Fleet Forth design considerations

[JimBoyd]

I've cleaned up Fleet Forth's multitasker source. Fleet Forth has a round robin cooperative multitasker, although another type could be written. It only has support for the one main task with background tasks. Each task uses a portion of page one for its return stack and a portion of the area from address $02 to address $7E in page zero for its data stack. A task is a CREATE word, like a variable but with a larger parameter field. A task's user area is in its parameter field. A task's parameter field may also have room for a task to have its own PAD .
In this post, any mention of a task's return stack refers to the portion of the return stack used by the task. The same goes for mention of a task's data stack.
Here is the multitasking lexicon:

Code: Select all

(PAUSE)  ( -- )
ENTRY  ( -- ADR )
READY  ( -- ADR )
TOS  ( -- ADR )
MULTI  ( -- )
SINGLE  ( -- )
WAKE  ( TADR -- )
SLEEP  ( TADR -- )
LOCAL  ( TADR ADR1 -- ADR2 )
       ( ADR1 TADR -- ADR2 )
STOP  ( -- )
LINK-TASK  ( TASK -- )
UNLINK-ALL  ( -- )
UNLINK-TASK  ( TASK -- )
TASK  ( U SP0 RP0 -- )
ACTIVATE  ( TASK -- )

(PAUSE) is the task switcher. Here is the source:

Code: Select all

CODE (PAUSE)  ( -- )
   IP 1+ LDA  PHA       // IP ON RET
   IP LDA  PHA          //
   TXA  PHA             // SP ON RET
   TSX  TXA             // RP STORED
   4 # LDY  UP )Y STA   // IN TOS
   BEGIN
      0 # LDY
      UP )Y LDA  TAX  INY
      UP )Y LDA  UP 1+ STA  INY
      UP STX  UP )Y LDA
   0= NOT UNTIL
   4 # LDY  UP )Y LDA  TAX  TXS
   PLA  TAX
   ' EXIT @ JMP  END-CODE

The next three words, ENTRY , READY , and TOS are user variables with offsets 0, 2, and 4 respectively. These offsets are reserved in the Fleet Forth kernel for multitasking.
ENTRY points to the beginning, or entry, of the user area for the next task. READY has the logic value true if the task is "awake" and ready to go or false if it is "asleep", although (PAUSE) only checks the low byte. TOS is used to store a task's return stack pointer.
(PAUSE) saves the value of IP to the task's return stack as well as the value of the current task's data stack pointer. The return stack pointer is saved in the user variable TOS . (PAUSE) then follows ENTRY to the next task, testing READY until it finds a task which is awake. Once a task which is awake is found, its return stack pointer is fetched from TOS and stored in the S register and the data stack pointer is restored from the task's return stack. A jump to EXIT fetches the saved value of IP from the task's return stack and returns to NEXT to resume execution of the Forth thread for this task.

Code: Select all

