INTRO(3L)

NAME
intro - introduction to the lightweight process library (LWP)

DESCRIPTION

The lightweight process library (LWP) provides a mechanism to support multiple threads of control that share a single address space. Under SunOS, the address space is derived from a single forked (“heavyweight”) process. Each thread has its own stack segment (specified when the thread is created) so that it can access local variables and make procedure calls independently of other threads. The collection of threads sharing an address space is called a pod. Under SunOS, threads share all of the resources of the heavyweight process that contains the pod, including descriptors and signal handlers.

The LWP provides a means for creating and destroying threads, message exchange between threads, manipulating condition variables and monitors, handling synchronous exceptions, mapping asynchronous events into messages, mapping synchronous events into exceptions, arranging for special per-thread context, multiplexing the clock for timeouts, and scheduling threads both preemptively and non-preemptively.

The LWP system exists as a library of routines (/usr/lib/liblwp.a) linked in (-llwp) with a client program which should #include the file <lwp/lwp.h>. main is transparently converted into a lightweight process as soon as it attempts to use any LWP primitives.

When an object created by a LWP primitive is destroyed, every attempt is made to clean up after it. For example, if a thread dies, all threads blocked on sends to or receives from that thread are unblocked, and all monitor locks held by the dead thread are released.

Because there is no kernel support for threads at present, system calls effectively block the entire pod. By linking in the non-blocking I/O library (-lnbio) ahead of the LWP library, you can alleviate this problem for those system calls that can issue a signal when a system call would be profitable to try. This library (which redefines some system calls) uses asynchronous I/O and events (for example, SIGCHLD and SIGIO) to make blocking less painful. The system calls remapped by the nbio library are: open(2V), socket(2), pipe(2V), close(2V), read(2V), write(2V), send(2), recv(2), accept(2), connect(2), select (2) and wait(2V).

RETURN VALUES

LWP primitives return non-negative integers on success. On errors, they return -1. See lwp_perror(3L) for details on error handling.

FILES
/usr/lib/liblwp.a
/usr/lib/libnbio.a

SEE ALSO
accept(2), close(2V), connect(2), open(2V), pipe(2V), read(2V), recv(2), select(2), send(2), socket(2), wait(2V) write(2V),
Lightweight Processes in the

INDEX
The following are the primitives currently supported, grouped roughly by function.

  Thread Creation
lwp_self(tid)
lwp_getstate(tid, statvec)
lwp_setregs(tid, machstate)
lwp_getregs(tid, machstate)
lwp_ping(tid)
lwp_create(tid, pc, prio, flags, stack, nargs, arg1, ..., argn)
lwp_destroy(tid)
lwp_enumerate(vec, maxsize)
pod_setexit(status)
pod_getexit()
pod_exit(status)
SAMETHREAD(t1, t2)

  Thread Scheduling
pod_setmaxpri(maxprio)
pod_getmaxpri()
pod_getmaxsize()
lwp_resched(prio)
lwp_setpri(tid, prio)
lwp_sleep(timeout)
lwp_suspend(tid)
lwp_resume(tid)
lwp_yield(tid)
lwp_join(tid)

  Error Handling
lwp_geterr()
lwp_perror(s)
lwp_errstr()

  Messages
msg_send(tid, argbuf, argsize, resbuf, ressize)
msg_recv(tid, argbuf, argsize, resbuf, ressize, timeout)
MSG_RECVALL(tid, argbuf, argsize, resbuf, ressize, timeout)
msg_reply(tid)
msg_enumsend(vec, maxsize)
msg_enumrecv(vec, maxsize)

  Event Mapping (Agents)
agt_create(agt, event, memory)
agt_enumerate(vec, maxsize)
agt_trap(event)

  Thread Synchronization: Monitors
mon_create(mid)
mon_destroy(mid)
mon_enter(mid)
mon_exit(mid)
mon_enumerate(vec, maxsize)
mon_waiters (mid, owner, vec, maxsize)
mon_cond_enter(mid)
mon_break(mid)
MONITOR(mid)
SAMEMON(m1, m2)

  Thread Synchronization: Condition Variables
cv_create(cv, mid)
cv_destroy(cv)
cv_wait(cv)
cv_notify(cv)
cv_send(cv, tid)
cv_broadcast(cv)
cv_enumerate(vec, maxsize)
cv_waiters(cv, vec, maxsize)
SAMECV(c1, c2)

  Exception Handling
exc_handle(pattern, func, arg)
exc_unhandle()
(*exc_bound(pattern, arg))()
exc_notify(pattern)
exc_raise(pattern)
exc_on_exit(func, arg)
exc_uniqpatt()

  Special Context Handling
lwp_ctxinit(tid, cookie)
lwp_ctxremove(tid, cookie)
lwp_ctxset(save, restore, ctxsize, optimise)
lwp_ctxmemget(mem, tid, ctx)
lwp_ctxmemset(mem, tid, ctx)
lwp_fpset(tid)
lwp_libcset(tid)

  Stack Management
CHECK(location, result)
lwp_setstkcache(minsize, numstks)
lwp_newstk()
lwp_datastk(data, size, addr)
lwp_stkcswset(tid, limit)
lwp_checkstkset(tid, limit)
STKTOP(s)

BUGS
There is no language support available from C.
There is no kernel support yet. Thus system calls in different threads cannot execute in parallel.
Killing a process that uses the non-blocking I/O library may leave objects (such as its standard input) in a non-blocking state. This could cause confusion to the shell.

LIST OF LWP LIBRARY FUNCTIONS

Name	Appears on Page	Description