share/man/man9/ltsleep.9

   1 .\"     $NetBSD: ltsleep.9,v 1.11 2007/06/17 18:50:07 pooka Exp $
   2 .\"
   3 .\" Copyright (c) 1996, 2002, 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Paul Kranenburg.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd June 17, 2007
  31 .Dt LTSLEEP 9
  32 .Os
  33 .Sh NAME
  34 .Nm ltsleep ,
  35 .Nm tsleep ,
  36 .Nm wakeup
  37 .Nd process context sleep and wakeup
  38 .Sh SYNOPSIS
  39 .In sys/proc.h
  40 .Ft int
  41 .Fn "ltsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "volatile struct simplelock *slock"
  42 .Ft int
  43 .Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo"
  44 .Ft void
  45 .Fn "wakeup" "wchan_t ident"
  46 .Sh DESCRIPTION
  47 .Em The interfaces described in this manual page are obsolete
  48 .Em and will be removed from a future version of the system.
  49 .Pp
  50 .Em Please see the
  51 .Xr condvar 9 ,
  52 .Xr mutex 9 ,
  53 .Em and
  54 .Xr rwlock 9
  55 .Em manual pages for information on kernel synchronisation primitives.
  56 .Pp
  57 These functions implement voluntary context switching.
  58 .Fn ltsleep
  59 and
  60 .Fn tsleep
  61 are used throughout the kernel whenever processing in the current context
  62 can not continue for any of the following reasons:
  63 .Bl -bullet -offset indent
  64 .It
  65 The current process needs to await the results of a pending I/O operation.
  66 .It
  67 The current process needs resources
  68 .Pq e.g., memory
  69 which are temporarily unavailable.
  70 .It
  71 The current process wants access to data-structures which are locked by
  72 other processes.
  73 .El
  74 .Pp
  75 The function
  76 .Fn wakeup
  77 is used to notify sleeping processes of possible changes to the condition
  78 that caused them to go to sleep.
  79 Typically, an awakened process will -- after it has acquired a context
  80 again -- retry the action that blocked its operation to see if the
  81 .Dq blocking
  82 condition has cleared.
  83 .Pp
  84 The
  85 .Fn ltsleep
  86 function takes the following arguments:
  87 .Bl -tag -width priority
  88 .It Fa ident
  89 An identifier of the
  90 .Dq wait channel
  91 representing the resource for which the current process needs to wait.
  92 This typically is the virtual address of some kernel data-structure related
  93 to the resource for which the process is contending.
  94 The same identifier must be used in a call to
  95 .Fn wakeup
  96 to get the process going again.
  97 .Fa ident
  98 should not be
  99 .Dv NULL .
 100 .It Fa priority
 101 The process priority to be used when the process is awakened and put on
 102 the queue of runnable processes.
 103 This mechanism is used to optimize
 104 .Dq throughput
 105 of processes executing in kernel mode.
 106 If the flag
 107 .Dv PCATCH
 108 is OR'ed into
 109 .Fa priority
 110 the process checks for posted signals before and after sleeping.
 111 If the flag
 112 .Dv PNORELOCK
 113 is OR'ed into
 114 .Fa priority ,
 115 .Fa slock
 116 is NOT re-locked after process resume.
 117 .It Fa wmesg
 118 A pointer to a character string indicating the reason a process is sleeping.
 119 The kernel does not use the string, but makes it available
 120 .Pq through the process structure field Li p_wmesg
 121 for user level utilities such as
 122 .Xr ps 1 .
 123 .It Fa timo
 124 If non-zero, the process will sleep for at most
 125 .Li timo/hz
 126 seconds.
 127 If this amount of time elapses and no
 128 .Fn wakeup "ident"
 129 has occurred, and no signal
 130 .Pq if Dv PCATCH No was set
 131 was posted,
 132 .Fn tsleep
 133 will return
 134 .Er EWOULDBLOCK .
 135 .It Fa slock
 136 If not NULL, the
 137 .Fa slock
 138 interlock is unlocked once the scheduler lock is acquired.
 139 Unless
 140 .Dv PNORELOCK
 141 was set,
 142 .Fa slock
 143 is locked again once
 144 the process is resumed from sleep.
 145 This provides wakeup-before-sleep condition protection facility.
 146 .El
 147 .Pp
 148 The
 149 .Fn tsleep
 150 macro is functionally equivalent to:
 151 .Bd -literal -offset indent
 152 ltsleep(ident, priority, wmesg, timo, NULL)
 153 .Ed
 154 .Pp
 155 The
 156 .Fn wakeup
 157 function will mark all processes which are currently sleeping on the identifier
 158 .Fa ident
 159 as runnable.
 160 Eventually, each of the processes will resume execution in the kernel
 161 context, causing a return from
 162 .Fn tsleep .
 163 Note that processes returning from sleep should always re-evaluate the
 164 conditions that blocked them, since a call to
 165 .Fn wakeup
 166 merely signals a
 167 .Em possible
 168 change to the blocking conditions.
 169 For example, when two or more processes are waiting for an exclusive-access
 170 lock
 171 .Pq see Xr lock 9 ,
 172 only one of them will succeed in acquiring the lock when it is released.
 173 All others will have to go back to sleep and wait for the next opportunity.
 174 .Sh RETURN VALUES
 175 .Fn ltsleep
 176 returns 0 if it returns as a result of a
 177 .Fn wakeup .
 178 If a
 179 .Fn ltsleep
 180 returns as a result of a signal, the return value is
 181 .Er ERESTART
 182 if the signal has the
 183 .Dv SA_RESTART
 184 property
 185 .Pq see Xr sigaction 2 ,
 186 and
 187 .Er EINTR
 188 otherwise.
 189 If
 190 .Fn ltsleep
 191 returns because of a timeout it returns
 192 .Er EWOULDBLOCK .
 193 .Sh SEE ALSO
 194 .Xr sigaction 2 ,
 195 .Xr condvar 9 ,
 196 .Xr hz 9 ,
 197 .Xr lock 9 ,
 198 .Xr mutex 9 ,
 199 .Xr rwlock 9
 200 .Sh HISTORY
 201 The sleep/wakeup process synchronization mechanism is very old.
 202 It appeared in a very early version of Unix.
 203 .Fn tsleep
 204 appeared in
 205 .Bx 4.4 .
 206 .Fn ltsleep
 207 appeared in
 208 .Nx 1.5 .