0 USER ENTRY   2 USER READY
4 USER TOS
: MULTI  ( -- )
   READY ON
   ['] (PAUSE) IS PAUSE ;
: WAKE  ( TADR -- )  2+ ON ;
: SLEEP  ( TADR -- )  2+ OFF ;
: LOCAL  ( BASE ADR1 -- ADR2 )
   [ ASSEMBLER ] UP [ FORTH ]
   @ - + ;
: STOP  ( -- )
   BEGIN
      READY OFF  PAUSE
   AGAIN ; -2 ALLOT

MULTI assures the task executing it is "awake" (normally the main task) and sets the deferred word PAUSE to (PAUSE) . The counterpart of MULTI is SINGLE . It is the only word in the multitasker lexicon defined in Fleet Forth's kernel. SINGLE sets PAUSE to NOOP a no operation word. NOOP is a word without a parameter field. Its code field points to NEXT .
WAKE takes a task's address and wakes it up.
SLEEP takes a task's address and puts it to sleep.
LOCAL takes a task's address and the address returned by a user variable in the currently executing task (usually main) and returns the address of that user variable in the given task. For example, suppose there is a task named DUMMY1 . I can tell if DUMMY1 is awake or not with the phrase:

Code: Select all

DUMMY1 READY LOCAL ?

where ? displays the contents of an address. LOCAL has two stack comments because it doesn't matter whether it is used with the user variable address on top or the task address, it returns the same result.
STOP is used for a one-shot task, one which does not have an infinite loop. STOP puts the task to sleep then pauses. STOP has an infinite loop in the event that a stopped task is woken up inadvertently. The task will put itself back to sleep and pause the next time it runs.

Linking and unlinking:

Code: Select all

: LINK-TASK  ( TASK -- )
   DUP SLEEP
   ENTRY 2DUP @ SWAP! ! ;
: UNLINK-ALL  ( -- )
   [ ASSEMBLER UP @ ] LITERAL
   DUP UP !  ENTRY ! ;
: UNLINK-TASK  ( TASK -- )
   [ ASSEMBLER ] UP [ FORTH ]
   BEGIN
      @ DUP @
      [ ASSEMBLER ] UP [ FORTH ] @ =
      IF  2DROP EXIT  THEN
      DUP @ 2PICK =
   UNTIL
   SWAP @ SWAP! ;

LINK-TASK takes a task's address and puts it to sleep because a newly created task does not have anything to do and would "crash and burn" if awake. It then links the task into the round robin list of tasks. It is important that a task does not get linked into the round robin list more than once!
UNLINK-ALL , as its name implies, unlinks all the tasks by setting UP , Forth's user pointer, to the main task and setting ENTRY for the main task to point to itself. The ability to unlink all the tasks makes it safe to forget a task. I've read somewhere that once a task is created, it should not be forgotten. It seems to me that this would make prototyping harder with the need to leave the Forth system and reload it to remove background tasks. To provide a little more protection, FORGET switches off multitasking. If the need to forget a Forth word arises, one or more tasks may be forgotten in the process. It would be prudent to unlink all tasks before switching multitasking back on and link them back into the round robin list one at a time. A cold or warm start will unlink all tasks as a side effect of setting up the user area and user pointer. ABORT or any word which executes ABORT switches multitasking off.
UNLINK-TASK takes the address of a task and will unlink just that task from the round robin list of tasks. If the address on the stack is not the address of a task linked in the round robin list, UNLINK-TASK will, after traversing the list, exit without changing anything.

Task creation and activation:

Code: Select all

: TASK  ( U SP0 RP0 -- )
   CREATE
      HERE RP0 LOCAL !
      HERE SP0 LOCAL !
      // OPTIONAL
      10 HERE BASE LOCAL !
      HERE #USER + HERE DP LOCAL !
      10 UMAX ALLOT ;
: ACTIVATE  ( TASK -- )
   DUP WAKE
   R> OVER RP0 LOCAL @ 1- DUP>R !
   DUP SP0 LOCAL @ R@ 1- C!
   TOS LOCAL R> 2- SWAP! ;

As I said, TASK is a CREATE word, it returns the address of its parameter field. The definition of TASK has been changed. The original definition took three parameters, the size of the user area for the task being created, the size of its portion of data stack, and the size of its portion of return stack. There were some constants and values used to keep track of how much of the stacks were set aside for each task. With the ability to forget tasks, this would necessitate resetting the values used to keep track of the portion of the stacks set aside for the background tasks.
The new version of TASK also takes three parameters. The size of the user area for the task, the address of the base of the data stack for the task being created, and the address of the base of its return stack.
A task's parameter field will have room for at least five user variables, possibly more. The five required user variables are:
ENTRY , READY , TOS , RP0 , and SP0 . RP0 holds the address of the base of the return stack and SP0 holds the address of the base of the data stack. When a stack is created, its value of BASE is set to ten and its DP , dictionary pointer, is set to the address after the latest user variable.
ACTIVATE takes the address of a task and is used in a word to give a task something to do. Here is an example with two tasks. They both flash the border, but at different intervals.

Code: Select all

180 VALUE DELAY1 175 VALUE DELAY2
0 $1C $12F TASK DUMMY1
0 $38 $15F TASK DUMMY2
: FLASH1
   DUMMY1 ACTIVATE
   BEGIN
      $D020 C@ 1+ BORDER
      DELAY1 JIFFIES
   AGAIN ;
: FLASH2
   DUMMY2 ACTIVATE
   BEGIN
      $D020 C@ 1+ BORDER
      DELAY2 JIFFIES
   AGAIN ;

Code: Select all

SEE FLASH1
FLASH1
 7DB4 7D84 DUMMY1
 7DB6 7CB2 ACTIVATE
 7DB8  A35 LIT D020 
 7DBC 1298 C@
 7DBE 11BF 1+
 7DC0 455F BORDER
 7DC2 7D66 DELAY1
 7DC4 42A6 JIFFIES
 7DC6  BD0 BRANCH 7DB8 
16 
 OK

FLASH1 is executed from the main task. ACTIVATE wakes the task DUMMY1 . It then places the address $7DB8 on the task's return stack. The data stack pointer for DUMMY1 is then placed on its return stack. The adjusted return pointer for DUMMY1 is stored in its version of TOS . DUMMY1 is now ready for the Forth thread at address $7DB8 to run.

[JimBoyd]

I posted about Fleet Forth's cold and warm start routines here.
There was an error in the cold start routine in the section of C64 Kernal calls which has since been corrected.

Code: Select all

   FF87 JSR  // RAMTAS
   FF8A JSR  // RESTOR
   FFE7 JSR  // CLALL
   FF84 JSR  // IOINIT
   FF81 JSR  // CINT

The Commodore 64 Kernal routine CLALL clears the table of open files, but it also falls through to the CLRCHN routine. This routine restores the default input device (the keyboard) and the default output device (the screen). It will also send an UNTALK or UNLISTEN command if necessary. The problem is that the C64 routine RAMTAS clears the memory locations holding the necessary information.
Here is the corrected list of C64 Kernal calls.

Code: Select all

   FFE7 JSR  // CLALL
   FF87 JSR  // RAMTAS
   FF8A JSR  // RESTOR
   FF84 JSR  // IOINIT
   FF81 JSR  // CINT

I've never had a problem with this because I load and run Fleet Forth immediately after powerup, or in recent years immediately after starting the VICE C64 simulator.

[JimBoyd]

Fleet Forth has a word, DIGIT , which is not in the Forth-83 standard, but it is in Fig Forth, F83 and F-PC. DIGIT is a primitive which attempts to convert a character into a valid digit in the specified number base and returns the result and a flag.
In Fig Forth, DIGIT has the following stack effect.

Code: Select all

DIGIT  ( CHAR BASE -- N TRUE )
       ( CHAR BASE -- FALSE )

However, in F83 and F-PC it has this stack effect.

Code: Select all

DIGIT  ( CHAR BASE -- N TRUE )
       ( CHAR BASE -- CHAR FALSE )

I've also seen this stack effect where accessing the value of BASE is built in.

Code: Select all

DIGIT  ( CHAR -- N TRUE )
       ( CHAR -- CHAR FALSE )

Which version would be best for a Forth-83 Standard system such as Fleet Forth?
Of the first two versions, the Fig Forth version has the advantage that CONVERT does not need to discard the unneeded character when a nonconvertible character is encountered, thus saving one cell. On the other hand, the F83 and F-PC version could be more generally useful since it always returns two stack items. Here is an example from Inside F83 by C. H. Ting where the result of the conversion is not needed.

Code: Select all

: DIGIT? ( char -- f ) 
   BASE @ DIGIT 
   NIP ; 

The third version is the one I'm leaning toward. The built in access of BASE saves two cells in each word which uses DIGIT , making that word slightly smaller and faster. This change only makes DIGIT two bytes longer comparing the value in the accumulator with the value of BASE

Code: Select all

   ' BASE >BODY C@ # LDY
   UP )Y CMP

