'\" 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 \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.