---
name: "pthread_workqueue"
section: "3"
platform: "linux"
package: "libpthread-workqueue-dev"
version: "0.9.1-1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/pthread_workqueue"
---

# pthread\_workqueue(3)

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

## 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)](/pthread/3.md), [sysctl(3)](/sysctl/3.md)

## 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.