versus comparing it with the value on the top of the data stack.

Code: Select all

   0 ,X CMP

DIGIT? would then be

Code: Select all

DIGIT?  ( char -- f )
   DIGIT NIP ;

[Edit: Fixed some typos]

[GARTHWILSON]

I thought I'd look up what Starting Forth has to say about DIGIT since it often has foot notes telling the differences in figForth, Forth-79, Forth-83, etc.; but I was shocked to see it wasn't even there! I have DIGIT> which has the stack effect you show first.

[JimBoyd]

I've decided to change Fleet Forth's word DIGIT to have the third stack effect mentioned in my previous post.

Code: Select all

DIGIT  ( CHAR -- N TRUE )
       ( CHAR -- CHAR FALSE )

Code: Select all

CODE DIGIT  ( CHAR -- N TRUE )
            ( CHAR -- CHAR FALSE )
   SEC  0 ,X LDA  $30 # SBC
   ' FALSE @ CS NOT BRAN
   $A # CMP
   CS IF
      7 # SBC  $A # CMP
      ' FALSE @ CS NOT BRAN
   THEN
   ' BASE >BODY C@ # LDY
   UP )Y CMP
   ' FALSE @ CS BRAN
   0 ,X STA
   ' TRUE @ JMP END-CODE

DIGIT is a primitive and including the access of the value in BASE only makes it two bytes bigger than before. This change saves two cells, or four bytes, in CONVERT , the high level word which uses DIGIT .
Returning two stack items even when conversion is unsuccessful adds a cell to CONVERT for a DROP to discard the unconverted character when it branches out of its loop.

Code: Select all

: CONVERT  ( D1 ADR1 -- D2 ADR2 )
   1+
   BEGIN
      COUNT DIGIT         \ count base @ digit
   WHILE
      2SWAP BASE @ *
      SWAP BASE @ UM* D+
      ROT
      DPL @ 0< 1+ DPL +!
   REPEAT
   DROP 1- ;              \ 1- ;

The comments show the original lines.
As I mentioned in my previous post, having DIGIT always return two stack items makes it more generally useful. Although this change will make CONVERT two bytes bigger, if I only intended DIGIT to be used by CONVERT , I would have made it headerless.

[JimBoyd]

I mention Fleet Forth's word NUMBER? here. Back then it was named -NUMBER . I've managed to reduce the size of its body to 132 bytes.
I've tried two other versions. One is 122 bytes but requires the first character (after any leading conversion base specifier or minus sign) to be a valid digit. The following would all be valid numbers with this version:

