From 85869e85ef04badcfe62a2efe95f1de59ad56c0f Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Mon, 12 Apr 2010 02:35:32 +0200 Subject: [PATCH] sleep.9: Document mtxsleep() and tsleep_interlock(). Also, update HISTORY a bit. Submitted-by: Venkatesh Srinivas --- share/man/man9/Makefile | 7 +-- share/man/man9/sleep.9 | 98 +++++++++++++++++++++++++++++++++-------- 2 files changed, 83 insertions(+), 22 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index a787cf7af2..c875bcfda0 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 \ diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 index 55bbebdcdd..c4bc21a36f 100644 --- a/share/man/man9/sleep.9 +++ b/share/man/man9/sleep.9 @@ -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 . @@ -56,16 +56,17 @@ .\" 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 @@ -75,13 +76,17 @@ .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 -- 2.41.0