1taskq(9F)                Kernel Functions for Drivers                taskq(9F)
2
3
4

NAME

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

SYNOPSIS

11       #include <sys/sunddi.h>
12
13       ddi_taskq_t *ddi_taskq_create(dev_info_t *dip, const char *name,
14            int nthreads, pri_t  pri, uint_t  cflags);
15
16
17       void ddi_taskq_destroy(ddi_taskq_t *tq);
18
19
20       int ddi_taskq_dispatch(ddi_taskq_t *tq, void (* func)(void *),
21            void *arg, uint_t dflags);
22
23
24       void ddi_taskq_wait(ddi_taskq_t *tq);
25
26
27       void ddi_taskq_suspend(ddi_taskq_t *tq);
28
29
30       boolean_t ddi_taskq_suspended(ddi_taskq_t *tq);
31
32
33       void ddi_taskq_resume(ddi_taskq_t *tq);
34
35

INTERFACE LEVEL

37       Solaris DDI specific (Solaris DDI)
38

PARAMETERS

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
44
45       name        Descriptive  string.  Only  alphanumeric  characters can be
46                   used            in name and spaces  are  not  allowed.  The
47                   name should be unique.
48
49
50       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
55
56       pri         Priority of threads servicing the task queue.  Drivers  and
57                   modules should specify TASKQ_DEFAULTPRI.
58
59
60       cflags      Should pass 0 as flags.
61
62
63       func        Callback function to call.
64
65
66       arg         Argument to the callback function.
67
68
69       dflags      Possible dflags are:
70
71                   DDI_SLEEP      Allow  sleeping  (blocking)  until memory is
72                                  available.
73
74
75                   DDI_NOSLEEP    Return DDI_FAILURE immediately if memory  is
76                                  not  available.
77
78
79
80       tq          Pointer to a task queue (ddi_taskq_t *).
81
82
83       tp          Pointer to a thread structure.
84
85

DESCRIPTION

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
92           1.     You have a task that isn't time-critical, but a current code
93                  path that is.
94
95           2.     You  have  a  task  that  may  require grabbing locks that a
96                  thread already holds.
97
98           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
102           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
107           5.     A  task  queue is just a simple way to launch multiple tasks
108                  in parallel.
109
110
111       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
120
121       The ddi_taskq_create() function creates a task queue instance.
122
123
124       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
130
131       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
135
136       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
140
141       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
149
150       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
154
155       The ddi_taskq_resume() function resumes task queue execution.
156

RETURN VALUES

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
162
163       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
166
167       The ddi_taskq_suspended() function returns  B_TRUE  if  taskq  is  sus‐
168       pended. Otherwise B_FALSE is returned.
169

CONTEXT

171       All functions may be called from the user or kernel contexts.
172
173
174       Addtionally,  the  ddi_taskq_dispatch  function  may be called from the
175       interrupt context only if the DDI_NOSLEEP flag is set.
176
177
178
179SunOS 5.11                        1 Mar 2005                         taskq(9F)
Impressum