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 task (no difference from sleep)
sleep ( task – ) gforth-experimental “sleep”
Stop task (no difference from halt)
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
stop-dns ( dtimeout – ) gforth-experimental “stop-dns”
Stop with timeout (in nanoseconds), better replacement for ms Stop with dtimeout (in nanoseconds), better replacement for ms
thread-deadline ( d – ) gforth-experimental “thread-deadline”
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”
Wake task
restart ( task – ) gforth-experimental “restart”
Wake task (no difference from wake)
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.