PTHREAD_WORKQUEUE(3) FreeBSD Library Functions Manual PTHREAD_WORKQUEUE(3) 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 LIBRARY POSIX Threads Library (libpthread, -lpthread) SYNOPSIS #include 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 size of the thread pool is managed by the kernel based on physical resources and the following tunable sysctl(3) MIBs: kern.wq_yielded_threshold Maxinum number of threads to yield within the yielded window. kern.wq_yielded_window_usecs The yielded thread window size given in microseconds. kern.wq_stalled_window_usecs The number of microseconds until a thread is considered stalled. kern.wq_reduce_pool_window_usecs The number of microseconds while a thread is idle until it is removed from the thread pool. kern.wq_max_timer_interval_usecs The number of microseconds to wait to check for stalled or idle threads. kern.wq_max_threads The maximum number of threads in the thread pool. The user may create multiple work queues of different priority and manu- ally 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 mul- tiple calls to pthread_workqueue_create_np(), with or without modifica- tions 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 han- dle 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 overcom- mit 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 pri- ority 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. HISTORY This thread workqueues code was created to support Grand Central Dispatch (GCD or libdispatch) and first appeared in FreeBSD 9.0. AUTHORS Stacey Son . FreeBSD 9.0 December 12, 2009 FreeBSD 9.0