TASK_$CREATE Domain/OS TASK_$CREATE
NAME
task_$create - create a task
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/task.h>
task_$handle_t task_$create(
void (*routine_pointer)(),
char *arg_pointer,
long arg_length,
long stack_size,
long task_priority,
task_$lifetime_t life_time,
task_$option_set_t task_options,
status_$t *status)
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/task.ins.pas';
function task_$create(
in routine_pointer: task_$routine_p;
in arg_pointer: univ_ptr;
in arg_length: integer32;
in stack_size: integer32;
in task_priority: integer32;
in life_time: task_$lifetime_t;
in task_options: task_$option_set_t;
out status: status_$t): task_$handle_t;
DESCRIPTION
Task_$create creates a new task and returns a handle for it.
Task_$create allocates stack_size bytes for the task's stack, then
creates an initial context by calling the routine that routine_pointer
points to.
routine_pointer
A pointer to the routine to run in the task. The task routine must
not return a value and must take two arguments: a pointer to an
argument vector, followed by the number of bytes in the argument
vector. The argument vector may contain anything.
In C, a valid task routine declaration is
void task_routine(
void *arg_pointer,
int arg_length)
In Pascal, a valid task routine declaration is
procedure task_routine(
in arg_ptr: univ_ptr;
in arg_len: integer32);
options(val_param);
arg_pointer
A pointer to the argument vector for the routine at routine_pointer.
The contents and format of the argument vector is not defined by the
task library. If arg_length is 0, arg_pointer is passed directly to
the routine at routine_pointer; otherwise, the argument vector is
copied from arg_pointer onto the stack for the created task, and the
task gets a pointer to that copy in its first argument.
arg_length
The number of bytes at arg_pointer to pass in the argument vector.
The value of arg_length is passed to the routine at routine_pointer
as its second argument when it is called.
stack_size
The number of bytes to allocate for the new task's stack. In gen-
eral, stack_size should be at least 64K bytes so it can accommodate
system calls, some of which require a large stack.
Task_$create increases the size of the stack to hold the argument
vector, so stack_size should not include the size of the argument
vector.
task_priority
The initial priority of the task. The priority levels are from 1 to
9, where 9 is the highest.
life_time
The lifetime of the new task. Specify one of the following values:
task_$forever
Create a task that lives independent of the process that
created it.
task_$until_level_exit
Create a task that lives until the level at which it was
created is released.
task_$until_exec_or_level_exit
Create a task that lives until the level at which it was
created is released or overlaid by a UNIX exec(2) call.
The system does not ensure that a task's code is available for the
duration of the task's lifetime; that is left up to the application.
Thus, if life_time is task_$forever, the task's code must exist in a
global library.
task_options
A small set of options when creating a new task. Currently there is
one option:
task_$intend_to_wait
Create a task completion eventcount that advances when the
created task terminates. When created with the
task_$intend_to_wait option, a task is suspended when it com-
pletes pending a task_$release call.
If task_$intend_to_wait is not specified in task_options - that is,
if task_options is 0 (or [] in Pascal) - then task_$create does not
create a completion eventcount. When created without the
task_$intend_to_wait option, a task is not suspended when it com-
pletes; instead it terminates immediately on completion, and the
completion status and output value of the task will not be accessi-
ble.
status
The completion status.
SEE ALSO
task_$get_ec, task_$release, task_$set_result.