WORKQUEUE(9)

WORKQUEUE(9) | Kernel Developer's Manual | WORKQUEUE(9)

# NAME

workqueue — simple do-it-in-thread-context framework

# SYNOPSIS

#include <sys/workqueue.h>
int
workqueue_create(struct workqueue **wqp, const char *name, void (*func)(struct work *, void *), void *arg, pri_t prio, int ipl, int flags);
void
workqueue_enqueue(struct workqueue *wq, struct work *wk, struct cpu_info *ci);
void
workqueue_wait(struct workqueue *wq, struct work *wk);
void
workqueue_destroy(struct workqueue *wq);

# DESCRIPTION

The workqueue utility routines are provided to defer work which is needed to be processed in a thread context.
workqueue_create() creates a workqueue. It takes the following arguments:

wqp
  Specify where to store the created workqueue.
name
  The name of the workqueue.
func
  The function to be called for each work.
arg
  An argument to be passed as a second argument of func.
prio
  The priority level for the worker threads.
ipl
  The highest IPL at which this workqueue is used.
flags
  The value of 0 indicates a standard create operation, however the following flags may be bitwise ORed together:
  `WQ_MPSAFE`
    Specifies that the workqueue is multiprocessor safe and does its own locking; otherwise the kernel lock will be held while processing work.
  `WQ_PERCPU`
    Specifies that the workqueue should have a separate queue for each CPU, thus the work could be enqueued on concrete CPUs.

workqueue_enqueue() enqueues the work wk into the workqueue wq.
If the `WQ_PERCPU` flag was set on workqueue creation, the ci argument may be used to specify the CPU on which the work should be enqueued. Also it may be `NULL`, then work will be enqueued on the current CPU. If `WQ_PERCPU` flag was not set, ci must be `NULL`.
The enqueued work will be processed in a thread context. A work must not be enqueued again until the callback is called by the workqueue framework.
workqueue_wait() waits for a specified work wk on the workqueue wq to finish. The caller must ensure that no new work will be enqueued to the workqueue beforehand. Note that if the workqueue is `WQ_PERCPU`, the caller can enqueue a new work to another queue other than the waiting queue.
workqueue_destroy() destroys a workqueue and frees associated resources. The caller should ensure that the workqueue has no work enqueued beforehand.

# RETURN VALUES

workqueue_create() returns 0 on success. Otherwise, it returns an errno(2).

# CODE REFERENCES

The workqueue subsystem is implemented within the file sys/kern/subr_workqueue.c.

# SEE ALSO

callout(9), condvar(9), kthread(9), softint(9)

December 28, 2017 | NetBSD 8.3