108 lines
2.6 KiB
Groff
108 lines
2.6 KiB
Groff
.\" $OpenBSD: cond_init.9,v 1.3 2022/03/11 14:42:08 visa Exp $ */
|
|
.\"
|
|
.\" Copyright (c) 2017 David Gwynne <dlg@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: March 11 2022 $
|
|
.Dt COND_INIT 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cond_init ,
|
|
.Nm cond_wait ,
|
|
.Nm cond_signal ,
|
|
.Nm COND_INITIALIZER
|
|
.Nd wait condition API
|
|
.Sh SYNOPSIS
|
|
.In sys/systm.h
|
|
.Ft void
|
|
.Fn "cond_init" "struct cond *c"
|
|
.Ft void
|
|
.Fn "cond_wait" "struct cond *c" "const char *wmesg"
|
|
.Ft void
|
|
.Fn "cond_signal" "struct cond *c"
|
|
.Fn "COND_INITIALIZER"
|
|
.Sh DESCRIPTION
|
|
The wait condition API allows a thread to sleep while it waits for
|
|
a notification, aka signal, that pending work has completed.
|
|
.Pp
|
|
.Fn cond_init
|
|
initialises the wait condition
|
|
.Fa c
|
|
for use.
|
|
.Pp
|
|
.Fn cond_wait
|
|
is used to sleep on the wait condition
|
|
.Fa c
|
|
until whatever the thread is waiting on calls
|
|
.Fn cond_signal .
|
|
.Fa wmesg
|
|
is a pointer to a character string indicating the reason the thread
|
|
is sleeping.
|
|
.Pp
|
|
.Fn cond_signal
|
|
is used to notify the thread waiting on
|
|
.Fa c
|
|
that the work has finished and it may proceed.
|
|
.Pp
|
|
.Fn COND_INITIALIZER
|
|
initialises a declaration of a cond for use.
|
|
.Sh CONTEXT
|
|
.Fn cond_init ,
|
|
and
|
|
.Fn cond_signal
|
|
can be called during autoconf, from process context, or from interrupt
|
|
context.
|
|
.Pp
|
|
.Fn cond_wait
|
|
can be called from process context.
|
|
.Sh EXAMPLES
|
|
.Xr taskq_barrier 9
|
|
is implemented using the wait condition API.
|
|
The following is a commented copy of the implementation:
|
|
.Bd -literal
|
|
static void taskq_barrier_task(void *);
|
|
|
|
void
|
|
taskq_barrier(struct taskq *tq)
|
|
{
|
|
struct cond c;
|
|
struct task t;
|
|
|
|
/*
|
|
* any currently running work has to have finished
|
|
* before this new task can be run.
|
|
*/
|
|
|
|
cond_init(&c);
|
|
task_init(&t, taskq_barrier_task, &c);
|
|
|
|
task_add(tq, &t);
|
|
|
|
/* wait until the task runs and signals completion */
|
|
cond_wait(&c, "tqbar");
|
|
}
|
|
|
|
static void
|
|
taskq_barrier_task(void *p)
|
|
{
|
|
struct cond *c = p;
|
|
|
|
/*
|
|
* all previous tasks have run, signal the thread waiting
|
|
* in taskq_barrier
|
|
*/
|
|
|
|
cond_signal(c);
|
|
}
|
|
.Ed
|