Kernel Functions for Drivers taskq(9F)
NAME
taskq, dditaskqcreate, dditaskqdestroy,
dditaskqdispatch, dditaskqwait, dditaskqsuspend,
taskqsuspended, dditaskqresume - Kernel task queue opera-
tions
SYNOPSIS
#include
dditaskqt *dditaskqcreate(devinfot *dip, const char *name,
int nthreads, prit pri, uintt cflags);
void dditaskqdestroy(dditaskqt *tq);
int dditaskqdispatch(dditaskqt *tq, void (* func)(void *),
void *arg, uintt dflags);
void dditaskqwait(dditaskqt *tq);
void dditaskqsuspend(dditaskqt *tq);
booleant dditaskqsuspended(dditaskqt *tq);
void dditaskqresume(dditaskqt *tq);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
dip Pointer to the device's devinfo structure. May
be NUL for kernel modules that do
not have an associated devinfo structure.
name Descriptive string. Only alphanumeric characters
can be used in name and spaces are
not allowed. The name should be unique.
nthreads Number of threads servicing the task queue. Note
that the request ordering is guaranteed (tasks
are processed in the order scheduled) if the
taskq is created with a single servicing thread.
SunOS 5.11 Last change: 1 Mar 2005 1
Kernel Functions for Drivers taskq(9F)
pri Priority of threads servicing the task queue.
Drivers and modules should specify
TASKQDEFAULTPRI.
cflags Should pass 0 as flags.
func Callback function to call.
arg Argument to the callback function.
dflags Possible dflags are:
DISLEP Allow sleeping (blocking) until
memory is available.
DINOSLEP Return DIFAILURE immediately if
memory is not available.
tq Pointer to a task queue (dditaskqt *).
tp Pointer to a thread structure.
DESCRIPTION
A kernel task queue is a mechanism for general-purpose asyn-
chronous 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:
1. You have a task that isn't time-critical, but a
current code path that is.
2. You have a task that may require grabbing locks
that a thread already holds.
3. You have a task that needs to block (for example,
to wait for memory), but a have a thread that can-
not block in its current context.
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.
SunOS 5.11 Last change: 1 Mar 2005 2
Kernel Functions for Drivers taskq(9F)
5. A task queue is just a simple way to launch multi-
ple tasks in parallel.
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 taskq
created with a single servicing thread guarantees that all
the tasks are serviced in the order in which they are
scheduled.
The dditaskqcreate() function creates a task queue
instance.
The dditaskqdispatch() function places taskq on the list
for later execution. The dflag argument specifies whether it
is allowed sleep waiting for memory. DISLEP dispatches
can sleep and are guaranteed to succeed. DINOSLEP
dispatches are guaranteed not to sleep but may fail (return
DIFAILURE) if resources are not available.
The dditaskqdestroy() function waits for any scheduled
tasks to complete, then destroys the taskq. The caller
should guarantee that no new tasks are scheduled for the
closing taskq.
The dditaskqwait() function waits for all previously
scheduled tasks to complete. Note that this function does
not stop any new task dispatches.
The dditaskqsuspend() function suspends all task execution
until dditaskqresume() is called. Although
dditaskqsuspend() attempts to suspend pending tasks, there
are no guarantees that they will be suspended. The only
guarantee is that all tasks dispatched after
dditaskqsuspend() will not be executed. Because it will
trigger a deadlock, the dditaskqsuspend() function should
never be called by a task executing on a taskq.
The dditaskqsuspended() function returns BTRUE if taskq
is suspended, and BFALSE otherwise. It is intended to
ASERT that the task queue is suspended.
SunOS 5.11 Last change: 1 Mar 2005 3
Kernel Functions for Drivers taskq(9F)
The dditaskqresume() function resumes task queue execu-
tion.
RETURN VALUES
The dditaskqcreate() function creates an opaque handle
that is used for all other taskq operations. It returns a
taskq pointer on success and NUL on failure.
The dditaskqdispatch() function returns DIFAILURE if it
can't dispatch a task and returns DISUCES if dispatch
succeeded.
The dditaskqsuspended() function returns BTRUE if taskq
is suspended. Otherwise BFALSE is returned.
CONTEXT
All functions may be called from the user or kernel con-
texts.
Addtionally, the dditaskqdispatch function may be called
from the interrupt context only if the DINOSLEP flag is
set.
SunOS 5.11 Last change: 1 Mar 2005 4
|