Code: Select all

$0.1234
%234.5.8.
#-42.3
123.

And these would not be valid:

Code: Select all

$.1234
.1234
0.1..2
123...45

The other version also requires the first digit after any conversion specifier or minus sign to be a valid digit. It is only 116 bytes because it allows more than one valid non-digit punctuation character in a row. Here are examples of valid numbers with this version:

Code: Select all

$0.123.....56.
123...45.2..
#-137....2

[JimBoyd]

I have previously mentioned the word VALID? . This word is used to test if a non-digit character is valid punctuation for a number. It is a deferred word and by default is set to (VALID?) , which only recognizes the period ( . ) as valid punctuation in a double number. Since VALID? is a deferred word, what is accepted as valid punctuation for a number can be changed. Starting Forth mentions these as valid punctuation for a double number:

Code: Select all

, . / - :

Some of these, as well as other punctuation, could be added by using a new version of (VALID?) . Taking this into consideration, I have decided to use the version of NUMBER? which requires valid non-digit punctuation in a number be separated by at least one digit. I believe a typo would be less likely slip by as a valid number with the tighter restriction and that it is well worth the extra six bytes.
My fellow Forthwrites, am I being a bit too cautious? Is it worth the extra six bytes?

[barrym95838]

I say it's worth it, but you should just follow your gut ... any decision you make can be easily revised later.

[JimBoyd]

barrym95838 wrote:

I say it's worth it, but you should just follow your gut

Thanks.
This was one of those decisions where I could have gone either way, but leaned toward the more restrictive, and slightly larger, version of NUMBER? .

[JimBoyd]

I have previously made brief mention of Fleet Forth's word WHERE . It is used to display the location of an error when (ABORT") aborts with an error message. WHERE can be useful apart from (ABORT") to display an error message which is not known beforehand.
-SET is one example:

Code: Select all

: -SET  ( -- )
   WHERE
   R@ 2- @ >NAME CR RON ID. ROFF
   ."  NOT SET" ABORT ; -2 ALLOT

-SET is the vector for a new deferred word until a new vector is set with IS :

Code: Select all

' NOOP IS PAUSE
' (PAUSE) IS PAUSE
' (EMIT) IS EMIT

If the new deferred word, prior to being set to a new vector, is executed from the command line, -SET displays the odd message that EXECUTE is not set. When executed from within a high level Forth word, the message shows the name of the deferred word which is not set.
Another example is ?D , the word which checks the disk drive for an error condition after block read/write.

Code: Select all

: ?D  ( -- )
   $0F >SLF# (?D) 0EXIT
   WHERE
   CR ." DISK ERROR:" CR
   DEB S? ABORT ;  -2 ALLOT

WHERE displays where the error occurred. The message 'DISK ERROR:' is displayed, followed my the message in the Disk Error Buffer or DEB , which comes from the disk drive as a text string.
To get a better feel of what Fleet Forth error messages look like, here are some examples.
This one is an example of using PAD as a buffer for sector 10 of track 37 on disk 0 of the current drive to read (r/w flag value is 1) 256 bytes with the sector read/write word. Device 8 is a 1541 disk drive and does not have 37 tracks. I've added comments after the fact.

Code: Select all

8 DRIVE  OK              \ select device 8 as the current drive
DOPEN  OK                \ open current drive for block access
PAD 10 37 0 1 256 SR/W   \ try to read sector 10 of track 37
PAD 10 37 0 1 256 SR/W   \ this line shown by Fleet Forth in reverse video
                  ^^^^   
DISK ERROR:
66,ILLEGAL TRACK OR SECTOR,37,10

When WHERE shows the line in a screen or the text input buffer or an evaluated string, it shows that line in reverse video so it stands out. The carets ( ^ ) identify the text which caused the error.
Here are some errors due to (intentional) typos.
From the console:

Code: Select all

DECIMAL  OK
CR 1 2 + . 123OOPS 4 5 * . 
3 
CR 1 2 + . 123OOPS 4 5 * .
           ^^^^^^^
WHAT?

and from a screen:

Code: Select all

1 RAM LOAD 7 
SCR# 32769 LINE# 7 
2 5 + . 321OOPS  7 9 * .
        ^^^^^^^
WHAT?

Missing delimiter for a string:

Code: Select all

: TEST2 
CR ." START TEST2 TEST1 
CR ." START TEST2 TEST1
   ^^
" MISSING

and using a deferred word which has not been set:

Code: Select all

DEFER PWM  OK
: TEST  50 PWM ;  OK
TEST
TEST
^^^^
PWM NOT SET

Here is a screen shot of trying to forget a word protected by FORGET's internal 'fence'.

[JimBoyd]

JimBoyd wrote:

I've decided to change Fleet Forth's word DIGIT to have the third stack effect mentioned in my previous post.

