lwp_create, lwp_destroy, SAMETHREAD, pod_setexit, pod_getexit, pod_exit
- LWP thread creation and destruction primitives
int lwp_create(tid, func, prio, flags, stack, nargs, arg1, ..., argn)
int arg1, ..., argn;
lwp_create() creates a lightweight process which starts at address func
and has stack segment stack. If stack is NULL, the thread is created
in a suspended state (see below) and no stack or pc is bound to the
thread. prio is the scheduling priority of the thread (higher priori-
ties are favored by the scheduler). The identity of the new thread is
filled in the reference parameter tid. flags describes some options on
the new thread. LWPSUSPEND creates the thread in suspended state (see
lwp_yield(3L)). LWPNOLASTRITES will disable the LASTRITES agent mes-
sage when the thread dies. The default (0) is to create the thread in
running state with LASTRITES reporting enabled. LWPSERVER indicates
that a thread is only viable as long as non-LWPSERVER threads are
alive. The pod will terminate if the only living threads are marked
LWPSERVER and blocked on a lwp resource (for instance, waiting for a
message to be sent). nargs is the number (0 or more) of simple-type
(int) arguments supplied to the thread.
The first time a lwp primitive is used, the lwp library automatically
converts the caller (i.e., main) into a thread with the highest avail-
able scheduling priority (see pod_getmaxpri(3L)). The identity of this
thread can be retrieved using lwp_self (see lwp_status(3L)). This
thread has the normal SunOS stack given to any forked process.
Scheduling is, by default, non-preemptive within a priority, and within
a priority, threads enter the run queue on a FIFO basis (that is, when-
ever a thread becomes eligible to run, it goes to the end of the run
queue of its particular priority). Thus, a thread continues to run
until it voluntarily relinquishes control or an event (including thread
creation) occurs to enable a higher priority thread. Some primitives
may cause the current thread to block, in which case the unblocked
thread with the highest priority runs next. When several threads are
created with the same priority, they are queued for execution in the
order of creation. This order may not be preserved as threads yield
and block within a priority. If an agent owned by a thread with a
higher priority is invoked, that thread will preempt the currently run-
There is no concept of ancestry in threads: the creator of a thread has
no special relation to the thread it created. When all threads have
died, the pod terminates.
lwp_destroy() is a way to explicitly terminate a thread or agent
(instead of having an executing thread "fall though", which also termi-
nates the thread). tid specifies the id of the thread or agent to be
terminated. If tid is SELF, the invoking thread is destroyed. Upon
termination, the resources (messages, monitor locks, agents) owned by
the thread are released, in some cases resulting in another thread
being notified of the death of its peer (by having a blocking primitive
become unblocked with an error indication). A thread may terminate
itself explicitly, although self-destruction is automatic when it
returns from the procedure specified in the lwp_create() primitive.
pod_setexit() sets the exit status for a pod. This value will be
returned to the parent process of the pod when the pod dies (default is
0). exit(3) terminates the current thread, using the argument supplied
to exit to set the current value of the exit status. on_exit(3) estab-
lishes an action that will be taken when the entire pod terminates.
pod_exit() is available to terminate the pod immediately with the final
actions established by on_exit. If you wish to terminate the pod imme-
diately, pod_exit() or exit(2V) should be used.
pod_getexit() returns the current value of the pod's exit status.
SAMETHREAD() is a convenient predicate used to compare two threads for
lwp_create(), and lwp_destroy() return:
0 on success.
-1 on failure.
pod_getexit() returns the current exit status of the pod.
lwp_create() will fail if one or more of the following are true:
LE_ILLPRIO Illegal priority.
LE_INVALIDARG Too many arguments (> 512).
LE_NOROOM Unable to allocate memory for thread context.
lwp_destroy() will fail if one or more of the following are true:
LE_NONEXIST Attempt to destroy a thread or agent that does not
exit(2V), exit(3), lwp_yield(3L), on_exit(3), pod_getmaxpri(3L)
Some special threads may be created silently by the lwp library. These
include an idle thread that runs when no other activity is going on,
and a reaper thread that frees stacks allocated by lwp_newstk. These
special threads will show up in status calls. A pod will terminate if
these special threads are the only ones extant.
21 January 1990 LWP_CREATE(3L)