NAME

       pthread_workqueue_init_np,  pthread_workqueue_create_np,  pthread_workqueue_additem_np — thread workqueue
       operations

       pthread_workqueue_attr_init_np,                                        pthread_workqueue_attr_destroy_np,
       pthread_workqueue_attr_getovercommit_np,                         pthread_workqueue_attr_setovercommit_np,
       pthread_workqueue_attr_getqueuepriority_np, pthread_workqueue_attr_setqueuepriority_np — thread workqueue
       attribute operations

SYNOPSIS

       #include <pthread_workqueue.h>

       int
       pthread_workqueue_init_np(void);

       int
       pthread_workqueue_create_np(pthread_workqueue_t *workqp, const pthread_workqueue_attr_t * attr);

       int
       pthread_workqueue_additem_np(pthread_workqueue_t    workq,    void     (     *workitem_func)(void     *),
           void * workitem_arg, pthread_workitem_handle_t * itemhandlep, unsigned int *gencountp);

       int
       pthread_workqueue_attr_init_np(pthread_workqueue_attr_t *attr);

       int
       pthread_workqueue_attr_destroy_np(pthread_workqueue_attr_t *attr);

       int
       pthread_workqueue_attr_getovercommit_np(pthread_workqueue_attr_t *attr, int *ocommp);

       int
       pthread_workqueue_attr_setovercommit_np(pthread_workqueue_attr_t *attr, int ocomm);

       int
       pthread_workqueue_attr_getqueuepriority_np(pthread_workqueue_attr_t *attr, int *qpriop);

       int
       pthread_workqueue_attr_setqueuepriority_np(pthread_workqueue_attr_t *attr, int qprio);

DESCRIPTION

       The pthread_workqueue_*_np() functions are used to create and submit work items to a thread pool.

       The  user  may  create  multiple  work queues of different priority and manually overcommit the available
       resources.

       pthread_workqueue_init_np() allocates and initializes the thread workqueue subsystem.

       pthread_workqueue_create_np() creates a new thread workqueue with the attributes given by attr.  If  attr
       is NULL then the default attributes are used.  A workqueue handle is returned in the workqp parameter.

       Thread  workqueue  attributes  are  used  to  specify  parameters  to pthread_workqueue_create_np().  One
       attribute object can be  used  in  multiple  calls  to  pthread_workqueue_create_np(),  with  or  without
       modifications between calls.

       pthread_workqueue_additem_np()  is  used  to  submit  work  items  to  the thread pool specified by workq
       parameter.  The work item function and function argument are given  by  workitem_func  and  workitem_arg.
       The work item handle is returned in itemhandlep.

       The  pthread_workqueue_attr_init_np()  function  initializes  attr  with all the default thread workqueue
       attributes.

       The pthread_workqueue_attr_destroy_np() function destroys attr.

       The pthread_workqueue_attr_set*_np() functions set the attribute that corresponds to each function  name.
       pthread_workqueue_attr_setovercommit_np() can be used to set the overcommit flag.  If the overcommit flag
       is  set  then more threads will be started, if needed, which may overcommit the physical resources of the
       system.  pthread_workqueue_attr_setqueuepriority_np() sets the queue priority  attribute  of  the  thread
       work queue and must be set to one of the following values:

       WORKQ_HIGH_PRIOQUEUE        Work  items in the queue with this attribute will be given higher priority by
                                   the thread scheduler.

       WORKQ_DEFAULT_PRIOQUEUE     Work items in the queue with this attribute are given the default priority.

       WORKQ_LOW_PRIOQUEUE         Work items in the queue with this attribute will be given lower  priority  by
                                   the thread scheduler.

       The  pthread_workqueue_attr_get*_np()  functions copy the value of the attribute that corresponds to each
       function name to the location pointed to by the second function parameter.

RETURN VALUES

       If successful, these functions return 0.  Otherwise, an error number is returned to indicate the error.

ERRORS

       The pthread_workqueue_init_np() function will fail if:

       [ENOMEM]           Out of memory.

       The pthread_workqueue_create_np() function will fail if:

       [ENOMEM]           Out of memory.

       The pthread_workqueue_additem_np() function will fail if:

       [EINVAL]           Invalid workqueue handle.

       [ENOMEM]           Out of memory.

       [ESRCH]            Can not find workqueue.

       The pthread_workqueue_attr_init_np() function will fail if:

       [ENOMEM]           Out of memory.

       The pthread_workqueue_attr_destroy_np() function will fail if:

       [EINVAL]           Invalid value for attr.

       The pthread_workqueue_attr_setqueuepriority_np() function will fail if:

       [EINVAL]           Invalid value for attr or for qprio.

       The     pthread_workqueue_attr_setovercommit_np(),     pthread_workqueue_attr_getovercommit_np()      and
       pthread_workqueue_attr_getqueuepriority_np() functions will fail if:

       [EINVAL]           Invalid value for attr.

SEE ALSO

       pthread(3), sysctl(3)

BUGS

       There  is  no  way, currently, to remove or destory work queues and pending work items other than exiting
       the process.

       All worker threads run at the same thread priority; however, items  placed  on  high-priority  workqueues
       will be executed before those on lower-priority workqueues.

HISTORY

       This  thread workqueues code was created to support Grand Central Dispatch (GCD or libdispatch) and first
       appeared in FreeBSD 8.0.

AUTHORS

       Mark Heily <mark@heily.com>.

       Based on earlier work by
       Stacey Son <sson@FreeBSD.org> and
       Apple, Inc.

Debian                                          December 12, 2009                           PTHREAD_WORKQUEUE(3)