'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" 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]
.TH taskq 9F "1 Mar 2005" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
taskq, ddi_taskq_create, ddi_taskq_destroy, ddi_taskq_dispatch, ddi_taskq_wait,
ddi_taskq_suspend, taskq_suspended, ddi_taskq_resume \- Kernel task queue
operations
.SH SYNOPSIS
.LP
.nf
#include <sys/sunddi.h>

\fBddi_taskq_t *\fR\fBddi_taskq_create\fR(\fBdev_info_t *\fR\fIdip\fR, \fBconst char *\fR\fIname\fR,
     \fBint\fR \fInthreads\fR, \fBpri_t\fR  \fIpri\fR, \fBuint_t\fR  \fIcflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_taskq_destroy\fR(\fBddi_taskq_t *\fR\fItq\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_taskq_dispatch\fR(\fBddi_taskq_t *\fR\fItq\fR, \fBvoid (*\fR \fIfunc)\fR(void *), 
     \fBvoid *\fR\fIarg\fR, \fBuint_t\fR \fIdflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_taskq_wait\fR(\fBddi_taskq_t *\fR\fItq\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_taskq_suspend\fR(\fBddi_taskq_t *\fR\fItq\fR);
.fi

.LP
.nf
\fBboolean_t\fR \fBddi_taskq_suspended\fR(\fBddi_taskq_t *\fR\fItq\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_taskq_resume\fR(\fBddi_taskq_t *\fR\fItq\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 12n
.rt  
Pointer to the device's dev_info structure. May be NULL for kernel
modules that do not have an associated dev_info structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 12n
.rt  
Descriptive string. Only alphanumeric characters can be used            in name
and spaces are not allowed. The name should be unique.
.RE

.sp
.ne 2
.mk
.na
\fB\fInthreads\fR\fR
.ad
.RS 12n
.rt  
Number of threads servicing the task queue. Note that the request ordering is
guaranteed (tasks are processed in the order scheduled) if the \fBtaskq\fR is
created with a single servicing thread.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpri\fR\fR
.ad
.RS 12n
.rt  
Priority of threads servicing the task queue. Drivers and modules should
specify TASKQ_DEFAULTPRI.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcflags\fR\fR
.ad
.RS 12n
.rt  
Should pass 0 as flags.
.RE

.sp
.ne 2
.mk
.na
\fB\fIfunc\fR\fR
.ad
.RS 12n
.rt  
Callback function to call.
.RE

.sp
.ne 2
.mk
.na
\fB\fIarg\fR\fR
.ad
.RS 12n
.rt  
Argument to the callback function.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdflags\fR\fR
.ad
.RS 12n
.rt  
Possible \fIdflags\fR are:
.sp
.ne 2
.mk
.na
\fBDDI_SLEEP\fR
.ad
.RS 15n
.rt  
Allow sleeping (blocking) until memory is available.
.RE

.sp
.ne 2
.mk
.na
\fBDDI_NOSLEEP\fR
.ad
.RS 15n
.rt  
Return DDI_FAILURE immediately if memory is not  available.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fItq\fR\fR
.ad
.RS 12n
.rt  
Pointer to a task queue (ddi_taskq_t *).
.RE

.sp
.ne 2
.mk
.na
\fB\fItp\fR\fR
.ad
.RS 12n
.rt  
Pointer to a thread structure.
.RE

.SH DESCRIPTION
.sp
.LP
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:
.RS +4
.TP
1.
You have a task that isn't time-critical, but a current code path that is.
.RE
.RS +4
.TP
2.
You have a task that may require grabbing locks that a thread already holds.
.RE
.RS +4
.TP
3.
You have a task that needs to block (for example, to wait for memory), but a
have a thread that cannot block in its current context.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
5.
A task queue is just a simple way to launch multiple tasks in parallel.
.RE
.sp
.LP
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 and should not depend on the execution of another task or a deadlock
may occur. A \fBtaskq\fR created with a single servicing thread guarantees that
all the tasks are serviced in the order in which they are scheduled.
.sp
.LP
The \fBddi_taskq_create()\fR function creates a task queue instance.
.sp
.LP
The \fBddi_taskq_dispatch()\fR function places \fBtaskq\fR on the list for
later execution. The \fIdflag\fR argument specifies whether it is allowed 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 \fBDDI_FAILURE\fR) if resources are not available.
.sp
.LP
The \fBddi_taskq_destroy()\fR function waits for any scheduled tasks to
complete, then destroys the \fBtaskq\fR. The caller should guarantee that no
new tasks are scheduled for the closing \fBtaskq\fR.
.sp
.LP
The \fBddi_taskq_wait()\fR function waits for all previously scheduled tasks to
complete. Note that this function does not stop any new task dispatches.
.sp
.LP
The \fBddi_taskq_suspend()\fR function suspends all task execution until
\fBddi_taskq_resume()\fR is called. Although \fBddi_taskq_suspend()\fR attempts
to suspend pending tasks, there are no guarantees that they will be suspended.
The only guarantee is that all tasks dispatched after \fBddi_taskq_suspend()\fR
will not be executed. Because it will trigger a deadlock, the
\fBddi_taskq_suspend()\fR function should never be called by a task executing
on a \fBtaskq\fR.
.sp
.LP
The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is
suspended, and \fBB_FALSE\fR otherwise. It is intended to ASSERT that the task
queue is suspended.
.sp
.LP
The \fBddi_taskq_resume()\fR function resumes task queue execution.
.SH RETURN VALUES
.sp
.LP
The \fBddi_taskq_create()\fR function creates an opaque handle that is used for
all other \fBtaskq\fR operations. It returns a \fBtaskq\fR pointer on success
and NULL on failure.
.sp
.LP
The \fBddi_taskq_dispatch()\fR function returns \fBDDI_FAILURE\fR if it can't
dispatch a task and returns \fBDDI_SUCCESS\fR if dispatch succeeded.
.sp
.LP
The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is
suspended. Otherwise \fBB_FALSE\fR is returned.
.SH CONTEXT
.sp
.LP
All functions may be called from the user or kernel contexts.
.sp
.LP
Addtionally, the \fBddi_taskq_dispatch\fR function may be called from the
interrupt context only if the DDI_NOSLEEP flag is set.