[src/trunk]: src/share/man/man9 Document cv_timedwaitclock.

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

details:   https://anonhg.NetBSD.org/src/rev/8c77b73c5584
branches:  trunk
changeset: 1009781:8c77b73c5584
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun May 03 04:05:50 2020 +0000

description:
Document cv_timedwaitclock.

diffstat:

 share/man/man9/condvar.9 |  79 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 78 insertions(+), 1 deletions(-)

diffs (111 lines):

diff -r 73424d59c87c -r 8c77b73c5584 share/man/man9/condvar.9
--- a/share/man/man9/condvar.9  Sun May 03 04:05:28 2020 +0000
+++ b/share/man/man9/condvar.9  Sun May 03 04:05:50 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: condvar.9,v 1.25 2020/05/03 04:05:28 riastradh Exp $
+.\"    $NetBSD: condvar.9,v 1.26 2020/05/03 04:05:50 riastradh Exp $
 .\"
 .\" Copyright (c) 2006, 2007, 2008, 2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -65,6 +65,13 @@
 .Ft int
 .Fn cv_timedwaitbt_sig "kcondvar_t *cv" "kmutex_t *mtx" "struct bintime *bt" \
 "const struct bintime *epsilon"
+.Ft int
+.Fn cv_timedwaitclock "kcondvar_t *cv" "kmutex_t *mtx" \
+"struct timespec *timeout" "clockid_t clockid" "int flags" \
+"const struct bintime *epsilon"
+.Fn cv_timedwaitclock_sig "kcondvar_t *cv" "kmutex_t *mtx" \
+"struct timespec *timeout" "clockid_t clockid" "int flags" \
+"const struct bintime *epsilon"
 .Ft void
 .Fn cv_signal "kcondvar_t *cv"
 .Ft void
@@ -257,6 +264,47 @@
 resolution and by scheduling competition, which may delay the wakeup by
 more than
 .Fa bt Li "+" Fa epsilon .
+.It Fn cv_timedwaitclock "cv" "lock" "timeout" "clockid" "flags" "epsilon"
+.It Fn cv_timedwaitclock_sig "cv" "lock" "timeout" "clockid" "flags" "epsilon"
+As per
+.Fn cv_wait
+and
+.Fn cv_wait_sig ,
+but will return early in case of timeout.
+The timeout is measured by the clock
+.Fa clockid ;
+see
+.Xr clock_settime 2
+for the supported options.
+The
+.Fa flags
+may be
+.Dv TIMER_RELTIME
+for a relative duration or
+.Dv TIMER_ABSTIME
+for an absolute time on the clock.
+For relative timeouts,
+.Fn cv_timedwaitclock
+and
+.Fn cv_timedwaitclock_sig
+subtract the elapsed time from
+.Fa timeout
+in place, or set it to zero if there is no time remaining.
+The hint
+.Fa epsilon
+requests a maximum delay after the timeout before wakeup.
+.Pp
+It is safe to pass in values of
+.Fa clockid
+and
+.Fa flags
+from userland, and timeouts copied in from userland; if anything is
+wrong with them,
+.Fn cv_timedwaitclock
+or
+.Fn cv_timedwaitclock_sig
+will return
+.Er EINVAL .
 .It Fn cv_signal "cv"
 .Pp
 Awaken one LWP waiting on the specified condition variable.
@@ -332,6 +380,29 @@
        consume(res);
 .Ed
 .Pp
+Consuming a resource using a timeout specified in a syscall by
+userland:
+.Bd -literal
+       struct timespec timeout;
+
+       error = copyin(SCARG(uap, timeout), &timeout, sizeof timeout);
+       if (error)
+               return error;
+
+       mutex_enter(&res->mutex);
+       while (res->state == BUSY) {
+               error = cv_timedwaitclock_sig(&res->condvar,
+                   &res->mutex, &timeout, SCARG(uap, clock_id),
+                   SCARG(uap, flags), DEFAULT_TIMEOUT_EPSILON);
+               if (error)
+                       break;
+       }
+       mutex_exit(&res->mutex);
+       if (error)
+               return error;
+       consume(res);
+.Ed
+.Pp
 Releasing a resource for the next consumer to use:
 .Bd -literal
        mutex_enter(&res->mutex);
@@ -371,3 +442,9 @@
 .Fn cv_timedwaitbt_sig
 primitives first appeared in
 .Nx 9.0 .
+The
+.Fn cv_timedwaitclock
+and
+.Fn cv_timedwaitclock_sig
+primitives first appeared in
+.Nx 10.0 .