./_Man_SunOS_4.1.3_html/html3/lwp

Manual page for LWP_CREATE(3L)

lwp_create, lwp_destroy, SAMETHREAD, pod_setexit, pod_getexit, pod_exit - LWP thread creation and destruction primitives

SYNOPSIS

#include <lwp/lwp.h>
#include <lwp/stackdep.h>

int lwp_create(tid, func, prio, flags, stack, nargs, arg1, ..., argn)
thread_t *tid;
void (*func)();
int prio;
int flags;
stkalign_t *stack;
int nargs;
int arg1, ..., argn;

int lwp_destroy(tid)
thread_t tid;

void pod_setexit(status)
int status;

int pod_getexit(status)
int status;

void pod_exit(status)
int status

SAMETHREAD(t1, t2)

DESCRIPTION

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 priorities 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 message 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 available 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, whenever 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 running one.

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 terminates 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 establishes 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 immediately, 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 equality.

RETURN VALUES

lwp_create(), and lwp_destroy() return:

0: on success.
-1: on failure.

pod_getexit() returns the current exit status of the pod.

ERRORS

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 exist.

WARNINGS

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.