code: plan9front

ref: e72da62915b09d5673b0c0179ba8dfe045aeb8c3
dir: /sys/man/9/sleep/

View raw version
sleep, wakeup, tsleep, return0 \- process synchronisation
.ta \w'\fLvoid 'u
void	sleep(Rendez *r, int (*f)(void*), void *arg)
void	wakeup(Rendez *r)
void	tsleep(Rendez *r, int (*f)(void*), void *arg, ulong ms)
int	return0(void *arg)
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 (9)
for instance.)
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.
.I Sleep
.IB f ( arg ).
If true, the event has happened and
.I sleep
returns immediately.
.I sleep
blocks on the event variable
.IR r ,
.IR wakeup .
.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.
.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
the system will wake it.
.IR Tsleep 's
caller must check its environment to decide whether timeout or the event
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.
.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 the
.B Rendez
.B sleep
in the
.B Proc
structure, for example:
.B tsleep(&up->sleep, return0, nil, 10);
.I sleep
.I tsleep
can be interrupted by
.IR postnote
.IR kproc (9)).
.B /sys/src/9/port/proc.c
.B /sys/src/9/port/sysproc.c
There can be at most one process waiting on a
.BR Rendez ,
and if two processes collide, the system will
.IR panic (9)
.RB (`` "double sleep" '').
Access to a
.B Rendez
must therefore be serialised by some other mechanism, usually
.IR qlock (9).
.IR lock (9),
.IR qlock (9),
.IR delay (9)
``Process Sleep and Wakeup on a Shared-memory Multiprocessor'',
.I "Plan 9 Programmer's Manual: Volume 2".