pthread_workqueue_init_np(3) pthread_workqueue_create_np

SYNOPSIS

In pthread_workqueue.h Ft int Fn pthread_workqueue_init_np void Ft int Fn pthread_workqueue_create_np pthread_workqueue_t *workqp const pthread_workqueue_attr_t * attr Ft int Fn pthread_workqueue_additem_np pthread_workqueue_t workq void ( *workitem_func)(void *) void * workitem_arg pthread_workitem_handle_t * itemhandlep unsigned int *gencountp Ft int Fn pthread_workqueue_attr_init_np pthread_workqueue_attr_t *attr Ft int Fn pthread_workqueue_attr_destroy_np pthread_workqueue_attr_t *attr Ft int Fn pthread_workqueue_attr_getovercommit_np pthread_workqueue_attr_t *attr int *ocommp Ft int Fn pthread_workqueue_attr_setovercommit_np pthread_workqueue_attr_t *attr int ocomm Ft int Fn pthread_workqueue_attr_getqueuepriority_np pthread_workqueue_attr_t *attr int *qpriop Ft int Fn pthread_workqueue_attr_setqueuepriority_np pthread_workqueue_attr_t *attr int qprio

DESCRIPTION

The Fn 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.

Fn pthread_workqueue_init_np allocates and initializes the thread workqueue subsystem.

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

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

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

The Fn pthread_workqueue_attr_init_np function initializes Fa attr with all the default thread workqueue attributes.

The Fn pthread_workqueue_attr_destroy_np function destroys Fa attr .

The Fn pthread_workqueue_attr_set*_np functions set the attribute that corresponds to each function name. Fn 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. Fn 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 Fn 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 Fn pthread_workqueue_init_np function will fail if:

Bq Er ENOMEM
Out of memory.

The Fn pthread_workqueue_create_np function will fail if:

Bq Er ENOMEM
Out of memory.

The Fn pthread_workqueue_additem_np function will fail if:

Bq Er EINVAL
Invalid workqueue handle.
Bq Er ENOMEM
Out of memory.
Bq Er ESRCH
Can not find workqueue.

The Fn pthread_workqueue_attr_init_np function will fail if:

Bq Er ENOMEM
Out of memory.

The Fn pthread_workqueue_attr_destroy_np function will fail if:

Bq Er EINVAL
Invalid value for Fa attr .

The Fn pthread_workqueue_attr_setqueuepriority_np function will fail if:

Bq Er EINVAL
Invalid value for Fa attr or for Fa qprio.

The Fn pthread_workqueue_attr_setovercommit_np , Fn pthread_workqueue_attr_getovercommit_np and Fn pthread_workqueue_attr_getqueuepriority_np functions will fail if:

Bq Er EINVAL
Invalid value for Fa attr .

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 Fx 8.0 .

AUTHORS

An Mark Heily Aq [email protected] . Br

Based on earlier work by An Stacey Son Aq [email protected] and An Apple, Inc.