Module Name: src
Committed By: riastradh
Date: Sun May 3 04:04:32 UTC 2020
Modified Files:
src/share/man/man9: condvar.9
Log Message:
Update cv_timedwaitbt documentation to reflect useful reality.
Previously, a negative timeout was forbidden (kassert), a zero or
maybe even just a sufficiently small timeout would block forever, and
we would subtract the time elapsed -- possibly longer than the
timeout, leading to a negative updated timeout, which would trip the
kassert the next time around if used as advertised. DERP.
Now negative timeouts are still forbidden in order to detect usage
mistakes, but a zero timeout fails immediately and we clamp the
subtracted time to be at least zero so you can always safely call
cv_timedwaitbt in a loop.
(An alternative would be to fail immediately for all nonpositive
timeouts, and to leave in the timespec the negative time we overshot,
but it's not clear this would be useful.)
To generate a diff of this commit:
cvs rdiff -u -r1.22 -r1.23 src/share/man/man9/condvar.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/condvar.9
diff -u src/share/man/man9/condvar.9:1.22 src/share/man/man9/condvar.9:1.23
--- src/share/man/man9/condvar.9:1.22 Fri Apr 10 17:16:21 2020
+++ src/share/man/man9/condvar.9 Sun May 3 04:04:32 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: condvar.9,v 1.22 2020/04/10 17:16:21 ad Exp $
+.\" $NetBSD: condvar.9,v 1.23 2020/05/03 04:04:32 riastradh Exp $
.\"
.\" Copyright (c) 2006, 2007, 2008, 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -213,19 +213,28 @@ if the timeout expires.
.It Fn cv_timedwaitbt "cv" "mtx" "bt" "epsilon"
.It Fn cv_timedwaitbt_sig "cv" "mtx" "bt" "epsilon"
.Pp
-Similar to
-.Fn cv_timedwait
+As per
+.Fn cv_wait
and
-.Fn cv_timedwait_sig ,
-but
+.Fn cv_wait_sig ,
+but will return early if the duration
+.Fa bt
+has elapsed, immediately if
+.Fa bt
+is zero.
+On return,
+.Fn cv_timedwaitbt
+and
+.Fn cv_timedwaitbt_sig
+subtract the time elapsed from
.Fa bt
-is decremented in place with the amount of time actually waited, and on
-return contains the amount of time remaining, possibly negative if the
-timeout expired.
+in place, or set it to zero if there is no time remaining.
.Pp
The hint
-.Fa epsilon
-requests that the wakeup not be delayed more than
+.Fa epsilon ,
+which can be
+.Dv DEFAULT_TIMEOUT_EPSILON
+if in doubt, requests that the wakeup not be delayed more than
.Fa bt Li "+" Fa epsilon ,
so that the system can coalesce multiple wakeups within their
respective epsilons into a single high-resolution clock interrupt or
@@ -291,10 +300,9 @@ Consuming a resource:
* alloted time, return an error.
*/
struct bintime timeout = { .sec = 5, .frac = 0 };
- const struct bintime epsilon = { .sec = 1, .frac = 0 };
while (res->state == BUSY) {
- error = cv_timedwaitbt(&res->condvar, \\
- &res->mutex, &timeout, &epsilon);
+ error = cv_timedwaitbt(&res->condvar,
+ &res->mutex, &timeout, DEFAULT_TIMEOUT_EPSILON);
if (error) {
KASSERT(error == EWOULDBLOCK);
if (res->state != BUSY)
