xref: /dflybsd-src/share/man/man9/condvar.9 (revision 3426d2c2fbeac9a3dbd8dbb031afd28623ead0fa)

.\"
.\" 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 June 29, 2018
.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_mtx_wait ,
.Nm cv_mtx_wait_sig ,
.Nm cv_mtx_timedwait ,
.Nm cv_mtx_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_mtx_wait "struct cv *cvp" "struct mtx *m"
.Ft int
.Fn cv_mtx_wait_sig "struct cv *cvp" "struct mtx *m"
.Ft int
.Fn cv_mtx_timedwait "struct cv *cvp" "struct mtx *m" "int timo"
.Ft int
.Fn cv_mtx_timedwait_sig "struct cv *cvp" "struct mtx *m" "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
and discards the
.Fa pri
parameter.
.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
/ 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 .
.Pp
.Fn cv_mtx_wait ,
.Fn cv_mtx_wait_sig ,
.Fn cv_mtx_timedwait ,
and
.Fn cv_mtx_timedwait_sig
work the same as
.Fn cv_wait ,
.Fn cv_wait_sig ,
.Fn cv_timedwait ,
and
.Fn cv_timedwait_sig
except that they take
.Vt struct mtx
argument
.Fa m .
.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.
.Sh RETURN VALUES
If successful,
.Fn cv_wait_sig ,
.Fn cv_timedwait ,
.Fn cv_timedwait_sig
.Fn cv_mtx_wait_sig ,
.Fn cv_mtx_timedwait ,
and
.Fn cv_mtx_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 locking 9 ,
.Xr lockmgr 9 ,
.Xr mutex 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 .