Code: Select all

DIGIT  ( CHAR -- N TRUE )
       ( CHAR -- CHAR FALSE )

Code: Select all

CODE DIGIT  ( CHAR -- N TRUE )
            ( CHAR -- CHAR FALSE )
   SEC  0 ,X LDA  $30 # SBC
   ' FALSE @ CS NOT BRAN
   $A # CMP
   CS IF
      7 # SBC  $A # CMP
      ' FALSE @ CS NOT BRAN
   THEN
   ' BASE >BODY C@ # LDY
   UP )Y CMP
   ' FALSE @ CS BRAN
   0 ,X STA
   ' TRUE @ JMP END-CODE

I should have seen this before. I changed the jump at the end of DIGIT to a branch.

Code: Select all

CODE DIGIT  ( CHAR -- N TRUE )
            ( CHAR -- CHAR FALSE )
   SEC  0 ,X LDA  $30 # SBC
   PUSH.FALSE CS NOT BRAN
   $A # CMP
   CS IF
      7 # SBC  $A # CMP
      PUSH.FALSE CS NOT BRAN
   THEN
   ' BASE >BODY C@ # LDY
   UP )Y CMP
   PUSH.FALSE CS BRAN
   0 ,X STA
   PUSH.TRUE CS NOT BRAN
END-CODE

[JimBoyd]

JimBoyd wrote:

My fellow Forthwrites, am I being a bit too cautious? Is it worth the extra six bytes?

It's actually eight bytes. Here is the source for both versions of NUMBER? . Just a reminder that DIGIT takes a character, it accesses the value of BASE internally, and returns either:
1) The numerical value of the digit and a true flag.
2) The character if it is not a valid digit and a false flag.
NUMBER? takes the address of a counted string which is followed by a trailing blank and returns a double number and a flag. The flag is true for a successful conversion. NUMBER? also sets the user variable DPL to the count of how many digit characters occur after the last valid punctuation character, or TRUE (-1) if there is no punctuation in the numeric string.
The larger stricter version:

Code: Select all

: NUMBER?  ( ADR -- D FLAG )
   RB
   DUP 1+ C@ ASCII # - DUP 3 U<
   IF
      BASE.TABLE + C@ BASE !
      1+ DUP
   THEN
   DROP
   DPL ON  0 0 ROT
   1+
   COUNT ASCII - <> DUP>R +
   COUNT DIGIT NIP >R
   2-
   BEGIN
      CONVERT DUP C@ VALID?
   WHILE
      DPL OFF
      DUP 1+ C@ VALID?
   UNTIL
   THEN
   C@ BL =  R> AND
   R>  ?EXIT
   >R DNEGATE R> ;

The smaller and less strict version:

Code: Select all

: NUMBER?  ( ADR -- D FLAG )
   RB
   DUP 1+ C@ ASCII # - DUP 3 U<
   IF
      BASE.TABLE + C@ BASE !
      1+ DUP
   THEN
   DROP
   DPL ON  0 0 ROT
   1+
   COUNT ASCII - <> DUP>R +
   COUNT DIGIT NIP >R
   2-
   BEGIN
      CONVERT DUP C@ VALID?
   WHILE
      DPL OFF
   REPEAT
   C@ BL =  R> AND
   R>  ?EXIT
   >R DNEGATE R> ;

[JimBoyd]

I previously mentioned fixing Fleet Forth's multitasking support in the kernel. This allows PAUSE to execute while the user is typing at Forth's command line, or even just thinking about what to type. It's nice when your background tasks don't freeze while you're sitting at the keyboard thinking.
If round robin multitasking will not be used, to avoid splitting the stacks into smaller areas for each task, PAUSE can be vectored to a 'run to completion' word. There are two caveats. Any word PAUSE is vectored to must leave the stacks as they were when it began. It, and all the words it executes, must not execute PAUSE to avoid runaway recursion.
Background tasks normally execute PAUSE to switch tasks. In that case PAUSE is vectored to an actual task switcher.
The following Fleet Forth words execute PAUSE directly or indirectly through another word.

Code: Select all

TYPE
QTYPE
KEY
(EXPECT)
INTERPRET
QUIT
DJIFFIES
JIFFIES

