6.30.1.1 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

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

task ( ustacksize "name" –  ) gforth-experimental

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 “newtask-four”

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

u is the data stack size of the main task.

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

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

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

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

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

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

Terminate the current task.

kill ( task –  ) gforth-experimental

Terminate task.

Tasks can also temporarily stop themselves or be stopped:

halt ( task –  ) gforth-experimental

Stop task (no difference from sleep)

sleep ( task –  ) gforth-experimental

Stop task (no difference from halt)

stop ( –  ) gforth-experimental

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

stop-ns ( timeout –  ) gforth-experimental

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

stop-dns ( dtimeout –  ) gforth-experimental

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

thread-deadline ( d –  ) gforth-experimental

stop until absolute time d in nanoseconds, base is 1970-1-1 0:00 UTC, but you usually will want to base your deadlines on a time you get with ntime.

Using stop-dns is easier to code, but if you want your task to wake up at regular intervals rather than some time after it finished its last piece of work, the way to go is to work with deadlines.

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

wake ( task –  ) gforth-experimental

Wake task

restart ( task –  ) gforth-experimental

Wake task (no difference from wake)

There is also:

pause ( –  ) gforth-experimental

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.