Implement condition variables.

1 files changed, 196 insertions, 0 deletions

diff --git a/share/man/man9/condvar.9 b/share/man/man9/condvar.9
new file mode 100644
index 0000000..6e483c7
--- /dev/null
+++ b/share/man/man9/condvar.9
@@ -0,0 +1,196 @@
+.\" 
+.\" Copyright (C) 2000 Jason Evans <jasone@freebsd.org>. All rights reserved.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible 
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 11, 2000
+.Dt CONDVAR 9
+.Os
+.Sh NAME
+.Nm condvar ,
+.Nm cv_init ,
+.Nm cv_destroy ,
+.Nm cv_wait ,
+.Nm cv_wait_sig ,
+.Nm cv_timedwait ,
+.Nm cv_timedwait_sig ,
+.Nm cv_signal ,
+.Nm cv_broadcast ,
+.Nm cv_waitq_remove ,
+.Nm cv_waitq_empty ,
+.Nm cv_wmesg
+.Nd kernel condition variable
+.Sh SYNOPSIS
+.Fd #include <sys/condvar.h>
+.Ft void
+.Fn cv_init "struct cv *cvp" "const char *desc"
+.Ft void
+.Fn cv_destroy "struct cv *cvp"
+.Ft void
+.Fn cv_wait "struct cv *cvp" "struct mtx *mp"
+.Ft int
+.Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp"
+.Ft int
+.Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo"
+.Ft int
+.Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "int timo"
+.Ft void
+.Fn cv_signal "struct cv *cvp"
+.Ft void
+.Fn cv_broadcast "struct cv *cvp"
+.Ft void
+.Fn cv_waitq_remove "struct proc *p"
+.Ft int
+.Fn cv_waitq_empty "struct cv *cvp"
+.Ft const char *
+.Fn cv_wmesg "struct cv *cvp"
+.Sh DESCRIPTION
+Condition variables are used in conjunction with mutexes to wait for conditions
+to occur.
+Condition variables are created with
+.Fn cv_init ,
+where
+.Ar cvp
+is a pointer to space for a
+.Dv struct cv ,
+and
+.Ar desc
+is a pointer to a null-terminated character string that describes the condition
+variable.
+Condition variables are destroyed with
+.Fn cv_destroy .
+Threads wait on condition variables by calling
+.Fn cv_wait ,
+.Fn cv_wait_sig ,
+.Fn cv_timedwait ,
+or
+.Fn cv_timedwait_sig .
+Threads unblock waiters by calling
+.Fn cv_signal
+to unblock one waiter, or
+.Fn cv_broadcast
+to unblock all waiters.
+.Fn cv_waitq_remove
+removes a waiting thread from a condition variable wait queue, if it is on one.
+.Fn cv_waitq_empty
+reports whether there are any waiters on
+.Ar cvp .
+.Fn cv_wmesg
+returns the description string of
+.Ar cvp ,
+as set by the initial call to
+.Fn cv_init .
+.Pp
+A thread must hold
+.Ar mp
+before calling
+.Fn cv_wait ,
+.Fn cv_wait_sig ,
+.Fn cv_timedwait ,
+or
+.Fn cv_timedwait_sig .
+When a thread waits on a condition,
+.Ar mp
+is atomically released before the thread is blocked, then atomically reacquired
+before the function call returns.
+All waiters must pass the same
+.Ar mp
+in conjunction with
+.Ar cvp .
+A thread must hold
+.Ar mp
+while calling
+.Fn cv_signal
+or
+.Fn cv_broadcast ,
+even though it isn't passed as an argument.
+.Pp
+When
+.Fn cv_wait ,
+.Fn cv_wait_sig ,
+.Fn cv_timedwait ,
+and
+.Fn cv_timedwait_sig
+unblock, their calling threads are made runnable.
+.Fn cv_timedwait
+and
+.Fn cv_timedwait_sig
+wait for at most
+.Ar timo
+/
+.Dv HZ
+seconds before being unblocked and returning
+.Er EWOULDBLOCK ;
+otherwise, they return 0.
+.Fn cv_wait_sig
+and
+.Fn cv_timedwait_sig
+return prematurely with a value of
+.Er EINTR
+or
+.Er ERESTART
+if a signal is caught, or 0 if signaled via
+.Fn cv_signal
+or
+.Fn cv_broadcast .
+.Sh RETURN VALUES
+If successful,
+.Fn cv_wait_sig ,
+.Fn cv_timedwait ,
+and
+.Fn cv_timedwait_sig
+return 0.
+Otherwise, a non-zero error code is returned.
+.Pp
+.Fn cv_waitq_empty
+returns non-zero if there are no threads on the wait queue; 0 otherwise.
+.Pp
+.Fn cv_wmesg
+returns the description string that was passed to
+.Fn cv_init .
+.Sh ERRORS
+.Fn cv_wait_sig
+and
+.Fn cv_timedwait_sig
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EINTR
+An unmasked signal was caught.
+.It Bq Er ERESTART
+A masked signal was caught.
+.El
+.Pp
+.Fn cv_timedwait
+and
+.Fn cv_timedwait_sig
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EWOULDBLOCK
+Timeout expired.
+.El
+.Sh SEE ALSO
+.Xr msleep 9 ,
+.Xr mutex 9