As well as any word which displays text, with the exception of EMIT since it displays a single character.
The error handling words ( ABORT ABORT" WHERE ) also execute PAUSE by way of TYPE but, they should not be in a background task. ABORT and ABORT" switch off any kind of multitasking by executing SINGLE , setting PAUSE to the no-op NOOP .

The following will cycle the border through all sixteen colors.

Code: Select all

: BORDER?  ( -- B )
   $D020 C@ ;
: CYCLE  ( -- )
   BORDER? 1+ BORDER ;
' CYCLE IS PAUSE

Something like the cyclic executive Garth mentions can be set up easily:

Code: Select all

: BACKGROUND
   TASK1
   TASK2
   TASK3
   TASK4 ;
' BACKGROUND IS PAUSE

What is missing is a way for a 'task' to run to a certain stopping point and resume where it left off. Leo Brodie's DOER/MAKE could be used. I propose a little structure of my own, inspired by DOER/MAKE, halting colon definitions. One of these runs to the halting point, where it exits. It resumes where it left off.

Code: Select all

: H:
   :  ( -- ADR TRUE )
      HERE 2+ ,
      [ HERE 2+ >A ]
   DOES>  ( -- )
      @ >R ;
: (HALT)  ( -- )
          ( R: ADR -- )
   R@ 2+  R> @ >BODY ! ;
: HALT
   LATEST NAME> @ [ A> ] LITERAL <>
   ABORT" NON HALTING WORD"
   COMPILE (HALT)  [COMPILE] RECURSE
   ; IMMEDIATE

Or if an auxiliary stack is not available, a pair of free zero page locations can be used.

Code: Select all

: H:
   :  ( -- ADR TRUE )
      HERE 2+ ,
      [ HERE 2+ 2 ! ]
   DOES>  ( -- )
      @ >R ;
: (HALT)  ( -- )
          ( R: ADR -- )
   R@ 2+  R> @ >BODY ! ;
: HALT
   LATEST NAME> @ [ 2 @ ] LITERAL <>
   ABORT" NON HALTING WORD"
   COMPILE (HALT)  [COMPILE] RECURSE
   ; IMMEDIATE

Here is a test halting word.

Code: Select all

H: HTEST  ( -- )
   BEGIN
      CR ." STARTING HTEST" HALT
      CR ." MIDDLE OF HTEST" HALT
      CR ." END OF HTEST" HALT
   AGAIN ;

Each time HTEST executes, it displays one of the messages and exits.

Code: Select all

HTEST
STARTING HTEST OK
HTEST
MIDDLE OF HTEST OK
HTEST
END OF HTEST OK
HTEST
STARTING HTEST OK

Here is an example without a BEGIN AGAIN loop.

Code: Select all

H: TEST2  ( -- )
   CR ." BEFORE HALTING." HALT
   CR ." AFTER HALTING." ;

The very first time it is executed, it will display the message "BEFORE HALTING" and every time after that it will, when executed, display "AFTER HALTING" .
Here is what gets compiled for TEST2 .

Code: Select all

' TEST2 >BODY :DIS 
 22937 22939 
 22939  7024 CR
 22941  6724 (.") BEFORE HALTING.
 22959 22754 (HALT)
 22961 22935 TEST2
 22963  7024 CR
 22965  6724 (.") AFTER HALTING.
 22982  2930 EXIT
47 
 OK

Halting colon definitions even support recursion.

Code: Select all

H: TEST  ( N -- N )
   BEGIN
      CR DUP SPACES ." BEGIN"
      1+ DUP 4 <
      IF  RECURSE  THEN
      HALT
      CR DUP SPACES ." MIDDLE"
      1+ DUP 6 <
      IF  RECURSE  THEN
      HALT
      CR DUP SPACES ." END"
      1- DUP 0< 0=
      IF  RECURSE  THEN
      HALT
   AGAIN ;

Code: Select all

0 TEST
BEGIN
 BEGIN
  BEGIN
   BEGIN OK
TEST
    MIDDLE
     MIDDLE OK
TEST
      END
     END
    END
   END
  END
 END
END OK
. 0  OK

If PAUSE is set to a halting colon definition, or a regular colon definition which executes more than one halting colon definition, the halting colon definition(s) will perform an action each time PAUSE is executed. This may be too frequent. Garth also mentioned alarms. An interval timer would be nice. How about the down-counter by Tim Hendtlass?
Here is DOWN-COUNTER for Fleet Forth.

Code: Select all

: DOWN-COUNTER
   2VARIABLE  ( -- )
   DOES>  ( -- ADR )
      JIFFY@ DROP
      OVER 2+ @
      OVER -  0 MIN
      2PICK +!
      OVER 2+ ! ;

That '0 MIN' is to handle the case when the jiffy timer resets to zero when it reaches twenty four hours.
A down-counter, a child word of DOWN-COUNTER , has two cells of storage. The first cell holds a value. The second cell holds the low cell of the Commodore 64 jiffy clock from the last time the down-counter was executed. Each time a down-counter is executed the amount of time, in jiffies, which passed from the last time is subtracted from the value in the first cell.

Code: Select all

DOWN-COUNTER DELAY1 OK
300 DELAY1 ! OK
DELAY1 ? 209  OK
DELAY1 ? 118  OK
DELAY1 ? 5  OK
DELAY1 ? -445  OK

Of course, the values returned each time I type "DELAY1 ?" depends on how long I wait.
Here is sample code to cycle the Commodore 64 border and cursor colors through predetermined values without an actual multitasker other than PAUSE built into certain kernel words. It cycles the colors while I'm still able to use Fleet Forth for other things.

Code: Select all

DOWN-COUNTER DELAY1
H: CYCLE-INK  ( -- )
   BEGIN
      DELAY1 @ 0< 0EXIT
      GREEN INK
      60 DELAY1 !  HALT
      DELAY1 @ 0< 0EXIT
      BROWN INK
      120 DELAY1 !  HALT
      DELAY1 @ 0< 0EXIT
      BLACK INK
      180 DELAY1 !  HALT
   AGAIN ;

DOWN-COUNTER DELAY2
H: CYCLE-BORDER  ( -- )
   BEGIN
      DELAY2 @ 0< 0EXIT
      GREEN BORDER
      30 DELAY2 !  HALT
      DELAY2 @ 0< 0EXIT
      CYAN BORDER
      90 DELAY2 !  HALT
      DELAY2 @ 0< 0EXIT
      YELLOW BORDER
      60 DELAY2 !  HALT
   AGAIN ;

: CYCLE  ( -- )
   CYCLE-INK  CYCLE-BORDER ;

' CYCLE IS PAUSE

Maybe halting colon definitions, or halting words, will be useful outside the realm of simulated multitasking, I don't know. Which will be more useful, halting words or DOER/MAKE? I don't know that either.

Note: My first attempt to port halting words to Blazin' Forth did not work. Blazin' Forth's word ] doesn't just change to the compiling state, it is the colon compiler. As a result, when Blazin' Forth's ] executes, parsing of the text stream and compiling begin immediately.
The only workaround I could come up with was to incorporate the functionality of : into H: without compiling : directly.

Code: Select all

: H:                       \ nothing placed on stack?
   CREATE                  \ create a new header 
      SMUDGE               \ hide name
      CURRENT @ CONTEXT !  \ set CONTEXT equal to CURRENT
      !CSP                 \ Blazin' Forth checks for a change in stack depth
      HERE 2+ ,            \ allocate and initialize one cell of storage
      ]                    \ include this AFTER everything up to DOES>
   DOES>
      @ >R ;

The test to make sure HALT is not used in normal colon definitions was left out of the version ported to Blazin' Forth. Because of the way Blazin' Forth handles compilation, it is not easy to test if a new definition is a child of H: until after the first line of text is parsed from the keyboard or until the block it is defined in is finished.

CREATE is used in both Fleet Forth and Blazin' Forth by all the words which create a header. It is basically VARIABLE without storage allotted.

Code: Select all

\ Fleet Forth's VARIABLE
: VARIABLE 
   CREATE  0 , ;

In regards to round robin multitasking, the problem with dividing the stacks so each task gets a portion is that it limits the number of tasks, as the background task's portion of the return stack has to have room for the nesting of that task and also for interrupts. One possibility is to have round robin multitasking with fewer background tasks. One or more background tasks could be a cyclic executive. The cyclic executive would need to be in a loop and include PAUSE .
Something like the following should work, but I haven't tested this yet.

Code: Select all

\ define some halting words.
H: BG1 ... ;
H: BG2 ... ;
H: BG3 ... ;
0 $20 $13F TASK BACKGROUND
: CYCLE
   BACKGROUND ACTIVATE
   BEGIN
      BG1  BG2  BG3  PAUSE
   AGAIN ;
BACKGROUND LINK-TASK
\ define and link other tasks
   ...
\ switch on multitasking
MULTI

[SamCoVT]

JimBoyd wrote:

What is missing is a way for a 'task' to run to a certain stopping point and resume where it left off. Leo Brodie's DOER/MAKE could be used. I propose a little structure of my own, inspired by DOER/MAKE, halting colon definitions. One of these runs to the halting point, where it exits. It resumes where it left off.

Code: Select all

: H:
   :  ( -- ADR TRUE )
      HERE 2+ ,
      [ HERE 2+ >A ]
   DOES>  ( -- )
      @ >R ;

You are breaking my brain (in a good way, I think). I was not aware you could put : in a colon definition (I would normally use CREATE, but I can see how they are different). Now that I think about it, of course you can do that. Forth lets you run with scissors by holding on to the sharp parts if you want.

Once I made it past that part, I see your DOES> pulls the address you left off (stored right at the beginning of the word's definition) at and puts it on the return stack just before the ; That immediately made me cringe because I've spent too many hours trying to balance my stores and fetches on the return stack, but of course you want that here. That's where it will "return" to and ; will bring you there. It's just like the co-routine code you showed earlier. It reminds me that >R and ; are just tools that can be used in any order if the resulting behavior is your desired behavior.

The rest was pretty easy to understand, once you understood what this part does. I haven't noodled my way all the way through your example yet, but I find it very interesting. Also, bonus points for showing off you auxiliary stack. I wrote one, but haven't really used it too much.

[JimBoyd]

SamCoVT wrote:

You are breaking my brain (in a good way, I think). I was not aware you could put : in a colon definition (I would normally use CREATE, but I can see how they are different). Now that I think about it, of course you can do that. Forth lets you run with scissors by holding on to the sharp parts if you want.

The reason for including : in the definition of H: is to include the compile time functionality of colon ( : ). In Fleet Forth this means creating a name and smudging it, setting the CONTEXT vocabulary equal to the CURRENT vocabulary, placing on the control flow stack (data stack) the same parameters as colon, and setting the state to compiling. Since Fleet Forth is an ITC Forth, this is not a problem. All words in Fleet Forth have a two byte code field, no exceptions. Even the child words of a CREATE DOES> word have a two byte code field.
In Fleet Forth, colon executes CREATE , which lays down the code field for do-variable. Colon overwrites that code field with do-colon. H: overwrites the code field with do-does. Do-does uses the Forth virtual machine W register to find the address to leave on the data stack and the high level code to push in the Forth virtual machine's IP register.
As an example, here is the source for Fleet Forth's 2CONSTANT , it is a CREATE DOES> word rather than a CREATE ;CODE word because it isn't used much.

Code: Select all

: 2CONSTANT
   CREATE , , DOES>
      2@ ;

And here is what gets compiled.

Code: Select all

SEE 2CONSTANT
2CONSTANT
 11961  8866 CREATE
 11963  7932 ,
 11965  7932 ,
 11967  8025 DOES
 11969  9483    JMP ' DOES> >BODY 21 +
 11972  4762 2@
 11974  2930 EXIT
15 
 OK

DOES> compiles DOES and a jump to do-does, which saves the contents of IP to the return stack and fetches the address from W with an offset of 3 (to skip over the JMP) and places it in IP .

Code: Select all

9483 DIS 
  9483   252    LDA IP 1+
  9485          PHA
  9486   251    LDA IP
  9488          PHA
  9489          CLC
  9490   254 )Y LDA  W
  9492     3  # ADC
  9494   251    STA IP
  9496          INY
  9497   254 )Y LDA  W
  9499     0  # ADC
  9501   252    STA IP 1+
  9503  9032    JMP ' CREATE >BODY 164 +
