Manual Pages for UNIX Operating System command usage for man taskq

Kernel Functions for Drivers                            taskq(9F)



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 opera-
     tions

SYNOPSIS
     #include 

     ddi_taskq_t *ddi_taskq_create(dev_info_t *dip, const char *name,
          int nthreads, pri_t  pri, uint_t  cflags);


     void ddi_taskq_destroy(ddi_taskq_t *tq);


     int ddi_taskq_dispatch(ddi_taskq_t *tq, void (* func)(void *),
          void *arg, uint_t dflags);


     void ddi_taskq_wait(ddi_taskq_t *tq);


     void ddi_taskq_suspend(ddi_taskq_t *tq);


     boolean_t ddi_taskq_suspended(ddi_taskq_t *tq);


     void ddi_taskq_resume(ddi_taskq_t *tq);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     dip         Pointer to the device's dev_info structure.  May
                 be  NULL  for  kernel            modules that do
                 not have an associated dev_info 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
                 TASKQ_DEFAULTPRI.


     cflags      Should pass 0 as flags.


     func        Callback function to call.


     arg         Argument to the callback function.


     dflags      Possible dflags are:

                 DDI_SLEEP      Allow sleeping  (blocking)  until
                                memory is available.


                 DDI_NOSLEEP    Return DDI_FAILURE immediately if
                                memory is not  available.



     tq          Pointer to a task queue (ddi_taskq_t *).


     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  ddi_taskq_create()  function  creates  a   task   queue
     instance.


     The ddi_taskq_dispatch() function places taskq on  the  list
     for later execution. The dflag 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
     DDI_FAILURE) if resources are not available.


     The ddi_taskq_destroy() 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  ddi_taskq_wait()  function  waits  for  all  previously
     scheduled  tasks  to  complete. Note that this function does
     not stop any new task dispatches.


     The ddi_taskq_suspend() function suspends all task execution
     until     ddi_taskq_resume()     is     called.     Although
     ddi_taskq_suspend() attempts to suspend pending tasks, there
     are  no  guarantees  that  they  will be suspended. The only
     guarantee   is   that    all    tasks    dispatched    after
     ddi_taskq_suspend()  will  not  be executed. Because it will
     trigger a deadlock, the ddi_taskq_suspend() function  should
     never be called by a task executing on a taskq.


     The ddi_taskq_suspended() function returns B_TRUE  if  taskq
     is  suspended,  and  B_FALSE  otherwise.  It  is intended to
     ASSERT that the task queue is suspended.



SunOS 5.11           Last change: 1 Mar 2005                    3






Kernel Functions for Drivers                            taskq(9F)



     The ddi_taskq_resume() function resumes  task  queue  execu-
     tion.

RETURN VALUES
     The ddi_taskq_create() function  creates  an  opaque  handle
     that  is  used  for all other taskq operations. It returns a
     taskq pointer on success and NULL on failure.


     The ddi_taskq_dispatch() function returns DDI_FAILURE if  it
     can't  dispatch  a  task and returns DDI_SUCCESS if dispatch
     succeeded.


     The ddi_taskq_suspended() function returns B_TRUE  if  taskq
     is suspended. Otherwise B_FALSE is returned.

CONTEXT
     All functions may be called from the  user  or  kernel  con-
     texts.


     Addtionally, the ddi_taskq_dispatch function may  be  called
     from  the  interrupt context only if the DDI_NOSLEEP flag is
     set.






























SunOS 5.11           Last change: 1 Mar 2005                    4