d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update asleep/await sections

Browse Source
This commit is contained in:
dillon 1998-12-23 00:24:59 +00:00
parent fb5b48c1cb
commit 9f074776ec
1 changed files with 46 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
share/man/man9/sleep.9
View File

@ -23,7 +23,7 @@
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: sleep.9,v 1.11 1998/12/21 10:29:28 dillon Exp $
.\" $Id: sleep.9,v 1.12 1998/12/21 10:34:53 dillon Exp $
.\" "
.Dd December 17, 1998
.Os
@ -133,15 +133,18 @@ value of NULL
to remove any previously queued condition.
.Pp
.Nm Await
implements the new asynchronous wait function. If you
implements the new asynchronous wait function. When
.Fn asleep
on an identifier,
is called on an identifier it associates the process with that
identifier but does not block.
.Fn await
will actually block the process until someone calls
will actually block the process until
.Fn wakeup
on that identifier. If someone calls
is called on that identifier any time after the
.Fn asleep .
If
.Fn wakeup
after you
is called after you
.Fn asleep
but before you
.Fn await
@ -151,10 +154,10 @@ call is effectively a NOP.
If
.Fn await
is called multiple times without an intervening
.Fn asleep
.Fn asleep ,
the
.Fn await
is effective a NOP, but will call
is effectively a NOP but will also call
.Fn mswitch
for safety. The
.Fn await
@ -162,13 +165,13 @@ function allows you to override the priority and timeout values to be used.
If the value -1 is specified for an argument, the value is taken from the
previous
.Fn asleep
call. If you pass -1 for the priority you must be prepared to catch signal
call. If -1 is passed for the priority you must be prepared to catch signal
conditions if the prior call to
.Fn asleep
specified it in its priority. If you pass -1 for the timeout you must be
specified it in its priority. If -1 is passed for the timeout you must be
prepared to catch a timeout condition if the prior call to
.Fn asleep
specified a timeout. When you use -1, you should generally not make
specified a timeout. When you use -1, it is usually a good idea to not make
assumptions as to the arguments used by the prior
.Fn asleep
call.
@ -177,29 +180,39 @@ The
.Fn asleep
and
.Fn await
functions are used by the kernel code for various purposes but the main one is
to allow complex interlocking code to 'backout' of a temporary resource failure
(such as lack of memory or trying to access a block that is not in the buffer
cache) in order to release major locks prior to blocking, and to then retry
the call that failed on wakeup. This involves subroutines deep in the kernel
calling
functions are mainly used by the kernel to shift the burden of blocking
away from extremely low level routines and to push it onto their callers.
This in turn allows more complex interlocking code to
.Em backout
of a temporary resource failure
(such as lack of memory) in order to release major locks prior to actually
blocking, and to then retry the operation on wakeup. This key feature is
expected to be heavily used in SMP situations in order to allow code to make
better use of spinlocks. A spinlock, by its very nature, cannot be used
around code that might block. It is hoped that these capabilities will
make it easier to migrate the SMP master locks deeper into the kernel.
.Pp
These routines may also be used to avoid nasty spl*() calls to get around
race conditions with simple conditional test/wait interlocks. You simple
call
.Fn asleep
and returning a temporary failure, then popping back up through a number
of call levels before calling
prior to your test, then conditonally
.Fn await
only if the test fails. It is usually a good idea to cancel an
.Fn asleep
if you wind up never calling the related
.Fn await ,
then retrying. The kernel might also use these functions to avoid using
spinlocks in a check-condition interlock. That is, in case the case where
the kernel wishes to check the condition of something and then block on it.
To avoid the race between the check and the blocking, the kernel can first
check the condition, then call
.Fn asleep ,
then check the condition a second time before calling
.Fn await .
The overlap makes the race condition impossible.
but it is not required. If you do not want to waste cpu calling
.Fn asleep
unnecessarily, you can surround the whole thing with a second test. The
race condition is still handled by the inside
.Fn asleep
call.
.Sh RETURN VALUES
See above.
.Sh SEE ALSO
.Xr ps 1
.Xr ps 1 ,
.Xr malloc 9
.Sh HISTORY
The sleep/wakeup process synchronization mechanism is very old. It
appeared in a very early version of Unix.
@ -209,8 +222,10 @@ appeared in
.Bx 4.4 .
.Pp
.Nm Asleep/await
first appeared in FreeBSD-3.0.1
first appeared in FreeBSD-3.0.1 and is designed to shift the burden of blocking
away from extremely low level routines and push it up to their callers.
.Sh AUTHORS
This man page has been written by
.ie t J\(:org Wunsch.
.el Joerg Wunsch. asleep/await portions were written by Matt Dillon
.el Joerg Wunsch.
asleep/await designed and written by Matthew Dillon.