COND_INIT(9) | Kernel Developer's Manual | 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);
    }

July 28, 2025 | Debian