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 OS/MP, 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 OS/MP, 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 Solbourne System Services Overview

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

NameAppears on PageDescription
agt_createagt_create(3L) map LWP events into messages
agt_enumerateagt_create(3L) map LWP events into messages
agt_trapagt_create(3L) map LWP events into messages
CHECKlwp_newstk(3L) LWP stack management
cv_broadcastcv_create(3L) manage LWP condition variables
cv_createcv_create(3L) manage LWP condition variables
cv_destroycv_create(3L) manage LWP condition variables
cv_enumeratecv_create(3L) manage LWP condition variables
cv_notifycv_create(3L) manage LWP condition variables
cv_sendcv_create(3L) manage LWP condition variables
cv_waitcv_create(3L) manage LWP condition variables
cv_waiterscv_create(3L) manage LWP condition variables
exc_boundexc_handle(3L) LWP exception handling
exc_handleexc_handle(3L) LWP exception handling
exc_notifyexc_handle(3L) LWP exception handling
exc_on_exitexc_handle(3L) LWP exception handling
exc_raiseexc_handle(3L) LWP exception handling
exc_unhandleexc_handle(3L) LWP exception handling
exc_uniqpattexc_handle(3L) LWP exception handling
lwp_checkstksetlwp_newstk(3L) LWP stack management
lwp_createlwp_create(3L) LWP thread creation and destruction primitives
lwp_ctxinitlwp_ctxinit(3L) special LWP context operations
lwp_ctxmemgetlwp_ctxinit(3L) special LWP context operations
lwp_ctxmemsetlwp_ctxinit(3L) special LWP context operations
lwp_ctxremovelwp_ctxinit(3L) special LWP context operations
lwp_ctxsetlwp_ctxinit(3L) special LWP context operations
lwp_datastklwp_newstk(3L) LWP stack management
lwp_destroylwp_create(3L) LWP thread creation and destruction primitives
lwp_enumeratelwp_status(3L) LWP status information
lwp_errstrlwp_perror(3L) LWP error handling
lwp_fpsetlwp_ctxinit(3L) special LWP context operations
lwp_geterrlwp_perror(3L) LWP error handling
lwp_getregslwp_status(3L) LWP status information
lwp_getstatelwp_status(3L) LWP status information
lwp_joinlwp_yield(3L) control LWP scheduling
lwp_libcsetlwp_ctxinit(3L) special LWP context operations
lwp_newstklwp_newstk(3L) LWP stack management
lwp_perrorlwp_perror(3L) LWP error handling
lwp_pinglwp_status(3L) LWP status information
lwp_reschedlwp_yield(3L) control LWP scheduling
lwp_resumelwp_yield(3L) control LWP scheduling
lwp_selflwp_status(3L) LWP status information
lwp_setprilwp_yield(3L) control LWP scheduling
lwp_setregslwp_status(3L) LWP status information
lwp_setstkcachelwp_newstk(3L) LWP stack management
lwp_sleeplwp_yield(3L) control LWP scheduling
lwp_stkcswsetlwp_newstk(3L) LWP stack management
lwp_suspendlwp_yield(3L) control LWP scheduling
lwp_yieldlwp_yield(3L) control LWP scheduling
MINSTACKSZlwp_newstk(3L) LWP stack management
mon_breakmon_create(3L) LWP routines to manage critical sections
mon_cond_entermon_create(3L) LWP routines to manage critical sections
mon_createmon_create(3L) LWP routines to manage critical sections
mon_destroymon_create(3L) LWP routines to manage critical sections
mon_entermon_create(3L) LWP routines to manage critical sections
mon_enumeratemon_create(3L) LWP routines to manage critical sections
mon_exitmon_create(3L) LWP routines to manage critical sections
mon_waitersmon_create(3L) LWP routines to manage critical sections
MONITORmon_create(3L) LWP routines to manage critical sections
msg_enumrecvmsg_send(3L) LWP send and receive messages
msg_enumsendmsg_send(3L) LWP send and receive messages
msg_recvmsg_send(3L) LWP send and receive messages
MSG_RECVALLmsg_send(3L) LWP send and receive messages
msg_replymsg_send(3L) LWP send and receive messages
msg_sendmsg_send(3L) LWP send and receive messages
pod_exitlwp_create(3L) LWP thread creation and destruction primitives
pod_getexitlwp_create(3L) LWP thread creation and destruction primitives
pod_getmaxpripod_getmaxpri(3L) control LWP scheduling priority
pod_getmaxsizepod_getmaxpri(3L) control LWP scheduling priority
pod_setexitlwp_create(3L) LWP thread creation and destruction primitives
pod_setmaxpripod_getmaxpri(3L) control LWP scheduling priority
SAMECVcv_create(3L) manage LWP condition variables
SAMEMONmon_create(3L) LWP routines to manage critical sections
SAMETHREADlwp_create(3L) LWP thread creation and destruction primitives
STKTOPlwp_newstk(3L) LWP stack management

Solbourne Computer, Inc.  —  18 Dec 1990