Implement condition variables.

2 files changed, 208 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 84b7872..9f15f79 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -13,7 +13,7 @@ MAN9=	CONDSPLASSERT.9 DELAY.9 KASSERT.9 MD5.9 SPLASSERT.9 \
 	VOP_STRATEGY.9 \
 	accf_data.9 accf_http.9 at_exit.9 at_fork.9 atomic.9 \
 	bios.9 boot.9 buf.9 \
-	cd.9 copy.9 \
+	cd.9 condvar.9 copy.9 \
 	devfs_add_devswf.9 devfs_link.9 devfs_remove_dev.9 devstat.9 \
 	devtoname.9 \
 	fetch.9 \
@@ -77,6 +77,17 @@ MLINKS+=atomic.9 atomic_subtract.9
 MLINKS+=atomic.9 atomic_store.9
 MLINKS+=at_exit.9 rm_at_exit.9
 MLINKS+=at_fork.9 rm_at_fork.9
+MLINKS+=condvar.9 cv_init.9
+MLINKS+=condvar.9 cv_destroy.9
+MLINKS+=condvar.9 cv_wait.9
+MLINKS+=condvar.9 cv_wait_sig.9
+MLINKS+=condvar.9 cv_timedwait.9
+MLINKS+=condvar.9 cv_timedwait_sig.9
+MLINKS+=condvar.9 cv_signal.9
+MLINKS+=condvar.9 cv_broadcast.9
+MLINKS+=condvar.9 cv_waitq_remove.9
+MLINKS+=condvar.9 cv_waitq_empty.9
+MLINKS+=condvar.9 cv_wmesg.9
 MLINKS+=copy.9 copyin.9 copy.9 copyinstr.9 copy.9 copyout.9 copy.9 copystr.9
 MLINKS+=devfs_link.9 devfs_makelink.9
 MLINKS+=devstat.9 devicestat.9 devstat.9 devstat_add_entry.9 
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