Module Name: src Committed By: skrll Date: Sat Mar 22 11:24:36 UTC 2014
Modified Files: src/distrib/sets/lists/comp: mi src/share/man/man9: Makefile ltsleep.9 Log Message: 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 To generate a diff of this commit: cvs rdiff -u -r1.1884 -r1.1885 src/distrib/sets/lists/comp/mi cvs rdiff -u -r1.375 -r1.376 src/share/man/man9/Makefile cvs rdiff -u -r1.14 -r1.15 src/share/man/man9/ltsleep.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/distrib/sets/lists/comp/mi diff -u src/distrib/sets/lists/comp/mi:1.1884 src/distrib/sets/lists/comp/mi:1.1885 --- src/distrib/sets/lists/comp/mi:1.1884 Fri Mar 21 13:30:39 2014 +++ src/distrib/sets/lists/comp/mi Sat Mar 22 11:24:35 2014 @@ -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 Index: src/share/man/man9/Makefile diff -u src/share/man/man9/Makefile:1.375 src/share/man/man9/Makefile:1.376 --- src/share/man/man9/Makefile:1.375 Tue Mar 18 10:21:47 2014 +++ src/share/man/man9/Makefile Sat Mar 22 11:24:36 2014 @@ -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 @@ MLINKS+=lock.9 simple_lock_init.9 lock.9 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 Index: src/share/man/man9/ltsleep.9 diff -u src/share/man/man9/ltsleep.9:1.14 src/share/man/man9/ltsleep.9:1.15 --- src/share/man/man9/ltsleep.9:1.14 Sat Jan 28 13:26:12 2012 +++ src/share/man/man9/ltsleep.9 Sat Mar 22 11:24:36 2014 @@ -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 to await the r 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 @@ condition has cleared. .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 @@ will return .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 @@ and 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