| Current File : //usr/share/man/man9f/taskq.9f |
'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.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.