Basic multi-tasking

Tasks can be created with newtask or newtask4 with a given amount of stack space (either all the same or each stack’s size specified).

newtask ( stacksize – task  ) gforth-experimental “newtask”

creates task; each stack (data, return, FP, locals) has size stacksize.

task ( ustacksize "name" –  ) gforth-experimental “task”

creates a task name; each stack (data, return, FP, locals) has size ustacksize.
name execution: ( – task )

newtask4 ( u-data u-return u-fp u-locals – task  ) gforth-experimental “newtask4”

creates task with data stack size u-data, return stack size u-return, FP stack size u-fp and locals stack size u-locals.

If you don’t know which stack sizes to use for the task, you can use the size(s) of the main task:

stacksize ( – u  ) gforth-experimental “stacksize”

u is the data stack size of the main task.

stacksize4 ( – u-data u-return u-fp u-locals  ) gforth-experimental “stacksize4”

Pushes the data, return, FP, and locals stack sizes of the main task.

A task is created in an inactive state. To let it run, you have to activate it with one of the following words:

initiate ( xt task –  ) gforth-experimental “initiate”

Let task execute xt. Upon return from the xt, the task terminates itself (VFX compatible). Use one-time executable closures to pass arbitrary paramenters to a task.

The following legacy words provide the same functionality as initiate, but with a different interface: Like does>, they split their containing colon definition in two parts: The part before activate/pass runs in the activating task, and returns to its caller after activating the task. The part behind activate/pass is executed in the activated target task.

activate ( run-time nest-sys1 task –  ) gforth-experimental “activate”

Let task perform the code behind activate, and return to the caller of the word containing activate. When the task returns from the code behind activate, it terminates itself.

pass ( x1 .. xn n task –  ) gforth-experimental “pass”

Pull x1 .. xn n from the current task’s data stack and push x1 .. xn on task’s data stack. Let task perform the code behind pass, and return to the caller of the word containing pass. When the task returns from the code behind pass, it terminates itself.

You can also do creation and activation in one step:

execute-task ( xt – task  ) gforth-experimental “execute-task”

Create a new task task with the same stack sizes as the main task. Let task execute xt. Upon return from the xt, the task terminates itself.

Apart from terminating by running to the end, a task can terminate itself with kill-task. Other tasks can terminate it with kill.

kill-task ( ) gforth-experimental “kill-task”

Terminate the current task.

kill ( task –  ) gforth-experimental “kill”

Terminate task.

Tasks can also temporarily stop themselves or be stopped:

halt ( task –  ) gforth-experimental “halt”

Stop a task

stop ( ) gforth-experimental “stop”

stops the current task, and waits for events (which may restart it)

stop-ns ( timeout –  ) gforth-experimental “stop-ns”

Stop with timeout (in nanoseconds), better replacement for ms

A task restarts when the timeout is over or when another task wakes it with:

restart ( task –  ) gforth-experimental “restart”

Wake a task

There is also:

pause ( ) gforth-experimental “pause”

voluntarily switch to the next waiting task (pause is the traditional cooperative task switcher; in the pthread multitasker, you don’t need pause for cooperation, but you still can use it e.g. when you have to resort to polling for some reason). This also checks for events in the queue.