# SPL Module Reference: task

load "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);
builtin task_pause(name);
builtin task_continue(name);
builtin task_system(name);
builtin task_public(name);
builtin task_getname();
builtin task_check(name);

function task_kill(name);
function task_late_kill(name);
function task_switch(name);
function task_co_call(name);
function task_co_return(retval);
function task_co_setdefault(name, def);
function task_eval(code, ctx);

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.

Generated by SPLDOC. | http://www.clifford.at/spl/