Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add mtsleep(9) and a description of how it, tsleep(9), and w...
details: https://anonhg.NetBSD.org/src/rev/e5c83cfc4f4a
branches: trunk
changeset: 327955:e5c83cfc4f4a
user: skrll <skrll%NetBSD.org@localhost>
date: Sat Mar 22 11:24:35 2014 +0000
description:
Add mtsleep(9) and a description of how it, tsleep(9), and wakeup(9)
should all be replaced with condvar(9).
While here clear out the lock(9) reference(s) and the obsoleted example.
Based on misc/48671
diffstat:
distrib/sets/lists/comp/mi | 5 +-
share/man/man9/Makefile | 4 +-
share/man/man9/ltsleep.9 | 127 +++++++++++++++++++++++++++++++++++++++-----
3 files changed, 118 insertions(+), 18 deletions(-)
diffs (256 lines):
diff -r 7a7ac8a2c226 -r e5c83cfc4f4a distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Sat Mar 22 09:46:33 2014 +0000
+++ b/distrib/sets/lists/comp/mi Sat Mar 22 11:24:35 2014 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1884 2014/03/21 13:30:39 wiz Exp $
+# $NetBSD: mi,v 1.1885 2014/03/22 11:24:35 skrll Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -10453,6 +10453,7 @@
./usr/share/man/cat9/mstohz.0 comp-sys-catman .cat
./usr/share/man/cat9/mtocl.0 comp-sys-catman .cat
./usr/share/man/cat9/mtod.0 comp-sys-catman .cat
+./usr/share/man/cat9/mtsleep.0 comp-sys-catman .cat
./usr/share/man/cat9/mutex.0 comp-sys-catman .cat
./usr/share/man/cat9/mutex_destroy.0 comp-sys-catman .cat
./usr/share/man/cat9/mutex_enter.0 comp-sys-catman .cat
@@ -17144,6 +17145,7 @@
./usr/share/man/html9/mstohz.html comp-sys-htmlman html
./usr/share/man/html9/mtocl.html comp-sys-htmlman html
./usr/share/man/html9/mtod.html comp-sys-htmlman html
+./usr/share/man/html9/mtsleep.html comp-sys-htmlman html
./usr/share/man/html9/mutex.html comp-sys-htmlman html
./usr/share/man/html9/mutex_destroy.html comp-sys-htmlman html
./usr/share/man/html9/mutex_enter.html comp-sys-htmlman html
@@ -23996,6 +23998,7 @@
./usr/share/man/man9/mstohz.9 comp-sys-man .man
./usr/share/man/man9/mtocl.9 comp-sys-man .man
./usr/share/man/man9/mtod.9 comp-sys-man .man
+./usr/share/man/man9/mtsleep.9 comp-sys-man .man
./usr/share/man/man9/mutex.9 comp-sys-man .man
./usr/share/man/man9/mutex_destroy.9 comp-sys-man .man
./usr/share/man/man9/mutex_enter.9 comp-sys-man .man
diff -r 7a7ac8a2c226 -r e5c83cfc4f4a share/man/man9/Makefile
--- a/share/man/man9/Makefile Sat Mar 22 09:46:33 2014 +0000
+++ b/share/man/man9/Makefile Sat Mar 22 11:24:35 2014 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.375 2014/03/18 10:21:47 hannken Exp $
+# $NetBSD: Makefile,v 1.376 2014/03/22 11:24:36 skrll Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -450,7 +450,7 @@
lock.9 lockinit.9 lock.9 lockmgr.9 \
lock.9 lockstatus.9 lock.9 lockmgr_printinfo.9 lock.9 transferlockers.9 \
lock.9 spinlockinit.9 lock.9 spinlockmgr.9
-MLINKS+=ltsleep.9 wakeup.9 ltsleep.9 tsleep.9
+MLINKS+=ltsleep.9 wakeup.9 ltsleep.9 mtsleep.9 ltsleep.9 tsleep.9
MLINKS+=malloc.9 MALLOC.9 malloc.9 realloc.9 malloc.9 free.9 malloc.9 FREE.9
MLINKS+=malloc.9 malloc_roundup.9 malloc.9 malloc_type_attach.9
MLINKS+=malloc.9 malloc_type_detach.9 malloc.9 malloc_type_setlimit.9
diff -r 7a7ac8a2c226 -r e5c83cfc4f4a share/man/man9/ltsleep.9
--- a/share/man/man9/ltsleep.9 Sat Mar 22 09:46:33 2014 +0000
+++ b/share/man/man9/ltsleep.9 Sat Mar 22 11:24:35 2014 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: ltsleep.9,v 1.14 2012/01/28 13:26:12 wiz Exp $
+.\" $NetBSD: ltsleep.9,v 1.15 2014/03/22 11:24:36 skrll Exp $
.\"
.\" Copyright (c) 1996, 2002, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -32,12 +32,15 @@
.Os
.Sh NAME
.Nm ltsleep ,
+.Nm mtsleep ,
.Nm tsleep ,
.Nm wakeup
.Nd process context sleep and wakeup
.Sh SYNOPSIS
.In sys/proc.h
.Ft int
+.Fn "mtsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "kmutex_t *mtx"
+.Ft int
.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo"
.Ft void
.Fn "wakeup" "wchan_t ident"
@@ -58,7 +61,9 @@
.Pp
These functions implement voluntary context switching.
.Fn tsleep
-is used throughout the kernel whenever processing in the current context
+and
+.Fn mtsleep
+are used throughout the kernel whenever processing in the current context
can not continue for any of the following reasons:
.Bl -bullet -offset indent
.It
@@ -67,9 +72,6 @@
The current process needs resources
.Pq e.g., memory
which are temporarily unavailable.
-.It
-The current process wants access to data-structures which are locked by
-other processes.
.El
.Pp
The function
@@ -83,7 +85,9 @@
.Pp
The
.Fn tsleep
-function takes the following arguments:
+and
+.Fn mtsleep
+functions take the following arguments:
.Bl -tag -width priority
.It Fa ident
An identifier of the
@@ -129,31 +133,52 @@
.El
.Pp
The
+.Fn mtsleep
+function takes an additional argument and flag:
+.Bl -tag -width priority
+.It Fa mtx
+A
+.Xr mutex 9
+representing the lock protecting the data-structures. On entry
+.Fn mtsleep
+will release the lock and re-acquire the lock on return.
+.It Fa priority
+If the flag
+.Dv PNORELOCK
+is OR'ed into
+.Fa priority
+then
+.Fn mtsleep
+will not re-acquire the lock.
+.El
+.Pp
+The
.Fn wakeup
function will mark all processes which are currently sleeping on the identifier
.Fa ident
as runnable.
Eventually, each of the processes will resume execution in the kernel
context, causing a return from
-.Fn tsleep .
+.Fn tsleep
+or
+.Fn mtsleep .
Note that processes returning from sleep should always re-evaluate the
conditions that blocked them, since a call to
.Fn wakeup
merely signals a
.Em possible
change to the blocking conditions.
-For example, when two or more processes are waiting for an exclusive-access
-lock
-.Pq see Xr lock 9 ,
-only one of them will succeed in acquiring the lock when it is released.
-All others will have to go back to sleep and wait for the next opportunity.
.Sh RETURN VALUES
.Fn tsleep
-returns 0 if it returns as a result of a
+and
+.Fn mtsleep
+return 0 if they return as a result of a
.Fn wakeup .
If a
.Fn tsleep
-returns as a result of a signal, the return value is
+and
+.Fn mtsleep
+return as a result of a signal, the return value is
.Er ERESTART
if the signal has the
.Dv SA_RESTART
@@ -164,13 +189,85 @@
otherwise.
If
.Fn tsleep
+and
+.Fn mtsleep
returns because of a timeout it returns
.Er EWOULDBLOCK .
+.Sh MIGRATING TO CONDVAR
+Note the conversion from tsleep/wakeup into
+.Xr condvar 9
+should not be done mechanically i.e.
+.Dq blindly .
+Code logic should be understood before changing, and it may also need to be
+revisited for the change.
+Please also read
+.Xr condvar 9
+man page.
+.Pp
+The
+.Fn tsleep
+and
+.Fn mtsleep ,
+and
+.Fn wakeup
+pairs should generally be replaced by
+.Xr cv_wait 9 /
+.Xr cv_wait_sig 9 /
+.Xr cv_timedwait 9 /
+.Xr cv_timedwait_sig 9
+and
+.Xr cv_signal 9 /
+.Xr cv_broadcast 9
+pairs.
+The
+.Fn cv_wait*
+variant to use can be determinded from looking at the corresponding
+.Fn tsleep
+usage.
+.Pp
+There are two arguments of interest:
+.Ar timo
+and
+.Ar priority .
+The
+.Ar priority
+value may have OR'ed the flag
+.Dv PCATCH .
+.Pp
+The
+.Dv PCATCH
+flag means that the blocking thread should be awoken on signal, and
+the sleep call should be replaced with
+.Xr cv_wait_sig 9 .
+.Pp
+The
+.Ar timo
+value, if it is not zero, indicates how long to sleep, and
+the sleep call should be replaced with
+.Xr cv_timedwait 9 .
+.Pp
+If both the
+.Dv PCATCH
+flag and a non-zero
+.Ar timo
+value are specified, then
+.Xr cv_timedwait_sig 9
+should be used.
+.Pp
+A
+.Xr mutex 9
+(interlock) must be held across
+.Fn cv_wait
+and
+.Fn cv_broadcast
+calls, in order to protect state.
+Most old code will require the addition of locking, whereas some will
+require amending to remove
+.Dv PNORELOCK .
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr condvar 9 ,
.Xr hz 9 ,
-.Xr lock 9 ,
.Xr mutex 9 ,
.Xr rwlock 9
.Sh HISTORY
Home |
Main Index |
Thread Index |
Old Index