NetBSD-Bugs archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

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

>Number:         48671
>Category:       misc
>Synopsis:       Add description how to convert from tsleep(9)/wakeup(9) to 
>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
System: NetBSD 6.1.3
rmind@ posted "converting to condvar(9)" message on tech-kern:
It would be worth to also mention it in deprecated tsleep(9)/wakeup(9)
man page to nuke them in future release.
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.

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
+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.
+.Fn tsleep
+.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
+.Xr cv_signal 9 /
+.Xr cv_broadcast 9
+It depends which
+.Fn cv_wait*
+variant to use, and it would be guessed by looking at the corresponding
+.Fn tsleep
+There are two arguments of interest:
+.Ar timo
+.Ar priority .
+.Ar priority
+value may have OR'ed such flags:
+means that blocking thread should be awoken on signal
+and it would be done by
+.Xr cv_wait_sig 9 .
+.Ar timo
+value, if it is not zero, indicates how long to sleep and
+it would be done by
+.Xr cv_timedwait 9 .
+If both
+.Ar timo
+value are specified, there is
+.Xr cv_timedwait_sig 9 .
+If none is specified, there is
+.Xr cv_wait 9 .
+Interlock (mutex) must be held across
+.Fn cv_wait*
+.Fn cv_broadcast
+calls, in order to protect our state.
+Which means that some old code might require amending
+(to remove
+or replace
+.Xr simple_lock 9
+use) or addition of locking.
 .Xr sigaction 2 ,
 .Xr condvar 9 ,

Home | Main Index | Thread Index | Old Index