TASKQ(9F) Kernel Functions for Drivers TASKQ(9F)

NAME

taskq, ddi_taskq_create, ddi_taskq_destroy, ddi_taskq_dispatch,
ddi_taskq_wait, ddi_taskq_suspend, ddi_taskq_suspended,
ddi_taskq_resume - Kernel task queue operations

SYNOPSIS

#include <sys/sunddi.h>

ddi_taskq_t *
ddi_taskq_create(dev_info_t *dip, const char *name, int nthreads,
pri_t pri, uint_t cflags);

void
ddi_taskq_destroy(ddi_taskq_t *tq);

int
ddi_taskq_dispatch(ddi_taskq_t *tq, void (*func)(void *), void *arg,
uint_t dflags);

void
ddi_taskq_wait(ddi_taskq_t *tq);

void
ddi_taskq_suspend(ddi_taskq_t *tq);

boolean_t
ddi_taskq_suspended(ddi_taskq_t *tq);

void
ddi_taskq_resume(ddi_taskq_t *tq);

INTERFACE LEVEL

illumos DDI specific (illumos DDI)

dip Pointer to the device's dev_info structure. May be NULL
for kernel modules that do not have an associated
dev_info_t structure.

name Descriptive string. Only alphanumeric characters can be
used in name and spaces are not allowed. The name should
be unique. If the created task queue is per-device
driver instance then the instance number should be
included to aid in identification and uniqueness.

nthreads Number of threads servicing the task queue. Note that
the request ordering is guaranteed (tasks are processed
in the order scheduled) if the taskq is created with a
single servicing thread.

pri Priority of threads servicing the task queue. Drivers
and modules should specify TASKQ_DEFAULTPRI.

cflags Must be 0.

func Callback function to call.

arg Argument to the callback function.

dflags Possible dflags are:

DDI_SLEEP
Allow sleeping (blocking) until memory is
available.

DDI_NOSLEEP
Return DDI_FAILURE immediately if memory is not
available.

tq Pointer to a task queue (ddi_taskq_t *).

DESCRIPTION

A kernel task queue is a mechanism for general-purpose asynchronous
task scheduling that enables tasks to be performed at a later time by
another thread. There are several reasons why you may utilize
asynchronous task scheduling:

1. You have a task that isn't time-critical, but a current code path
that is.

2. You have a task that may require grabbing locks that a thread
already holds.

3. You have a task that needs to block Pq for example, to wait for
memory , but you have a thread that cannot block in its current
context.

4. You have a code path that can't complete because of a specific
condition, but also can't sleep or fail. In this case, the task
is immediately queued and then is executed after the condition
disappears.

5. A task queue is just a simple way to launch multiple tasks in
parallel.

A task queue consists of a list of tasks, together with one or more
threads to service the list. If a task queue has a single service
thread, all tasks are guaranteed to execute in the order they were
dispatched. Otherwise they can be executed in any order. Note that
since tasks are placed on a list, execution of one task should not
depend on the execution of another task or a deadlock may occur.

The ddi_taskq_create() function creates a task queue instance.

The ddi_taskq_dispatch() function places func on the list for later
execution. The dflag argument specifies whether it is allowed to sleep
waiting for memory. DDI_SLEEP dispatches can sleep and are guaranteed
to succeed. DDI_NOSLEEP dispatches are guaranteed not to sleep but may
fail (return DDI_FAILURE) if resources are not available.

The ddi_taskq_destroy() function waits for any scheduled tasks to
complete, then destroys the taskq tq. The caller should guarantee that
no new tasks are scheduled for the closing taskq.

The ddi_taskq_wait() function waits for all previously scheduled tasks
to complete. Note that this function does not stop any new task
dispatches.

The ddi_taskq_suspend() function suspends all task execution until
ddi_taskq_resume() is called. Although ddi_taskq_suspend() attempts to
suspend pending tasks, there are no guarantees that they will be
suspended. The only guarantee is that all tasks dispatched after
ddi_taskq_suspend() will not be executed. Because it will trigger a
deadlock, the ddi_taskq_suspend() function should never be called by a
task executing on a taskq.

The ddi_taskq_suspended() function returns B_TRUE if the taskq tq is
suspended, and B_FALSE otherwise. It is intended to ASSERT that the
task queue is suspended.

The ddi_taskq_resume() function resumes task queue execution.

CONTEXT

All functions may be called from the user or kernel contexts.

Additionally, the ddi_taskq_dispatch() function may be called from the
interrupt context only if the DDI_NOSLEEP flag is set.

RETURN VALUES

The ddi_taskq_create() function creates an opaque handle that is used
for all other taskq operations. It returns a ddi_taskq_t * pointer on
success and NULL on failure.

The ddi_taskq_dispatch() function returns DDI_FAILURE if it can't
dispatch a task and returns DDI_SUCCESS if dispatch succeeded.

The ddi_taskq_suspended() function returns B_TRUE if tq is suspended.
Otherwise B_FALSE is returned.

illumos September 15, 2024 illumos