.TH SLEEP 10.2.SH NAMEsleep, wakeup, tsleep, return0 \- process synchronisation.SH SYNOPSIS.ta \w'\fLvoid 'u.Bvoid sleep(Rendez *r, int (*f)(void*), void *arg).PP.Bvoid wakeup(Rendez *r).PP.Bvoid tsleep(Rendez *r, int (*f)(void*), void *arg, int ms).PP.Bint return0(void *arg).PP.SH DESCRIPTIONA process running in the kernel can use these functions tosynchronise with an interrupt handler or another kernel process.In particular, they are used by device drivers to wait for an event to be signalled onreceipt of an interrupt.(In practice, they are most often used indirectly, through.IR qio (10.2)for instance.).PPThe caller of.I sleepand a caller of.I wakeupshare a.B Rendezstructure, to provide a rendezvous point between themto synchronise on an event..I Sleepuses a condition function.I fthat returns true if the event has occurred..PP.I Sleepevaluates.IB f ( arg ).If true, the event has happened and.I sleepreturns immediately.Otherwise,.I sleepblocks on the event variable.IR r ,awaiting.IR wakeup ..PP.I Wakeupis called by either a process or an interrupt handler to wake any processsleeping at.IR r ,signifying that the corresponding condition is true (the event has occurred).It has no effect if there is no sleeping process..PP.I Tsleepis similar to.IR sleep ,except that if the condition.IB f ( arg )is false and the caller does sleep,and nothing else wakes it within.I msmillliseconds,the system will wake it..IR Tsleep 'scaller must check its environment to decide whether timeout or the eventoccurred.The timing provided by.I tsleepis imprecise, but adequate in practice for the normal use of protecting againstlost interrupts and otherwise unresponsive devices or software..PP.I Return0ignores its arguments and returns zero. It is commonly used asthe predicate.I fin a call to.I tsleepto obtain a time delay, using a.B Rendezvariable.B sleepin the.B Procstructure, for example:.IP.B tsleep(&up->sleep, return0, nil, 10);.PPBoth.I sleepand.I tsleepcan be interrupted by.IR swiproc(see.IR kproc (10.2)),causing a non-local goto through a call to.IR error (10.2)..SH DIAGNOSTICSThere can be at most one process waiting on a.BR Rendez ,and if two processes collide, the system will.IR panic (10.2).RB (`` "double sleep" '').Access to a.B Rendezmust therefore be serialised by some other mechanism, usually.IR qlock (10.2)..SH SOURCE.B /os/port/proc.c.br.B /emu/port/proc.c.SH SEE ALSO.IR lock (10.2),.IR qlock (10.2),.IR delay (10.2).br``Process Sleep and Wakeup on a Shared-memory Multiprocessor'',in.I "Plan 9 Programmer's Manual: Volume 2".
.TH SLEEP 10.2
.SH NAME
sleep, wakeup, tsleep, return0 \- process synchronisation
.SH SYNOPSIS
.ta \w'\fLvoid 'u
.B
void sleep(Rendez *r, int (*f)(void*), void *arg)
.PP
.B
void wakeup(Rendez *r)
.PP
.B
void tsleep(Rendez *r, int (*f)(void*), void *arg, int ms)
.PP
.B
int return0(void *arg)
.PP
.SH DESCRIPTION
A process running in the kernel can use these functions to
synchronise with an interrupt handler or another kernel process.
In particular, they are used by device drivers to wait for an event to be signalled on
receipt of an interrupt.
(In practice, they are most often used indirectly, through
.IR qio (10.2)
for instance.)
.PP
The caller of
.I sleep
and a caller of
.I wakeup
share a
.B Rendez
structure, to provide a rendezvous point between them
to synchronise on an event.
.I Sleep
uses a condition function
.I f
that returns true if the event has occurred.
.PP
.I Sleep
evaluates
.IB f ( arg ).
If true, the event has happened and
.I sleep
returns immediately.
Otherwise,
.I sleep
blocks on the event variable
.IR r ,
awaiting
.IR wakeup .
.PP
.I Wakeup
is called by either a process or an interrupt handler to wake any process
sleeping at
.IR r ,
signifying that the corresponding condition is true (the event has occurred).
It has no effect if there is no sleeping process.
.PP
.I Tsleep
is similar to
.IR sleep ,
except that if the condition
.IB f ( arg )
is false and the caller does sleep,
and nothing else wakes it within
.I ms
millliseconds,
the system will wake it.
.IR Tsleep 's
caller must check its environment to decide whether timeout or the event
occurred.
The timing provided by
.I tsleep
is imprecise, but adequate in practice for the normal use of protecting against
lost interrupts and otherwise unresponsive devices or software.
.PP
.I Return0
ignores its arguments and returns zero. It is commonly used as
the predicate
.I f
in a call to
.I tsleep
to obtain a time delay, using a
.B Rendez
variable
.B sleep
in the
.B Proc
structure, for example:
.IP
.B tsleep(&up->sleep, return0, nil, 10);
.PP
Both
.I sleep
and
.I tsleep
can be interrupted by
.IR swiproc
(see
.IR kproc (10.2)),
causing a non-local goto through a call to
.IR error (10.2).
.SH DIAGNOSTICS
There can be at most one process waiting on a
.BR Rendez ,
and if two processes collide, the system will
.IR panic (10.2)
.RB (`` "double sleep" '').
Access to a
.B Rendez
must therefore be serialised by some other mechanism, usually
.IR qlock (10.2).
.SH SOURCE
.B /os/port/proc.c
.br
.B /emu/port/proc.c
.SH SEE ALSO
.IR lock (10.2),
.IR qlock (10.2),
.IR delay (10.2)
.br
``Process Sleep and Wakeup on a Shared-memory Multiprocessor'',
in
.I "Plan 9 Programmer's Manual: Volume 2".