sleep.9: Document mtxsleep() and tsleep_interlock().
authorSascha Wildner <saw@online.de>
Mon, 12 Apr 2010 00:35:32 +0000 (02:35 +0200)
committerSascha Wildner <saw@online.de>
Mon, 12 Apr 2010 00:35:32 +0000 (02:35 +0200)
Also, update HISTORY a bit.

Submitted-by: Venkatesh Srinivas <me@endeavour.zapto.org>
share/man/man9/Makefile
share/man/man9/sleep.9

index a787cf7..c875bcf 100644 (file)
@@ -1,5 +1,4 @@
 # $FreeBSD: src/share/man/man9/Makefile,v 1.60.2.26 2003/06/13 01:04:17 hmp Exp $
-# $DragonFly: src/share/man/man9/Makefile,v 1.81 2008/11/22 20:08:35 swildner Exp $
 
 MAN=   accept_filter.9 \
        accf_data.9 \
@@ -636,11 +635,13 @@ MLINKS+=serializer.9 ASSERT_NOT_SERIALIZED.9 \
        serializer.9 lwkt_serialize_init.9 \
        serializer.9 lwkt_serialize_try.9
 MLINKS+=sleep.9 lksleep.9 \
+       sleep.9 mtxsleep.9 \
        sleep.9 ssleep.9 \
        sleep.9 tsleep.9 \
-       sleep.9 zsleep.9 \
+       sleep.9 tsleep_interlock.9 \
        sleep.9 wakeup.9 \
-       sleep.9 wakeup_one.9
+       sleep.9 wakeup_one.9 \
+       sleep.9 zsleep.9
 MLINKS+=spinlock.9 spin_init.9 \
        spinlock.9 spin_lock_rd.9 \
        spinlock.9 spin_lock_rd_quick.9 \
index 55bbebd..c4bc21a 100644 (file)
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2004 The DragonFly Project.  All rights reserved.
+.\" Copyright (c) 2004,2010 The DragonFly Project.  All rights reserved.
 .\"
 .\" This code is derived from software contributed to The DragonFly Project
 .\" by Hiten Pandya <hmp@backplane.com>.
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" $FreeBSD: src/share/man/man9/sleep.9,v 1.18.2.5 2001/12/17 11:30:19 ru Exp $
-.\" $DragonFly: src/share/man/man9/sleep.9,v 1.11 2008/03/05 17:20:23 swildner Exp $
 .\" "
-.Dd December 14, 2009
+.Dd April 12, 2010
 .Os
 .Dt SLEEP 9
 .Sh NAME
 .Nm tsleep ,
 .Nm ssleep ,
 .Nm lksleep ,
+.Nm mtxsleep ,
 .Nm zsleep ,
+.Nm tsleep_interlock ,
 .Nm wakeup ,
 .Nm wakeup_one
 .Nd wait/sleep/block for events
 .In sys/systm.h
 .In sys/proc.h
 .Ft int
-.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo"
+.Fn tsleep "void *ident" "int flags" "const char *wmesg" "int timo"
 .Ft int
-.Fn ssleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo"
+.Fn ssleep "void *ident" "struct spinlock *spin" "int flags" "const char *wmesg" "int timo"
 .Ft int
-.Fn lksleep "void *ident" "struct lock *lock" "int flag" "const char *wmesg" "int timo"
+.Fn lksleep "void *ident" "struct lock *lock" "int flags" "const char *wmesg" "int timo"
 .Ft int
-.Fn zsleep "void *ident" "struct lwkt_serialize *slz" "int flag" "const char *wmesg" "int timo"
+.Fn mtxsleep "void *ident" "struct mtx *mtx" "int flags" "const char *wmesg" "int timo"
+.Ft int
+.Fn zsleep "void *ident" "struct lwkt_serialize *slz" "int flags" "const char *wmesg" "int timo"
+.Ft void
+.Fn tsleep_interlock "void *ident" "int flags"
 .Ft void
 .Fn wakeup "void *ident"
 .Ft void
