5.27 Threading Words

These words provide access to code addresses and other threading stuff in Gforth (and, possibly, other interpretive Forths). It more or less abstracts away the differences between direct and indirect threading (and, for direct threading, the machine dependences). However, at present this wordset is still incomplete. It is also pretty low-level; some day it will hopefully be made unnecessary by an internals wordset that abstracts implementation details away completely.

The terminology used here stems from indirect threaded Forth systems; in such a system, the XT of a word is represented by the CFA (code field address) of a word; the CFA points to a cell that contains the code address. The code address is the address of some machine code that performs the run-time action of invoking the word (e.g., the dovar: routine pushes the address of the body of the word (a variable) on the stack ).

In an indirect threaded Forth, you can get the code address of name with ' name @; in Gforth you can get it with ' name >code-address, independent of the threading method.

threading-method       – n        gforth       “threading-method”

0 if the engine is direct threaded. Note that this may change during the lifetime of an image.

>code-address       xt – c_addr         gforth       “>code-address”

c-addr is the code address of the word xt.

code-address!       c_addr xt –         gforth       “code-address!”

Create a code field with code address c-addr at xt.

For a word defined with DOES>, the code address usually points to a jump instruction (the does-handler) that jumps to the dodoes routine (in Gforth on some platforms, it can also point to the dodoes routine itself). What you are typically interested in, though, is whether a word is a DOES>-defined word, and what Forth code it executes; >does-code tells you that.

>does-code       xt – a_addr         gforth       “>does-code”

If xt is the execution token of a child of a DOES> word, a-addr is the start of the Forth code after the DOES>; Otherwise a-addr is 0.

To create a DOES>-defined word with the following basic words, you have to set up a DOES>-handler with does-handler!; /does-handler aus behind you have to place your executable Forth code. Finally you have to create a word and modify its behaviour with does-handler!.

does-code!       a_addr xt –         gforth       “does-code!”

Create a code field at xt for a child of a DOES>-word; a-addr is the start of the Forth code after DOES>.

does-handler!       a_addr –         gforth       “does-handler!”

Create a DOES>-handler at address a-addr. Normally, a-addr points just behind a DOES>.

/does-handler       – n         gforth       “/does-handler”

The size of a DOES>-handler (includes possible padding).

The code addresses produced by various defining words are produced by the following words:

docol:       – addr         gforth       “docol:”

The code address of a colon definition.

docon:       – addr         gforth       “docon:”

The code address of a CONSTANT.

dovar:       – addr         gforth       “dovar:”

The code address of a CREATEd word.

douser:       – addr         gforth       “douser:”

The code address of a USER variable.

dodefer:       – addr         gforth       “dodefer:”

The code address of a defered word.

dofield:       – addr         gforth       “dofield:”

The code address of a field.

The following two words generalize >code-address, >does-code, code-address!, and does-code!:

>definer       xt – definer         gforth       “>definer”

Definer is a unique identifier for the way the xt was defined. Words defined with different does>-codes have different definers. The definer can be used for comparison and in definer!.

definer!       definer xt –         gforth       “definer!”

The word represented by xt changes its behaviour to the behaviour associated with definer.