INTRO ( 3L )

LIGHTWEIGHT PROCESSES LIBRARY

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

lwp perror(3L) for details on error handling.

On errors, they return 1.

See

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 System Services Overview
INDEX

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

lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
pod
pod
pod

self(tid)
getstate(tid, statvec)
setregs(tid, machstate)
getregs(tid, machstate)
ping(tid)
create(tid, pc, prio, flags, stack, nargs, arg1, . . . , argn)
destroy(tid)
enumerate(vec, maxsize)
setexit(status)
getexit( )
exit(status)

Sun Release 4.1

Last change: 21 January 1990

INTRO ( 3L )

LIGHTWEIGHT PROCESSES LIBRARY

INTRO ( 3L )

SAMETHREAD(t1, t2)
Thread Scheduling

pod
pod
pod
lwp
lwp
lwp
lwp
lwp
lwp
lwp

setmaxpri(maxprio)
getmaxpri( )
getmaxsize( )
resched(prio)
setpri(tid, prio)
sleep(timeout)
suspend(tid)
resume(tid)
yield(tid)
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
mon
mon
mon
mon
mon
mon
mon

create(mid)
destroy(mid)
enter(mid)
exit(mid)
enumerate(vec, maxsize)
waiters (mid, owner, vec, maxsize)
cond enter(mid)
break(mid)
MONITOR(mid)
SAMEMON(m1, m2)
Thread Synchronization: Condition Variables

cv
cv
cv
cv
cv
cv
cv
cv

create(cv, mid)
destroy(cv)
wait(cv)
notify(cv)
send(cv, tid)
broadcast(cv)
enumerate(vec, maxsize)
waiters(cv, vec, maxsize)
SAMECV(c1, c2)
Exception Handling

exc handle(pattern, func, arg)

exc unhandle( )
( exc bound(pattern, arg))( )
exc notify(pattern)

Sun Release 4.1

Last change: 21 January 1990

INTRO ( 3L )

LIGHTWEIGHT PROCESSES LIBRARY

INTRO ( 3L )

exc raise(pattern)
exc on exit(func, arg)
exc uniqpatt( )
Special Context Handling

lwp
lwp
lwp
lwp
lwp
lwp
lwp

ctxinit(tid, cookie)
ctxremove(tid, cookie)
ctxset(save, restore, ctxsize, optimise)
ctxmemget(mem, tid, ctx)
ctxmemset(mem, tid, ctx)
fpset(tid)
libcset(tid)

Stack Management
CHECK(location, result)

lwp
lwp
lwp
lwp
lwp

setstkcache(minsize, numstks)
newstk( )
datastk(data, size, addr)
stkcswset(tid, limit)
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

agt create
agt enumerate
agt trap

agt create(3L)
agt create(3L)
agt create(3L)
lwp newstk(3L)
cv create(3L)
cv create(3L)
cv create(3L)
cv create(3L)
cv create(3L)
cv create(3L)
cv create(3L)
cv create(3L)
exc handle(3L)
exc handle(3L)
exc handle(3L)
exc handle(3L)
exc handle(3L)
exc handle(3L)
exc handle(3L)
lwp newstk(3L)
lwp create(3L)
lwp ctxinit(3L)
lwp ctxinit(3L)
lwp ctxinit(3L)
lwp ctxinit(3L)
lwp ctxinit(3L)

CHECK

cv broadcast
cv create
cv destroy
cv enumerate
cv notify
cv send
cv wait
cv waiters
exc bound
exc handle
exc notify
exc on exit
exc raise
exc unhandle
exc uniqpatt
lwp checkstkset
lwp create
lwp ctxinit
lwp ctxmemget
lwp ctxmemset
lwp ctxremove
lwp ctxset

Sun Release 4.1

Description
map LWP events into messages
map LWP events into messages
map LWP events into messages
LWP stack management
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
manage LWP condition variables
LWP exception handling
LWP exception handling
LWP exception handling
LWP exception handling
LWP exception handling
LWP exception handling
LWP exception handling
LWP stack management
LWP thread creation and destruction primitives
special LWP context operations
special LWP context operations
special LWP context operations
special LWP context operations
special LWP context operations

Last change: 21 January 1990

INTRO ( 3L )

lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp
lwp

LIGHTWEIGHT PROCESSES LIBRARY

datastk
destroy
enumerate
errstr
fpset
geterr
getregs
getstate
join
libcset
newstk
perror
ping
resched
resume
self
setpri
setregs
setstkcache
sleep
stkcswset
suspend
yield

MINSTACKSZ

mon
mon
mon
mon
mon
mon
mon
mon

break
cond enter
create
destroy
enter
enumerate
exit
waiters

MONITOR

msg enumrecv
msg enumsend
msg recv
MSG RECVALL

msg
msg
pod
pod
pod
pod
pod
pod

reply
send
exit
getexit
getmaxpri
getmaxsize
setexit
setmaxpri

SAMECV
SAMEMON
SAMETHREAD
STKTOP

Sun Release 4.1

lwp newstk(3L)
lwp create(3L)
lwp status(3L)
lwp perror(3L)
lwp ctxinit(3L)
lwp perror(3L)
lwp status(3L)
lwp status(3L)
lwp yield(3L)
lwp ctxinit(3L)
lwp newstk(3L)
lwp perror(3L)
lwp status(3L)
lwp yield(3L)
lwp yield(3L)
lwp status(3L)
lwp yield(3L)
lwp status(3L)
lwp newstk(3L)
lwp yield(3L)
lwp newstk(3L)
lwp yield(3L)
lwp yield(3L)
lwp newstk(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
mon create(3L)
msg send(3L)
msg send(3L)
msg send(3L)
msg send(3L)
msg send(3L)
msg send(3L)
lwp create(3L)
lwp create(3L)
pod getmaxpri(3L)
pod getmaxpri(3L)
lwp create(3L)
pod getmaxpri(3L)
cv create(3L)
mon create(3L)
lwp create(3L)
lwp newstk(3L)

INTRO ( 3L )

LWP stack management

LWP thread creation and destruction primitive s
LWP status information
LWP error handling
special LWP context operations
LWP error handling
LWP status information
LWP status information
control LWP scheduling
special LWP context operations
LWP stack management
LWP error handling
LWP status information
control LWP scheduling
control LWP scheduling
LWP status information
control LWP scheduling
LWP status information
LWP stack management
control LWP scheduling
LWP stack management
control LWP scheduling
control LWP scheduling
LWP stack management
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP routines to manage critical sections
LWP send and receive messages
LWP send and receive messages
LWP send and receive messages
LWP send and receive messages
LWP send and receive messages
LWP send and receive messages
LWP thread creation and destruction primitives
LWP thread creation and destruction primitive s
control LWP scheduling priority
control LWP scheduling priority
LWP thread creation and destruction primitives
control LWP scheduling priority
manage LWP condition variables
LWP routines to manage critical sections
LWP thread creation and destruction primitive s
LWP stack management

Last change: 21 January 1990