INTRO(3L) — LIGHTWEIGHT PROCESSES LIBRARY

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(2), close(2), read(2V), write(2V), send(2), recv(2), accept(2), connect(2), select(2), wait(2)

RETURN VALUES

LWP primitives return −1 on errors. Upon success, a non-negative integer is returned. See lwp_perror(3L) for details on error handling.

FILES

/usr/lib/liblwp.a

/usr/lib/libnbio.a

/usr/include/lwp/check.h

/usr/include/lwp/lwp.h

/usr/include/lwp/lwperror.h

/usr/include/lwp/lwpmachdep.h

/usr/include/lwp/stackdep.h

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_create()agt_create(3L) map LWP events into messages
agt_enumerate()agt_create(3L) map LWP events into messages
agt_trap()agt_create(3L) map LWP events into messages
CHECK()lwp_newstk(3L) LWP stack management
cv_broadcast()cv_create(3L) manage LWP condition variables
cv_create()cv_create(3L) manage LWP condition variables
cv_destroy()cv_create(3L) manage LWP condition variables
cv_enumerate()cv_create(3L) manage LWP condition variables
cv_notify()cv_create(3L) manage LWP condition variables
cv_send()cv_create(3L) manage LWP condition variables
cv_wait()cv_create(3L) manage LWP condition variables
cv_waiters()cv_create(3L) manage LWP condition variables
exc_bound()exc_handle(3L) LWP exception handling
exc_handle()exc_handle(3L) LWP exception handling
exc_notify()exc_handle(3L) LWP exception handling
exc_on_exit()exc_handle(3L) LWP exception handling
exc_raise()exc_handle(3L) LWP exception handling
exc_unhandle()exc_handle(3L) LWP exception handling
exc_uniqpatt()exc_handle(3L) LWP exception handling
lwp_checkstkset()lwp_newstk(3L) LWP stack management
lwp_create()lwp_create(3L) LWP thread creation and destruction primitives
lwp_ctxinit()lwp_ctxinit(3L) special LWP context operations
lwp_ctxremove()lwp_ctxinit(3L) special LWP context operations
lwp_ctxset()lwp_ctxinit(3L) special LWP context operations
lwp_ctxmemget()lwp_ctxinit(3L) special LWP context operations
lwp_ctxmemset()lwp_ctxinit(3L) special LWP context operations
lwp_destroy()lwp_create(3L) LWP thread creation and destruction primitives
lwp_enumerate()lwp_status(3L) LWP status information
lwp_errstr()lwp_perror(3L) LWP error handling
lwp_fpset()lwp_ctxinit(3L) special LWP context operations
lwp_geterr()lwp_perror(3L) LWP error handling
lwp_getstate()lwp_status(3L) LWP status information
lwp_setregs()lwp_status(3L) LWP status information
lwp_getregs()lwp_status(3L) LWP status information
lwp_ping()lwp_status(3L) LWP status information
lwp_join()lwp_yield(3L) control LWP scheduling
lwp_libcset()lwp_ctxinit(3L) special LWP context operations
lwp_newstk()lwp_newstk(3L) LWP stack management
lwp_datastk()lwp_newstk(3L) LWP stack management
lwp_perror()lwp_perror(3L) LWP error handling
lwp_resched()lwp_yield(3L) control LWP scheduling
lwp_resume()lwp_yield(3L) control LWP scheduling
lwp_self()lwp_status(3L) LWP status information
lwp_setpri()lwp_yield(3L) control LWP scheduling
lwp_setstkcache()lwp_newstk(3L) LWP stack management
lwp_sleep()lwp_yield(3L) control LWP scheduling
lwp_stkcswset()lwp_newstk(3L) LWP stack management
lwp_suspend()lwp_yield(3L) control LWP scheduling
lwp_yield()lwp_yield(3L) control LWP scheduling
MINSTACKSZ()lwp_newstk(3L) LWP stack management
mon_break()mon_create(3L) LWP routines to manage critical sections
mon_cond_enter()mon_create(3L) LWP routines to manage critical sections
mon_create()mon_create(3L) LWP routines to manage critical sections
mon_destroy()mon_create(3L) LWP routines to manage critical sections
mon_enter()mon_create(3L) LWP routines to manage critical sections
mon_enumerate()mon_create(3L) LWP routines to manage critical sections
mon_exit()mon_create(3L) LWP routines to manage critical sections
mon_waiters()mon_create(3L) LWP routines to manage critical sections
MONITOR()mon_create(3L) LWP routines to manage critical sections
msg_enumrecv()msg_send(3L) LWP send and receive messages
msg_enumsend()msg_send(3L) LWP send and receive messages
msg_recv()msg_send(3L) LWP send and receive messages
MSG_RECVALL()msg_send(3L) LWP send and receive messages
msg_reply()msg_send(3L) LWP send and receive messages
msg_send()msg_send(3L) LWP send and receive messages
pod_exit()lwp_create(3L) LWP thread creation and destruction primitives
pod_getexit()lwp_create(3L) LWP thread creation and destruction primitives
pod_getmaxpri()pod_setmaxpri(3L) control LWP scheduling priority
pod_getmaxsize()pod_setmaxpri(3L) control LWP scheduling priority
pod_setexit()lwp_create(3L) LWP thread creation and destruction primitives
pod_setmaxpri()pod_setmaxpri(3L) control LWP scheduling priority
SAMECV()cv_create(3L) manage LWP condition variables
SAMEMON()mon_create(3L) LWP routines to manage critical sections
SAMETHREAD()lwp_create(3L) LWP thread creation and destruction primitives
STKTOP()lwp_newstk(3L) LWP stack management

Sun Release 4.0 — Last change: 18 November 1987

Museum

Related Articles