unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

TASK_ADD(9)              BSD Kernel Developer's Manual             TASK_ADD(9)

NAME
     taskq_create, taskq_destroy, task_set, task_add, task_del,
     TASK_INITIALIZER -- task queues

SYNOPSIS
     #include <&lt;sys/task.h>&gt;

     struct taskq *
     taskq_create(const char *name, unsigned int nthreads, int ipl,
         unsigned int flags);

     void
     taskq_destroy(struct taskq *tq);

     void
     task_set(struct task *t, void (*fn)(void *), void *arg);

     int
     task_add(struct taskq *tq, struct task *t);

     int
     task_del(struct taskq *tq, struct task *t);

     extern struct taskq *const systq;
     extern struct taskq *const systqmp;

     TASK_INITIALIZER(void (*fn)(void *), void *arg);

DESCRIPTION
     The taskq API provides a mechanism to defer work to a process context.

     taskq_create() allocates a taskq and a set of threads to be used to com-
     plete work that would be inappropriate for the shared system taskq.  The
     name argument specifies the name of the kernel threads that are created
     to service the work on the taskq.  nthreads specifies the number of
     threads that will be created to handle the work.  ipl specifies the high-
     est interrupt protection level at which task_add() and task_del() will be
     called against the created taskq.  See spl(9) for a list of the IPLs.
     The operational characteristics of the taskq can be altered by OR'ing the
     following defines into the flags argument:

           TASKQ_MPSAFE
                The threads servicing the taskq will be run without the kernel
                big lock.

           TASKQ_CANTSLEEP
                The tasks run via the taskq cannot sleep.

     taskq_destroy() causes the resources associated with a previously created
     taskq to be freed.  It will wait till all the tasks in the work queue are
     completed before returning.  Calling taskq_destroy() against the system
     taskq is an error and will lead to undefined behaviour or a system fault.

     It is the responsibility of the caller to provide the task_set(),
     task_add(), and task_del() functions with pre-allocated task structures.

     task_set() prepares the task structure t to be used in future calls to
     task_add() and task_del().  t will be prepared to call the function fn
     with the argument specified by arg.  Once initialised, the t structure
     can be used repeatedly in calls to task_add() and task_del() and does not
     need to be reinitialised unless the function called and/or its argument
     must change.

     task_add() schedules the execution of the work specified by the task
     structure t on the tq taskq.  The task structure must already be ini-
     tialised by task_set().

     task_del() will remove the task structure t from the taskq tq.  If the
     work was already executed or has not been added to the taskq, the call
     will have no effect.  Calling task_del() against a different taskq than
     the one given in a previous call to task_add() is an error and will lead
     to undefined behaviour.

     The kernel provides two system taskqs: systq, which executes while hold-
     ing the kernel lock, and systqmp, which does not hold the kernel lock
     during execution.  They can both be used by any subsystem for short lived
     tasks.  They are serviced by a single thread and can therefore provide
     predictable ordering of work.  Work can be scheduled on the system taskqs
     from callers at or below IPL_HIGH.

     A task declaration can be initialised with the TASK_INITIALIZER() macro.
     The task will be prepared to call the function specified by the fn argu-
     ment with the void * argument given in arg.

CONTEXT
     taskq_create() and taskq_destroy() can be called during autoconf, or from
     process context.  task_set(), task_add(), and task_del() can be called
     during autoconf, from process context, or from interrupt context.

RETURN VALUES
     taskq_create() returns a pointer to a taskq structure on success or NULL
     on failure.

     task_add() will return 1 if the task t was added to the taskq tq or 0 if
     the task was already queued.

     task_del() will return 1 if the task t was removed from the taskq tq or 0
     if the task was not already on the queue.

SEE ALSO
     autoconf(9), spl(9)

HISTORY
     The task API was originally written by David Gwynne <dlg@openbsd.org>.
     The task API first appeared in OpenBSD 5.5.

BSD                            February 9, 2015                            BSD