table of contents
PTHREAD_WORKQUEUE(3) | 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
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¶
Thepthread_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.
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¶
Thepthread_workqueue_init_np
() function will
fail if:
- [
ENOMEM
] - Out of memory.
pthread_workqueue_create_np
() function
will fail if:
- [
ENOMEM
] - Out of memory.
pthread_workqueue_additem_np
() function
will fail if:
The pthread_workqueue_attr_init_np
() function
will fail if:
- [
ENOMEM
] - Out of memory.
pthread_workqueue_attr_destroy_np
()
function will fail if:
- [
EINVAL
] - Invalid value for attr.
pthread_workqueue_attr_setqueuepriority_np
()
function will fail if:
- [
EINVAL
] - Invalid value for attr or for qprio.
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 byStacey Son ⟨sson@FreeBSD.org⟩ and
Apple, Inc.
December 12, 2009 | Debian |