Module "task"
=============

SPL Task Management Module

This module provides basic functions for handling SPL tasks. SPL tasks
may be used like threads, co-routines, or anything simmilar.
 
builtin task_create(name, code, ctx);
-------------------------------------

This function creates a new task. The 1st parameter is the name of the
new task and the 2nd is the SPL program code for the task. The 2nd
parameter will be compiled when executing the function, so it is a good
idea to keep it small and move the big portion of the task logic to
seperate functions. The third option is the context in which the task
should be executed.

If the task name is undefined, the task won't have a name attached to
it and it won't be possible to access it later.

If the context is ommitted, the task will run in the same context as
the function which called this function.
 

builtin task_pause(name);
-------------------------

This functions pauses the specified task until it is woken up by
task_continue() (or by an external event).

If the task name is ommitted, the current task will be affected by
this function.
 

builtin task_continue(name);
----------------------------

This function wakes up the specified task. It also can be used to
remove the SYSTEM flag from the current tast (see task_system()).

If the task name is ommitted, the current task will be affected by
this function.
 

builtin task_system(name);
--------------------------

This function sets the SYSTEM flag on the specified task. That means
that the scheduler will not schedule any other task until the system
flag is removed again using task_continue() or the task is paused
(task_pause()) or killed (task_kill()).

If the task name is ommitted, the current task will be affected by
this function. Usually this function is only used to manipulate the
currently running task.
 

builtin task_public(name);
--------------------------

This function is used to set the PUBLIC flag on a task. This is e.g.
needed when the task should be woken up by WebSPL when the taskname
is encoded into the session id.

If the task name is ommitted, the current task will be affected by
this function.
 

builtin task_getname();
-----------------------

Returns the name of the current task.
 

builtin task_check(name);
-------------------------

Returns 1 if the specified task exists and 0 otherwise.
 

function task_kill(name);
-------------------------

This function kills the specified task.

If the task name is ommitted, the current task will be affected by
this function.
 

function task_late_kill(name);
------------------------------

This function schedules the specified task to be killed. The task
will be killed when becomes paused the next time (e.g. because
task_pause() is called on it). If the task is already paused,
it will be killed emediatly.

If the task name is ommitted, the current task will be affected by
this function.
 

function task_switch(name);
---------------------------

This function pauses the current task and wakes up the specified one.
It is using task_system() to make the operation atomic and so avoid
race conditions.
 

function task_co_call(name);
----------------------------

This function is like, task_switch() but registers the current task as
co-routine caller. That means, when the specified task call
task_co_return(), the calling task will be woken up again and the
parameter to task_co_return() will be returned by this function.
 

function task_co_return(retval);
--------------------------------

Return to the task which switched to this task using task_co_call(). If
the current task was not entered using this mechanism, control is passed to
the task specified by task_co_setdefault(), or a runtime error is
triggered if no default has been defined.
 

function task_co_setdefault(name, def);
---------------------------------------

Set the task "def" as default task to be returned when the task "name"
calls task_co_return() was not entered thru task_co_call().
 

function task_eval(code, ctx);
------------------------------

An eval, implemented as own task. It is recommended to use the "eval"
statement instead. The only difference is that this function allows you to
specify a different function context in which the code should be executed.
 
