sys/man/9/sleep

   1 .TH SLEEP 9
   2 .SH NAME
   3 sleep, wakeup, tsleep, return0 \- process synchronisation
   4 .SH SYNOPSIS
   5 .ta \w'\fLvoid 'u
   6 .B
   7 void    sleep(Rendez *r, int (*f)(void*), void *arg)
   8 .PP
   9 .B
  10 void    wakeup(Rendez *r)
  11 .PP
  12 .B
  13 void    tsleep(Rendez *r, int (*f)(void*), void *arg, ulong ms)
  14 .PP
  15 .B
  16 int     return0(void *arg)
  17 .PP
  18 .SH DESCRIPTION
  19 A process running in the kernel can use these functions to
  20 synchronise with an interrupt handler or another kernel process.
  21 In particular, they are used by device drivers to wait for an event to be signalled on
  22 receipt of an interrupt.
  23 (In practice, they are most often used indirectly, through
  24 .IR qio (9)
  25 for instance.)
  26 .PP
  27 The caller of
  28 .I sleep
  29 and a caller of
  30 .I wakeup
  31 share a
  32 .B Rendez
  33 structure, to provide a rendezvous point between them
  34 to synchronise on an event.
  35 .I Sleep
  36 uses a condition function
  37 .I f
  38 that returns true if the event has occurred.
  39 .PP
  40 .I Sleep
  41 evaluates
  42 .IB f ( arg ).
  43 If true, the event has happened and
  44 .I sleep
  45 returns immediately.
  46 Otherwise,
  47 .I sleep
  48 blocks on the event variable
  49 .IR r ,
  50 awaiting
  51 .IR wakeup .
  52 .PP
  53 .I Wakeup
  54 is called by either a process or an interrupt handler to wake any process
  55 sleeping at
  56 .IR r ,
  57 signifying that the corresponding condition is true (the event has occurred).
  58 It has no effect if there is no sleeping process.
  59 .PP
  60 .I Tsleep
  61 is similar to
  62 .IR sleep ,
  63 except that if the condition
  64 .IB f ( arg )
  65 is false and the caller does sleep,
  66 and nothing else wakes it within
  67 .I ms
  68 millliseconds,
  69 the system will wake it.
  70 .IR Tsleep 's
  71 caller must check its environment to decide whether timeout or the event
  72 occurred.
  73 The timing provided by
  74 .I tsleep
  75 is imprecise, but adequate in practice for the normal use of protecting against
  76 lost interrupts and otherwise unresponsive devices or software.
  77 .PP
  78 .I Return0
  79 ignores its arguments and returns zero. It is commonly used as
  80 the predicate
  81 .I f
  82 in a call to
  83 .I tsleep
  84 to obtain a time delay, using the
  85 .B Rendez
  86 variable
  87 .B sleep
  88 in the
  89 .B Proc
  90 structure, for example:
  91 .IP
  92 .B tsleep(&up->sleep, return0, nil, 10);
  93 .PP
  94 Both
  95 .I sleep
  96 and
  97 .I tsleep
  98 can be interrupted by
  99 .IR postnote
 100 (see
 101 .IR kproc (9)).
 102 .SH SOURCE
 103 .B /sys/src/9/port/proc.c
 104 .br
 105 .B /sys/src/9/port/sysproc.c
 106 .SH DIAGNOSTICS
 107 There can be at most one process waiting on a
 108 .BR Rendez ,
 109 and if two processes collide, the system will
 110 .IR panic (9)
 111 .RB (`` "double sleep" '').
 112 Access to a
 113 .B Rendez
 114 must therefore be serialised by some other mechanism, usually
 115 .IR qlock (9).
 116 .SH SEE ALSO
 117 .IR lock (9),
 118 .IR qlock (9),
 119 .IR delay (9)
 120 .br
 121 ``Process Sleep and Wakeup on a Shared-memory Multiprocessor'',
 122 in
 123 .I "Plan 9 Programmer's Manual: Volume 2".