The return stack and its uses

During compilation of a new word, FlashForth establishes links from the calling word to the previously-defined words that are to be invoked by execution of the new word. This linkage mechanism, during execution, uses the return stack (rstack). The address of the next word to be invoked is placed on the rstack so that, when the current word is done executing, the system knows where to jump to the next word. Since words can be nested, there needs to be a stack of these return addresses.

In addition to serving as the reservoir of return addresses, the return stack is where the counter for the for ... next construct is placed. (See section11.) The user can also store to and retrieve from the rstack but this must be done carefully because the rstack is critical to program execution. If you use the rstack for temporary storage, you must return it to its original state, or else you will probably crash the FlashForth system. Despite the danger, there are times when use of the rstack as temporary storage can make your code less complex.

To store to the rstack, use >r to move TOS from the parameter stack to the top of the rstack. To retrieve a value, r> moves the top value from the rstack to the parameter stack TOS. To simply remove a value from the top of the rstack there is the word rdrop. The word r@ copies the top of the rstack to the parameter stack TOS and is used to get a copy of the loop counter in a for loop discussed in Section11.