WORKQ_ADD_TASK(9)

NAME
workq_add_task, workq_queue_task, workq_create, workq_destroy - work queues

SYNOPSIS
#include <sys/workq.h>
int
workq_add_task(struct workq *wq, int flags, void (*func)(void *, void *), void *arg1, void *arg2);
void
workq_queue_task(struct workq *wq, struct workq_task *wqt, int flags, void (*func)(void *, void *), void *arg1, void *arg2);
struct workq *
workq_create(const char *name, int maxthreads, int ipl);
void
workq_destroy(struct workq *wq);

DESCRIPTION
The workq framework API provides a mechanism to defer tasks to a process context when it is impossible to run such a task in the current context.

workq_add_task() adds a task to the workq specified by the wq argument. If wq is NULL the task will be run by the kernel's generic work queue. Tasks in the kernel's generic work queue should not run for long periods of time, they should use their own workq for task processing. A task is specified by the func argument, and will be called with arg1 and arg2. Two arguments are allowed to provide additional flexibility to the called function. In many cases, one may wish to perform an action on a target. Two arguments allow both target and action to be passed without the need for a wrapper struct to contain them in a single argument. The flags argument specifies creation and runtime characteristics of the task. The possible flags are:

WQ_WAITOK
    Wait for resources to become available. If resources are not available and this flag is not set then workq_add_task() will return ENOMEM.

workq_queue_task() adds a task to the workq specified by the wq argument, using the memory provided by the wqt argument to store that task's entry on the workq. The flags, func, arg1, and arg2 arguments are the same as those in the workq_add_task() function. However, because the caller is responsible for providing the memory needed to store the task on the workq, workq_queue_task() is guaranteed to succeed.

workq_create() creates a workq to be used when tasks would unnecessarily block the kernel workq. The name argument specifies the name of the kernel threads that run the tasks. maxthreads specifies the maximum number of worker threads that will service the work queue. ipl specifies the interrupt protection level at which the workq can be safely used. See spl(9) for a list of the IPLs.

workq_destroy() causes the resources associated with a previously created workq to be freed. It will wait till all the tasks in the work queue are completed before returning.

workq_add_task(), workq_create(), and workq_destroy() can be called during autoconf(9) or from process context. workq_add_task() can additionally be called from interrupt context if WQ_WAITOK is not specified.

SEE ALSO
autoconf(9), spl(9)

HISTORY
The workq framework was originally written by Ted Unangst <tedu@openbsd.org>, and heavily influenced by arguments with David Gwynne <dlg@openbsd.org>. The workq framework first appeared in OpenBSD 4.2.