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