'\"
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" Copyright 2024 Oxide Computer Company
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.Dd September 15, 2024
.Dt TASKQ 9F
.Os
.Sh NAME
.Nm taskq ,
.Nm ddi_taskq_create ,
.Nm ddi_taskq_destroy ,
.Nm ddi_taskq_dispatch ,
.Nm ddi_taskq_wait ,
.Nm ddi_taskq_suspend ,
.Nm ddi_taskq_suspended ,
.Nm ddi_taskq_resume
.Nd Kernel task queue operations
.Sh SYNOPSIS
.In sys/sunddi.h
.Ft "ddi_taskq_t *"
.Fo ddi_taskq_create
.Fa "dev_info_t *dip"
.Fa "const char *name
.Fa "int nthreads"
.Fa "pri_t pri"
.Fa "uint_t cflags"
.Fc
.Ft void
.Fo ddi_taskq_destroy
.Fa "ddi_taskq_t *tq"
.Fc
.Ft int
.Fo ddi_taskq_dispatch
.Fa "ddi_taskq_t *tq"
.Fa "void (*func)(void *)"
.Fa "void *arg"
.Fa "uint_t dflags"
.Fc
.Ft void
.Fo ddi_taskq_wait
.Fa "ddi_taskq_t *tq"
.Fc
.Ft void
.Fo ddi_taskq_suspend
.Fa "ddi_taskq_t *tq"
.Fc
.Ft boolean_t
.Fo ddi_taskq_suspended
.Fa "ddi_taskq_t *tq"
.Fc
.Ft void
.Fo ddi_taskq_resume
.Fa "ddi_taskq_t *tq"
.Fc
.Sh INTERFACE LEVEL
illumos DDI specific (illumos DDI)
.Bl -tag -width Fa
.It Fa dip
Pointer to the device's dev_info structure.
May be
.Dv NULL
for kernel modules that do not have an associated
.Ft dev_info_t
structure.
.It Fa name
Descriptive string.
Only alphanumeric characters can be used in
.Fa 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.
.It Fa nthreads
Number of threads servicing the task queue.
Note that the request ordering is guaranteed
.Pq tasks are processed in the order scheduled
if the taskq is created with a single servicing thread.
.It Fa pri
Priority of threads servicing the task queue.
Drivers and modules should specify
.Dv TASKQ_DEFAULTPRI .
.It Fa cflags
Must be 0.
.It Fa func
Callback function to call.
.It Fa arg
Argument to the callback function.
.It dflags
Possible
.Fa dflags
are:
.Bl -tag -width Ds
.It Dv DDI_SLEEP
Allow sleeping
.Pq blocking
until memory is available.
.It Dv DDI_NOSLEEP
Return
.Dv DDI_FAILURE
immediately if memory is not  available.
.El
.It tq
Pointer to a task queue
.Pq Ft ddi_taskq_t * .
.El
.Sh 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:
.Bl -enum
.It
You have a task that isn't time-critical, but a current code path that is.
.It
You have a task that may require grabbing locks that a thread already holds.
.It
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.
.It
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.
.It
A task queue is just a simple way to launch multiple tasks in parallel.
.El
.Pp
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.
.Pp
The
.Fn ddi_taskq_create
function creates a task queue instance.
.Pp
The
.Fn ddi_taskq_dispatch
function places
.Fa func
on the list for later execution.
The
.Fa dflag
argument specifies whether it is allowed to sleep waiting for memory.
.Dv DDI_SLEEP
dispatches can sleep and are guaranteed to succeed.
.Dv DDI_NOSLEEP
dispatches are guaranteed not to sleep but may fail
.Po
return
.Dv DDI_FAILURE
.Pc
if resources are not available.
.Pp
The
.Fn ddi_taskq_destroy
function waits for any scheduled tasks to complete, then destroys the taskq
.Fa tq .
The caller should guarantee that no new tasks are scheduled for the closing
taskq.
.Pp
The
.Fn ddi_taskq_wait
function waits for all previously scheduled tasks to complete.
Note that this function does not stop any new task dispatches.
.Pp
The
.Fn ddi_taskq_suspend
function suspends all task execution until
.Fn ddi_taskq_resume
is called.
Although
.Fn 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
.Fn ddi_taskq_suspend
will not be executed.
Because it will trigger a deadlock, the
.Fn ddi_taskq_suspend
function should never be called by a task executing on a taskq.
.Pp
The
.Fn ddi_taskq_suspended
function returns
.Dv B_TRUE
if the taskq
.Fa tq
is suspended, and
.Dv B_FALSE
otherwise.
It is intended to ASSERT that the task queue is suspended.
.Pp
The
.Fn ddi_taskq_resume
function resumes task queue execution.
.Sh CONTEXT
All functions may be called from the user or kernel contexts.
.Pp
Additionally, the
.Fn ddi_taskq_dispatch
function may be called from the interrupt context only if the
.Dv DDI_NOSLEEP
flag is set.
.Sh RETURN VALUES
The
.Fn ddi_taskq_create
function creates an opaque handle that is used for all other taskq operations.
It returns a
.Ft "ddi_taskq_t *"
pointer on success and
.Dv NULL
on failure.
.Pp
The
.Fn ddi_taskq_dispatch
function returns
.Dv DDI_FAILURE
if it can't dispatch a task and returns
.Dv DDI_SUCCESS
if dispatch succeeded.
.Pp
The
.Fn ddi_taskq_suspended
function returns
.Dv B_TRUE
if
.Fa tq
is suspended.
Otherwise
.Dv B_FALSE
is returned.