[src/trunk]: src/share/man/man9 Update cv_timedwaitbt documentation to reflec...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/677a7e96e50a
branches:  trunk
changeset: 971743:677a7e96e50a
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun May 03 04:04:32 2020 +0000

description:
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.)

diffstat:

 share/man/man9/condvar.9 |  34 +++++++++++++++++++++-------------
 1 files changed, 21 insertions(+), 13 deletions(-)

diffs (60 lines):

diff -r 3be01ab41970 -r 677a7e96e50a share/man/man9/condvar.9
--- a/share/man/man9/condvar.9  Sun May 03 01:26:39 2020 +0000
+++ b/share/man/man9/condvar.9  Sun May 03 04:04:32 2020 +0000
@@ -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 @@
 .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 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.
+is zero.
+On return,
+.Fn cv_timedwaitbt
+and
+.Fn cv_timedwaitbt_sig
+subtract the time elapsed from
+.Fa bt
+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 @@
         * 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)