NAME

cond_init, cond_wait, cond_signal, COND_INITIALIZER — wait condition API

SYNOPSIS

#include <sys/systm.h>

void
cond_init(struct cond *c);

void
cond_wait(struct cond *c, const char *wmesg);

void
cond_signal(struct cond *c);

void
cond_signal_handler(void *c);

COND_INITIALIZER();

DESCRIPTION

The wait condition API allows a thread to sleep while it waits for a notification, aka signal, that pending work has completed.

cond_init() initialises the wait condition c for use.

cond_wait() is used to sleep on the wait condition c until whatever the thread is waiting on calls cond_signal() or cond_signal_handler(). wmesg is a pointer to a character string indicating the reason the thread is sleeping.

cond_signal() and cond_signal_handler() notify the thread waiting on c that the work has finished and it may proceed. cond_signal() and cond_signal_handler() operate identically, the only difference is the type of argument they take. cond_signal_handler() takes a void * argument, allowing it to be used directly with APIs such as task_set(9) and timeout_set(9).

COND_INITIALIZER() initialises a declaration of a cond for use.

CONTEXT

cond_init(), cond_signal(), and cond_signal_handler() can be called during autoconf, from process context, or from interrupt context.

cond_wait() can be called from process context.

EXAMPLES

taskq_barrier(9) is implemented using the wait condition API. The following is a commented copy of the implementation:

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);
}