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 9.2