From 1967f937b7474a5ce02fc3e092acf676f19d248b Mon Sep 17 00:00:00 2001 From: dillon Date: Mon, 21 Dec 1998 10:29:28 +0000 Subject: Add manual page for experimental kernel asleep() and await() routines --- share/man/man9/Makefile | 3 +- share/man/man9/sleep.9 | 94 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 94 insertions(+), 3 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 670b40c..2e2a058 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile,v 1.39 1998/09/27 13:35:49 eivind Exp $ +# $Id: Makefile,v 1.40 1998/10/28 00:55:42 nsouch Exp $ MAN9= MD5.9 \ VFS.9 VFS_FHTOVP.9 VFS_INIT.9 VFS_MOUNT.9 VFS_QUOTACTL.9 \ @@ -63,6 +63,7 @@ MLINKS+=posix4.9 p1003_1b.9 MLINKS+=psignal.9 gsignal.9 psignal.9 pgsignal.9 MLINKS+=rtalloc.9 rtalloc1.9 rtalloc.9 rtalloc_ign.9 MLINKS+=sleep.9 tsleep.9 sleep.9 wakeup.9 sleep.9 wakeup_one.9 +MLINKS+=sleep.9 asleep.9 sleep.9 await.9 MLINKS+=spl.9 spl0.9 MLINKS+=spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9 MLINKS+=spl.9 splnet.9 spl.9 splsoftclock.9 spl.9 splsofttty.9 diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 index 351de02..883c658 100644 --- a/share/man/man9/sleep.9 +++ b/share/man/man9/sleep.9 @@ -23,14 +23,16 @@ .\" (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.9 1997/04/11 17:49:56 bde Exp $ +.\" $Id: sleep.9,v 1.10 1998/01/16 18:12:57 bde Exp $ .\" " -.Dd April 3, 1996 +.Dd December 17, 1998 .Os .Dt SLEEP 9 .Sh NAME .Nm sleep , .Nm tsleep , +.Nm asleep , +.Nm await , .Nm wakeup .Nd wait for events .Sh SYNOPSIS @@ -39,6 +41,10 @@ .Fd #include .Ft int .Fn tsleep "void *ident" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn asleep "void *ident" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn await "int priority" "int timo" .Ft void .Fn wakeup "void *ident" .Ft void @@ -106,6 +112,90 @@ is returned if the system call should be interrupted by the signal is the traditional form. It doesn't let you specify a timeout nor a .Ar wmesg , hence its use is deprecated. +.Pp +.Nm Asleep +implements the new asynchronous sleep function. It takes the same arguments +as +.Fn tsleep +and places the process on the appropriate wait queue, but +.Fn asleep +leaves the process runnable and returns immediately. The caller is then +expected to, at some point in the future, call +.Fn await +to actually wait for the previously queued wait condition. +If +.Fn asleep +is called several times, only the most recent call is effective. +.Fn asleep +may be called with an +.Ar ident +value of NULL +to remove any previously queued condition. +.Pp +.Nm Await +implements the new asynchronous wait function. If you +.Fn asleep +on an identifier, +.Fn await +will actually block the process until someone calls +.Fn wakeup +on that identifier. If someone calls +.Fn wakeup +after you +.Fn asleep +but before you +.Fn await +then the +.Fn await +call is effectively a NOP. +If +.Fn await +is called multiple times without an intervening +.Fn asleep +the +.Fn await +is effective a NOP, but will call +.Fn mswitch +for safety. The +.Fn await +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 +conditions if the prior call to +.Fn asleep +specified it in its priority. If you pass -1 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 +assumptions as to the arguments used by the prior +.Fn asleep +call. +.Pp +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 +.Fn asleep +and returning a temporary failure, then popping back up through a number +of call levels before calling +.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. .Sh RETURN VALUES See above. .Sh SEE ALSO -- cgit v1.1