misc/48671: Add description how to convert from tsleep(9)/wakeup(9) to condvar(9)

[Izumi Tsutsui <tsutsui%ceres.dti.ne.jp@localhost>]

>Number:         48671
>Category:       misc
>Synopsis:       Add description how to convert from tsleep(9)/wakeup(9) to 
>condvar(9)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Fri Mar 21 08:25:00 +0000 2014
>Originator:     Izumi Tsutsui
>Release:        NetBSD 6.1.3
>Organization:
>Environment:
System: NetBSD 6.1.3
>Description:
rmind@ posted "converting to condvar(9)" message on tech-kern:
http://mail-index.netbsd.org/tech-kern/2010/09/05/msg008831.html
It would be worth to also mention it in deprecated tsleep(9)/wakeup(9)
man page to nuke them in future release.
>How-To-Repeat:
man tsleep

Currently it just says:
>> The interfaces described in this manual page are obsolete and will be
>> removed from a future version of the system.
>> 
>> The ltsleep() interface has been obsoleted and removed from the system.
>> 
>> Please see the condvar(9), mutex(9), and rwlock(9) manual pages for
>> information on kernel synchronisation primitives.

>Fix:
Here is a dumb patch which adds "MIGRATING TO CONDVAR" section
to ltsleep(9) per his description. (needs more proofreadings though)

Index: ltsleep.9
===================================================================
RCS file: /cvsroot/src/share/man/man9/ltsleep.9,v
retrieving revision 1.14
diff -u -p -d -r1.14 ltsleep.9
--- ltsleep.9   28 Jan 2012 13:26:12 -0000      1.14
+++ ltsleep.9   21 Mar 2014 08:01:24 -0000
@@ -166,6 +166,80 @@ If
 .Fn tsleep
 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 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.
+It depends which
+.Fn cv_wait*
+variant to use, and it would be guessed by looking at the corresponding
+.Fn tsleep
+usage.
+There are two arguments of interest:
+.Ar timo
+and
+.Ar priority .
+The
+.Ar priority
+value may have OR'ed such flags:
+.Dv PNORELOCK
+and
+.Dv PCATCH .
+.Pp
+The
+.Dv PCATCH
+means that blocking thread should be awoken on signal
+and it would be done by
+.Xr cv_wait_sig 9 .
+.Pp
+The
+.Ar timo
+value, if it is not zero, indicates how long to sleep and
+it would be done by
+.Xr cv_timedwait 9 .
+.Pp
+If both
+.Dv PCACHE
+and
+non-zero
+.Ar timo
+value are specified, there is
+.Xr cv_timedwait_sig 9 .
+.Pp
+If none is specified, there is
+.Xr cv_wait 9 .
+.Pp
+Interlock (mutex) must be held across
+.Fn cv_wait*
+and
+.Fn cv_broadcast
+calls, in order to protect our state.
+Which means that some old code might require amending
+(to remove
+.Dv PNORELOCK
+or replace
+.Xr simple_lock 9
+use) or addition of locking.
 .Sh SEE ALSO
 .Xr sigaction 2 ,
 .Xr condvar 9 ,