Thu Dec 12 02:34:55 2019 UTC ()
Point out that spurious wake-ups are possible, and that an LWP should
check for resource availability after being awoken.


(pgoyette)
diff -r1.20 -r1.21 src/share/man/man9/condvar.9
cvs diff -r1.20 -r1.21 src/share/man/man9/condvar.9 (expand / switch to unified diff)

--- src/share/man/man9/condvar.9 2019/04/12 11:02:22 1.20
+++ src/share/man/man9/condvar.9 2019/12/12 02:34:55 1.21
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: condvar.9,v 1.20 2019/04/12 11:02:22 abhinav Exp $ 1.\" $NetBSD: condvar.9,v 1.21 2019/12/12 02:34:55 pgoyette Exp $
2.\" 2.\"
3.\" Copyright (c) 2006, 2007, 2008 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2006, 2007, 2008 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran. 7.\" by Andrew Doran.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -17,27 +17,27 @@ @@ -17,27 +17,27 @@
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd November 12, 2017 30.Dd December 12, 2019
31.Dt CONDVAR 9 31.Dt CONDVAR 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm cv , 34.Nm cv ,
35.Nm condvar , 35.Nm condvar ,
36.Nm cv_init , 36.Nm cv_init ,
37.Nm cv_destroy , 37.Nm cv_destroy ,
38.Nm cv_wait , 38.Nm cv_wait ,
39.Nm cv_wait_sig , 39.Nm cv_wait_sig ,
40.Nm cv_timedwait , 40.Nm cv_timedwait ,
41.Nm cv_timedwait_sig , 41.Nm cv_timedwait_sig ,
42.Nm cv_timedwaitbt , 42.Nm cv_timedwaitbt ,
43.Nm cv_timedwaitbt_sig , 43.Nm cv_timedwaitbt_sig ,
@@ -134,26 +134,33 @@ It will be released once the LWP has pre @@ -134,26 +134,33 @@ It will be released once the LWP has pre
134before 134before
135.Fn cv_wait 135.Fn cv_wait
136returns. 136returns.
137.Pp 137.Pp
138A small window exists between testing for availability of a resource and 138A small window exists between testing for availability of a resource and
139waiting for the resource with 139waiting for the resource with
140.Fn cv_wait , 140.Fn cv_wait ,
141in which the resource may become available again. 141in which the resource may become available again.
142The interlock is used to guarantee that the resource will not be signalled 142The interlock is used to guarantee that the resource will not be signalled
143as available until the calling LWP has begun to wait for it. 143as available until the calling LWP has begun to wait for it.
144.Pp 144.Pp
145Non-interruptable waits have the potential to deadlock the system, and so must 145Non-interruptable waits have the potential to deadlock the system, and so must
146be kept short (typically, under one second). 146be kept short (typically, under one second).
 147.Pp
 148Upon being awakened, the calling LWP should verify the availability
 149of the resource (or other condition).
 150It should not blindly assume that the resource is now available.
 151If the resource is still not available, the calling LWP may call
 152.Fn cv_wait
 153again to continue waiting.
147.It Fn cv_wait_sig "cv" "mtx" 154.It Fn cv_wait_sig "cv" "mtx"
148.Pp 155.Pp
149As per 156As per
150.Fn cv_wait , 157.Fn cv_wait ,
151but causes the current LWP to wait interruptably. 158but causes the current LWP to wait interruptably.
152If the LWP receives a signal, or is interrupted by another condition such 159If the LWP receives a signal, or is interrupted by another condition such
153as its containing process exiting, the wait is ended early and an error 160as its containing process exiting, the wait is ended early and an error
154code returned. 161code returned.
155.Pp 162.Pp
156If 163If
157.Fn cv_wait_sig 164.Fn cv_wait_sig
158returns as a result of a signal, the return value is 165returns as a result of a signal, the return value is
159.Er ERESTART 166.Er ERESTART