1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
.\" Copyright (C) 2010 mark@heily.com
.\" Copyright (C) 2009 sson@FreeBSD.org
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD: $
.Dd December 12, 2009
.Dt PTHREAD_WORKQUEUE 3
.Os
.Sh NAME
.Nm pthread_workqueue_init_np ,
.Nm pthread_workqueue_create_np ,
.Nm pthread_workqueue_additem_np
.Nd thread workqueue operations
.Pp
.Nm pthread_workqueue_attr_init_np ,
.Nm pthread_workqueue_attr_destroy_np ,
.Nm pthread_workqueue_attr_getovercommit_np ,
.Nm pthread_workqueue_attr_setovercommit_np ,
.Nm pthread_workqueue_attr_getqueuepriority_np ,
.Nm pthread_workqueue_attr_setqueuepriority_np
.Nd thread workqueue attribute operations
.Sh 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"
.Sh DESCRIPTION
The
.Fn pthread_workqueue_*_np
functions are used to create and submit work items to a thread pool.
.Pp
The user may create multiple work queues of different priority and
manually overcommit the available resources.
.Pp
.Fn pthread_workqueue_init_np
allocates and initializes the thread workqueue subsystem.
.Pp
.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.
.Pp
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.
.Pp
.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 .
.Pp
The
.Fn pthread_workqueue_attr_init_np
function initializes
.Fa attr
with all the default thread workqueue attributes.
.Pp
The
.Fn pthread_workqueue_attr_destroy_np
function destroys
.Fa attr .
.Pp
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:
.Bl -tag -width "Va WORKQ_DEFAULT_PRIOQUEUE"
.It Va WORKQ_HIGH_PRIOQUEUE
Work items in the queue with this attribute will be given higher priority by
the thread scheduler.
.It Va WORKQ_DEFAULT_PRIOQUEUE
Work items in the queue with this attribute are given the default
priority.
.It Va WORKQ_LOW_PRIOQUEUE
Work items in the queue with this attribute will be given lower priority
by the thread scheduler.
.El
.Pp
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.
.Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
.Sh ERRORS
The
.Fn pthread_workqueue_init_np
function will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Out of memory.
.El
.Pp
The
.Fn pthread_workqueue_create_np
function will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Out of memory.
.El
.Pp
The
.Fn pthread_workqueue_additem_np
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid workqueue handle.
.It Bq Er ENOMEM
Out of memory.
.It Bq Er ESRCH
Can not find workqueue.
.El
.Pp
The
.Fn pthread_workqueue_attr_init_np
function will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Out of memory.
.El
.Pp
The
.Fn pthread_workqueue_attr_destroy_np
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
The
.Fn pthread_workqueue_attr_setqueuepriority_np
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr
or for
.Fa qprio.
.El
.Pp
The
.Fn pthread_workqueue_attr_setovercommit_np ,
.Fn pthread_workqueue_attr_getovercommit_np
and
.Fn pthread_workqueue_attr_getqueuepriority_np
functions will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Sh SEE ALSO
.Xr pthread 3 ,
.Xr sysctl 3
.Sh BUGS
There is no way, currently, to remove or destory work queues and pending
work items other than exiting the process.
.Pp
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.
.Sh HISTORY
This thread workqueues code was created to support Grand Central Dispatch (GCD
or libdispatch) and first appeared in
.Fx 8.0 .
.Sh AUTHORS
.An "Mark Heily" Aq mark@heily.com .
.Br
.Pp
Based on earlier work by
.An "Stacey Son" Aq sson@FreeBSD.org
and
.An Apple, Inc.
|