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.