June 17, 2007 LTSLEEP 9

### NAME

ltsleep, tsleep, wakeup - process context sleep and wakeup

### SYNOPSIS

```int` ltsleep(```wchan_t ident``, pri_t priority``, const char *wmesg``, int timo``, volatile struct simplelock *slock`)
```int` tsleep(```wchan_t ident``, pri_t priority``, const char *wmesg``, int timo`)
```void` wakeup(```wchan_t ident`)

### DESCRIPTION

The interfaces described in this manual page are obsolete and will be removed from a future version of the system.

Please see the condvar(9), mutex(9), and rwlock(9) manual pages for information on kernel synchronisation primitives.

These functions implement voluntary context switching. ltsleep(``) and tsleep(``) are used throughout the kernel whenever processing in the current context can not continue for any of the following reasons:

- The current process needs to await the results of a pending I/O operation.

- The current process needs resources (e.g., memory) which are temporarily unavailable.

- The current process wants access to data-structures which are locked by other processes.

The function wakeup(``) is used to notify sleeping processes of possible changes to the condition that caused them to go to sleep. Typically, an awakened process will -- after it has acquired a context again -- retry the action that blocked its operation to see if the ``blocking'' condition has cleared.

The ltsleep(``) function takes the following arguments:

```ident`
  An identifier of the ``wait channel'' representing the resource for which the current process needs to wait. This typically is the virtual address of some kernel data-structure related to the resource for which the process is contending. The same identifier must be used in a call to wakeup(``) to get the process going again. ```ident` should not be ```NULL`.

```priority`
  The process priority to be used when the process is awakened and put on the queue of runnable processes. This mechanism is used to optimize ``throughput'' of processes executing in kernel mode. If the flag ```PCATCH` is OR'ed into ```priority` the process checks for posted signals before and after sleeping. If the flag ```PNORELOCK` is OR'ed into ```priority`, ```slock` is NOT re-locked after process resume.

```wmesg`
  A pointer to a character string indicating the reason a process is sleeping. The kernel does not use the string, but makes it available (through the process structure field`` `p_wmesg`) for user level utilities such as ps(1).

```timo`
  If non-zero, the process will sleep for at most ```timo/hz` seconds. If this amount of time elapses and no wakeup(```ident`) has occurred, and no signal (if`` `PCATCH` was set) was posted, tsleep(``) will return ```EWOULDBLOCK`.

```slock`
  If not NULL, the ```slock` interlock is unlocked once the scheduler lock is acquired. Unless ```PNORELOCK` was set, ```slock` is locked again once the process is resumed from sleep. This provides wakeup-before-sleep condition protection facility.

The tsleep(``) macro is functionally equivalent to:

  `

      ltsleep(ident, priority, wmesg, timo, NULL)

  `

The wakeup(``) function will mark all processes which are currently sleeping on the identifier ```ident` as runnable. Eventually, each of the processes will resume execution in the kernel context, causing a return from tsleep(``). Note that processes returning from sleep should always re-evaluate the conditions that blocked them, since a call to wakeup(``) merely signals a possible change to the blocking conditions. For example, when two or more processes are waiting for an exclusive-access lock (seelock(9)), only one of them will succeed in acquiring the lock when it is released. All others will have to go back to sleep and wait for the next opportunity.

### RETURN VALUES

ltsleep(``) returns 0 if it returns as a result of a wakeup(``). If a ltsleep(``) returns as a result of a signal, the return value is ```ERESTART` if the signal has the ```SA_RESTART` property (seesigaction(2)), and ```EINTR` otherwise. If ltsleep(``) returns because of a timeout it returns ```EWOULDBLOCK`.

### SEE ALSO

sigaction(2), condvar(9), hz(9), lock(9), mutex(9), rwlock(9)

### HISTORY

The sleep/wakeup process synchronization mechanism is very old. It appeared in a very early version of Unix. tsleep(``) appeared in 4.4BSD. ltsleep(``) appeared in NetBSD1.5.