Add a condvar(9) manual page (based on FreeBSD's).
authorSascha Wildner <saw@online.de>
Fri, 16 Apr 2010 08:37:33 +0000 (10:37 +0200)
committerSascha Wildner <saw@online.de>
Fri, 16 Apr 2010 08:37:33 +0000 (10:37 +0200)
Submitted-by: Venkatesh Srinivas <me@endeavour.zapto.org>
share/man/man9/Makefile
share/man/man9/condvar.9 [new file with mode: 0644]

index c875bcf..7582204 100644 (file)
@@ -29,6 +29,7 @@ MAN=  accept_filter.9 \
        byteorder.9 \
        callout.9 \
        cd.9 \
+       condvar.9 \
        contigmalloc.9 \
        copy.9 \
        crit_enter.9 \
@@ -335,6 +336,15 @@ MLINKS+=callout.9 callout_active.9 \
        callout.9 callout_stop.9 \
        callout.9 timeout.9 \
        callout.9 untimeout.9
+MLINKS+=condvar.9 cv_broadcast.9 \
+       condvar.9 cv_broadcastpri.9 \
+       condvar.9 cv_destroy.9 \
+       condvar.9 cv_init.9 \
+       condvar.9 cv_signal.9 \
+       condvar.9 cv_timedwait.9 \
+       condvar.9 cv_timedwait_sig.9 \
+       condvar.9 cv_wait.9 \
+       condvar.9 cv_wait_sig.9
 MLINKS+=contigmalloc.9 contigfree.9
 MLINKS+=copy.9 copyin.9 \
        copy.9 copyinstr.9 \
diff --git a/share/man/man9/condvar.9 b/share/man/man9/condvar.9
new file mode 100644 (file)
index 0000000..471788c
--- /dev/null
@@ -0,0 +1,178 @@
+.\"
+.\" Copyright (C) 2010 The DragonFly Project. All rights reserved.
+.\" 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: src/share/man/man9/condvar.9,v 1.11 2004/11/08 18:15:11 jhb Exp $
+.\"
+.Dd April 16, 2010
+.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_broadcastpri
+.Nd kernel condition variable
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/systm.h
+.In 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 lock *l"
+.Ft int
+.Fn cv_wait_sig "struct cv *cvp" "struct lock *l"
+.Ft int
+.Fn cv_timedwait "struct cv *cvp" "struct lock *l" "int timo"
+.Ft int
+.Fn cv_timedwait_sig "struct cv *cvp" "struct lock *l" "int timo"
+.Ft void
+.Fn cv_signal "struct cv *cvp"
+.Ft void
+.Fn cv_broadcast "struct cv *cvp"
+.Ft void
+.Fn cv_broadcastpri "struct cv *cvp" "int pri"
+.Sh DESCRIPTION
+Condition variables are used in conjunction with locks to wait for conditions
+to occur.
+Condition variables are created with
+.Fn cv_init ,
+where
+.Fa cvp
+is a pointer to space for a
+.Vt struct cv ,
+and
+.Fa 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
+or
+.Fn cv_broadcastpri
+to unblock all waiters.
+.Fn cv_broadcastpri
+is a synonym for
+.Fn cv_broadcast
+in
+.Dx .
+.Pp
+A thread must hold
+.Fa l
+before calling
+.Fn cv_wait ,
+.Fn cv_wait_sig ,
+.Fn cv_timedwait ,
+or
+.Fn cv_timedwait_sig .
+When a thread waits on a condition,
+.Fa l
+is atomically released before the thread is blocked, then atomically reacquired
+before the function call returns.
+All waiters must pass the same
+.Fa l
+in conjunction with
+.Fa cvp .
+.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
+.Fa timo
+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 IMPLEMENTATION NOTES
+Condition variables exist primarily for code imported from other systems; for
+.Dx
+code, the
+.Fn tsleep /
+.Fn wakeup
+family of functions should be used instead.
+.Pp
+Condition variables can currently only release
+.Xr lockmgr 9
+locks.
+.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.
+.Sh FILES
+Condition variables are implemented in
+.Pa /sys/kern/kern_condvar.c .
+The public interface and structure is found in
+.Pa /sys/sys/condvar.h .
+.Sh SEE ALSO
+.Xr lockmgr 9 ,
+.Xr tsleep 9
+.Sh HISTORY
+Condition variables appeared in
+.Dx 2.7 .
+.Sh AUTHORS
+This manual page was written by
+.An Jason Evans
+for
+.Fx .