1taskq(9F) Kernel Functions for Drivers taskq(9F)
2
6 taskq, ddi_taskq_create, ddi_taskq_destroy, ddi_taskq_dispatch,
7 ddi_taskq_wait, ddi_taskq_suspend, taskq_suspended, ddi_taskq_resume -
8 Kernel task queue operations
9
11 #include <sys/sunddi.h>
12 ddi_taskq_t *ddi_taskq_create(dev_info_t *dip, const char *name,
14 int nthreads, pri_t pri, uint_t cflags);
15 void ddi_taskq_destroy(ddi_taskq_t *tq);
18 int ddi_taskq_dispatch(ddi_taskq_t *tq, void (* func)(void *),
21 void *arg, uint_t dflags);
22 void ddi_taskq_wait(ddi_taskq_t *tq);
25 void ddi_taskq_suspend(ddi_taskq_t *tq);
28 boolean_t ddi_taskq_suspended(ddi_taskq_t *tq);
31 void ddi_taskq_resume(ddi_taskq_t *tq);
34
37 Solaris DDI specific (Solaris DDI)
38
40 dip Pointer to the device's dev_info structure. May be NULL for
41 kernel modules that do not have an associated
42 dev_info structure.
43 name Descriptive string. Only alphanumeric characters can be
46 used in name and spaces are not allowed. The
47 name should be unique.
48 nthreads Number of threads servicing the task queue. Note that the
51 request ordering is guaranteed (tasks are processed in the
52 order scheduled) if the taskq is created with a single ser‐
53 vicing thread.
54 pri Priority of threads servicing the task queue. Drivers and
57 modules should specify TASKQ_DEFAULTPRI.
58 cflags Should pass 0 as flags.
61 func Callback function to call.
64 arg Argument to the callback function.
67 dflags Possible dflags are:
70 DDI_SLEEP Allow sleeping (blocking) until memory is
72 available.
73 DDI_NOSLEEP Return DDI_FAILURE immediately if memory is
76 not available.
77 tq Pointer to a task queue (ddi_taskq_t *).
81 tp Pointer to a thread structure.
84
87 A kernel task queue is a mechanism for general-purpose asynchronous
88 task scheduling that enables tasks to be performed at a later time by
89 another thread. There are several reasons why you may utilize asynchro‐
90 nous task scheduling:
91 1. You have a task that isn't time-critical, but a current code
93 path that is.
94 2. You have a task that may require grabbing locks that a
96 thread already holds.
97 3. You have a task that needs to block (for example, to wait
99 for memory), but a have a thread that cannot block in its
100 current context.
101 4. You have a code path that can't complete because of a spe‐
103 cific condition, but also can't sleep or fail. In this case,
104 the task is immediately queued and then is executed after
105 the condition disappears.
106 5. A task queue is just a simple way to launch multiple tasks
108 in parallel.
109 A task queue consists of a list of tasks, together with one or more
112 threads to service the list. If a task queue has a single service
113 thread, all tasks are guaranteed to execute in the order they were dis‐
114 patched. Otherwise they can be executed in any order. Note that since
115 tasks are placed on a list, execution of one task and should not depend
116 on the execution of another task or a deadlock may occur. A taskq cre‐
117 ated with a single servicing thread guarantees that all the tasks are
118 serviced in the order in which they are scheduled.
119 The ddi_taskq_create() function creates a task queue instance.
122 The ddi_taskq_dispatch() function places taskq on the list for later
125 execution. The dflag argument specifies whether it is allowed sleep
126 waiting for memory. DDI_SLEEP dispatches can sleep and are guaranteed
127 to succeed. DDI_NOSLEEP dispatches are guaranteed not to sleep but may
128 fail (return DDI_FAILURE) if resources are not available.
129 The ddi_taskq_destroy() function waits for any scheduled tasks to com‐
132 plete, then destroys the taskq. The caller should guarantee that no new
133 tasks are scheduled for the closing taskq.
134 The ddi_taskq_wait() function waits for all previously scheduled tasks
137 to complete. Note that this function does not stop any new task dis‐
138 patches.
139 The ddi_taskq_suspend() function suspends all task execution until
142 ddi_taskq_resume() is called. Although ddi_taskq_suspend() attempts to
143 suspend pending tasks, there are no guarantees that they will be sus‐
144 pended. The only guarantee is that all tasks dispatched after
145 ddi_taskq_suspend() will not be executed. Because it will trigger a
146 deadlock, the ddi_taskq_suspend() function should never be called by a
147 task executing on a taskq.
148 The ddi_taskq_suspended() function returns B_TRUE if taskq is sus‐
151 pended, and B_FALSE otherwise. It is intended to ASSERT that the task
152 queue is suspended.
153 The ddi_taskq_resume() function resumes task queue execution.
156
158 The ddi_taskq_create() function creates an opaque handle that is used
159 for all other taskq operations. It returns a taskq pointer on success
160 and NULL on failure.
161 The ddi_taskq_dispatch() function returns DDI_FAILURE if it can't dis‐
164 patch a task and returns DDI_SUCCESS if dispatch succeeded.
165 The ddi_taskq_suspended() function returns B_TRUE if taskq is sus‐
168 pended. Otherwise B_FALSE is returned.
169
171 All functions may be called from the user or kernel contexts.
172 Addtionally, the ddi_taskq_dispatch function may be called from the
175 interrupt context only if the DDI_NOSLEEP flag is set.
176SunOS 5.11 1 Mar 2005 taskq(9F)