COND_INIT(9)

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