23 
 OK

Then jumps to do-variable.

Code: Select all

9032 DIS 
  9032          CLC
  9033     2  # LDA
  9035   254    ADC  W
  9037          PHA
  9038     0  # LDA
  9040   255    ADC  W 1+
  9042  2632    JMP PUSH
13 
 OK

As I showed in the listing for the version of H: for Blazin' Forth, because Blazin' Forth's ] is the compiler as well as changing state to compiling, it was necessary to use CREATE and include what Blazin' Forth's : does at compile time.
Since Tali Forth is an STC Forth, I ported H: and HALT to Durex Forth version 1.6.3 which is, from what I've seen, a subroutine threaded Forth. Colon words have no code field, but CREATE words have a five byte code field. The first three bytes are a JSR to its equivalent of do-does. The next two bytes are a pointer to the high level forth to execute.
This is the source for the port to Durex Forth.

Code: Select all

\ halting words
create dummy
: h:
   :
      ['] dummy dup c@ c, 1+ @ , 0 ,
      here 1+ , 
   does>
      @ >r ;
: (halt)
   r@ 3 + r> 2+ @ 5 + ! ;
: halt
   postpone (halt) postpone recurse ;
   immediate

\ for demos
: spaces  ( +n -- )
   0 max spaces ;

I was able to include colon to do at compile time, whatever Durex Forth's colon does. I first had to define a dummy CREATE word so I could build up a duplicate of it's code field. I duplicated the JSR and padded the last two bytes with zero. That gets patched by whatever DOES> compiles in Durex Forth.
Notice how (halt) has become more complicated.
I left out the error checking which would abort if HALT were used in a regular colon definition. This was to keep the code to a bare minimum for clarity.
I don't know how Tali Forth's CREATE words differ from Durex Forth's, so caution is advised.
I would also like to mention that Durex Forth's version of SEE was practically useless for investigating H: words. However, Durex Forth does have DUMP , which was indispensable.

Quote:

Once I made it past that part, I see your DOES> pulls the address you left off (stored right at the beginning of the word's definition) at and puts it on the return stack just before the ; That immediately made me cringe because I've spent too many hours trying to balance my stores and fetches on the return stack, but of course you want that here. That's where it will "return" to and ; will bring you there. It's just like the co-routine code you showed earlier. It reminds me that >R and ; are just tools that can be used in any order if the resulting behavior is your desired behavior.

Wait till you see Dynamically Structured Codes by M. L. Gassanenko.