@@ -91,6 +96,7 @@ The functions
 .Fn tsleep ,
 .Fn ssleep ,
 .Fn lksleep ,
+.Fn mtxsleep ,
 .Fn zsleep ,
 and
 .Fn wakeup
@@ -99,9 +105,11 @@ If a process must wait for an
 external event, it is put on sleep by
 .Fn tsleep ,
 .Fn ssleep ,
-.Fn lksleep
+.Fn lksleep ,
+.Fn mtxsleep ,
 or
 .Fn zsleep .
+.Pp
 The parameter
 .Ar ident
 is an arbitrary address that uniquely identifies the event on which
@@ -121,17 +129,6 @@ Due to the limited space of those programs to display arbitrary strings,
 this message should not be longer than 6 characters.
 .Pp
 The
-.Fn wakeup_one
-function is used to make the first process/thread in the queue that is
-sleeping on the parameter
-.Fa ident
-runnable.
-This can prevent the system from becoming saturated
-when a large number of processes/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
 function is general in its use and suspends the current process/thread until a
 wakeup is performed on the specified identifier.
@@ -146,6 +143,32 @@ contains the
 flag, signals are checked before and after sleeping, else signals are
 ignored.
 .Pp
+.Fn Tsleep_interlock
+is similar to
+.Fn tsleep ,
+in that it queues a thread on a sleep queue, but it does not actually put the
+thread to sleep.
+This allows coupling tsleep with higher-level synchronization primitives.
+The pattern is:
+.Bd -literal
+(acquire high level synchronization primitive)
+(test condition of interest)
+tsleep_interlock(ident, flags)
+(release high level synchronization primitive)
+tsleep(..., PINTERLOCK)
+.Ed
+.Pp
+For example, to implement
+.Nm ssleep :
+.Bd -literal
+spin_lock_wr(&important_lock);
+if (important_condition == 0) {
+       tsleep_interlock(ident, flags);
+       spin_unlock_wr(&important_lock);
+       tsleep(..., PINTERLOCK);
+}
+.Ed
+.Pp
 The
 .Fn ssleep
 function works like
@@ -177,6 +200,16 @@ interlocked by
 will not be missed.
 .Pp
 The
+.Fn mtxsleep
+function works like
+.Fn tsleep
+while at the same time atomically releasing the mutex
+.Fa mtx
+before sleeping and reacquiring it in exclusive state before
+.Fn mtxsleep
+returns.
+.Pp
+The
 .Fn zsleep
 function works like
 .Fn tsleep
@@ -190,6 +223,17 @@ This is an atomic operation, which guarantees that a
 interlocked by
 .Fa slz
 will not be missed.
+.Pp
+The
+.Fn wakeup_one
+function is used to make the first process/thread in the queue that is
+sleeping on the parameter
+.Fa ident
+runnable.
+This can prevent the system from becoming saturated
+when a large number of processes/threads are sleeping on the same address,
+but only one of them can actually do any useful work when made
+runnable.
 .Sh IMPLEMENTATION NOTES
 Unlike
 .Fx ,
@@ -210,6 +254,9 @@ The
 function returns
 .Li 0
 if awakened, otherwise an appropriate error code is returned.
+.Sh FILES
+The various sleep functions are in
+.Pa /sys/kern/kern_synch.c .
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er EWOULDBLOCK
@@ -239,6 +286,19 @@ It appeared in a very early version of Unix.
 .Nm Tsleep
 appeared in
 .Bx 4.4 .
+.Pp
+.Nm ssleep
+appeared in
+.Dx 1.6 ,
+.Nm zsleep
+in
+.Dx 2.0 ,
+and
+.Nm lksleep
+and
+.Nm mtxsleep
+in
+.Dx 2.3 .
 .Sh AUTHORS
 .An -nosplit
 This manual page was written by