diff options
author | jhb <jhb@FreeBSD.org> | 2006-04-17 19:11:12 +0000 |
---|---|---|
committer | jhb <jhb@FreeBSD.org> | 2006-04-17 19:11:12 +0000 |
commit | d989c9d47862700759c8cc97aba66f22c3f2f2e5 (patch) | |
tree | 2b39ff36528e74a68e1e240236cf939a61149783 /share/man/man9/sleep.9 | |
parent | 665da7e9a1a510644a3e2cac5be242002d0a20a9 (diff) | |
download | FreeBSD-src-d989c9d47862700759c8cc97aba66f22c3f2f2e5.zip FreeBSD-src-d989c9d47862700759c8cc97aba66f22c3f2f2e5.tar.gz |
- Sleep/wakeup operate on threads now, not processes.
- Describe msleep() as the primary sleep function now rather than tsleep()
and describe tsleep() and msleep_spin() as variations.
- Try to make the description of msleep() a bit closer to English
(sentences with actual subjects, etc.)
- Document that a priority of 0 now prevents the thread's priority from
being altered.
- Add a history note for wakeup_one().
Diffstat (limited to 'share/man/man9/sleep.9')
-rw-r--r-- | share/man/man9/sleep.9 | 102 |
1 files changed, 62 insertions, 40 deletions
diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 index 1e2cc73..1562c55a 100644 --- a/share/man/man9/sleep.9 +++ b/share/man/man9/sleep.9 @@ -50,23 +50,29 @@ .Fn wakeup_one "void *chan" .Sh DESCRIPTION The functions -.Fn tsleep +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +.Fn wakeup , and -.Fn wakeup -handle event-based process blocking. -If a process must wait for an -external event, it is put on sleep by -.Fn tsleep . +.Fn wakeup_one +handle event-based thread blocking. +If a thread must wait for an +external event, it is put to sleep by +.Fn tsleep , +.Fn msleep , +or +.Fn msleep_spin . The parameter .Fa chan is an arbitrary address that uniquely identifies the event on which -the process is being asleep. -All processes sleeping on a single +the thread is being asleep. +All threads sleeping on a single .Fa chan are woken up later by .Fn wakeup , often called from inside an interrupt routine, to indicate that the -resource the process was blocking on is available now. +resource the thread was blocking on is available now. .Pp The parameter .Fa wmesg @@ -77,26 +83,49 @@ this message should not be longer than 6 characters. .Pp The .Fn wakeup_one -function is used to make the first process in the queue that is +function is used to make the first thread in the queue that is sleeping on the parameter .Fa chan runnable. This can prevent the system from becoming saturated -when a large number of processes are sleeping on the same address, +when a large number of threads are sleeping on the same address, but only one of them can actually do any useful work when made runnable. .Pp The -.Fn tsleep +.Fn msleep function is the general sleep call. -Suspends the current process until a wakeup is +It suspends the current thread until a wakeup is performed on the specified identifier. -The process will then be made +The +.Fa mtx +parameter is a mutex which will be released before sleeping and reacquired +before +.Fn msleep +returns. +If +.Fa priority +includes the +.Dv PDROP +flag, the +.Fa mtx +parameter will not be reacquired before returning. +The mutex is used to ensure that a condition can be checked atomically, +and that the current thread can be suspended without missing a +change to the condition, or an associated wakeup. +If +.Fa priority +is not 0, +then the thread will be made runnable with the specified -.Fa priority . -Sleeps at most +.Fa priority +when it resumes. +If .Fa timo -\&/ hz seconds (0 means no timeout). +is not 0, +then the thread will sleep for at most +.Fa timo +\&/ hz seconds. If the .Va Giant lock is not held and @@ -112,7 +141,9 @@ includes the .Dv PCATCH flag, signals are checked before and after sleeping, otherwise signals are not checked. -Returns 0 if awakened, +The +.Fn msleep +function returns 0 if awakened, .Er EWOULDBLOCK if the timeout expires. If @@ -127,34 +158,21 @@ is returned if the system call should be interrupted by the signal .Er EINTR ) . .Pp The +.Fn tsleep +function is a variation on +.Fn msleep . +It is identical to invoking .Fn msleep -function is a variation on tsleep. -The parameter -.Fa mtx -is a mutex which will be released before sleeping and reacquired before -.Fn msleep -returns. -If -.Fa priority -includes the -.Dv PDROP -flag, the +with a +.Dv NULL .Fa mtx -parameter will not be reacquired before returning. -The mutex is -used to ensure that a condition can be checked atomically, and -that the current process can be suspended without missing a -change to the condition, or an associated wakeup. +parameter. .Pp The .Fn msleep_spin function is another variation on -.Fn tsleep -similar to .Fn msleep . -Unlike -.Fn msleep , -this function accepts a spin mutex rather than a default mutex for its +This function accepts a spin mutex rather than a default mutex for its .Fa mtx parameter. It is also more limited in that it does not accept a @@ -173,7 +191,7 @@ See above. .Xr malloc 9 , .Xr mi_switch 9 .Sh HISTORY -The sleep/wakeup process synchronization mechanism is very old. +The sleep/wakeup thread synchronization mechanism is very old. It appeared in a very early version of .Ux . @@ -183,6 +201,10 @@ The function appeared in .Bx 4.4 . The +.Fn wakeup_one +function appeared in +.Fx 2.2 . +The .Fn msleep function appeared in .Fx 5.0 , |