1.\" Copyright (C) 2009-2015 sson@FreeBSD.org 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD: $ 29.Dd May 1, 2014 30.Dt PTHREAD_WORKQUEUE 3 31.Os 32.Sh NAME 33.Nm pthread_workqueue_init_np , 34.Nm pthread_workqueue_create_np , 35.Nm pthread_workqueue_additem_np 36.Nd thread workqueue operations 37.Pp 38.Nm pthread_workqueue_attr_init_np , 39.Nm pthread_workqueue_attr_destroy_np , 40.Nm pthread_workqueue_attr_getovercommit_np , 41.Nm pthread_workqueue_attr_setovercommit_np , 42.Nm pthread_workqueue_attr_getqueuepriority_np , 43.Nm pthread_workqueue_attr_setqueuepriority_np 44.Nd thread workqueue attribute operations 45.Sh LIBRARY 46.Lb libpthread 47.Sh SYNOPSIS 48.In pthread_np.h 49.Ft int 50.Fn pthread_workqueue_init_np "void" 51.Ft int 52.Fn pthread_workqueue_create_np "pthread_workqueue_t *workqp" "const pthread_workqueue_attr_t * attr" 53.Ft int 54.Fn pthread_workqueue_additem_np "pthread_workqueue_t workq" "void *( *workitem_func)(void *)" "void * workitem_arg" "pthread_workitem_handle_t * itemhandlep" "unsigned int *gencountp" 55.Ft int 56.Fn pthread_workqueue_attr_init_np "pthread_workqueue_attr_t *attr" 57.Ft int 58.Fn pthread_workqueue_attr_destroy_np "pthread_workqueue_attr_t *attr" 59.Ft int 60.Fn pthread_workqueue_attr_getovercommit_np "pthread_workqueue_attr_t *attr" "int *ocommp" 61.Ft int 62.Fn pthread_workqueue_attr_setovercommit_np "pthread_workqueue_attr_t *attr" "int ocomm" 63.Ft int 64.Fn pthread_workqueue_attr_getqueuepriority_np "pthread_workqueue_attr_t *attr" "int *qpriop" 65.Ft int 66.Fn pthread_workqueue_attr_setqueuepriority_np "pthread_workqueue_attr_t *attr" "int qprio" 67.Sh DESCRIPTION 68The 69.Fn pthread_workqueue_*_np 70functions are used to create and submit work items to a thread pool. 71The size of the thread pool is managed by the kernel based on physical 72resources and these tunable 73.Xr sysctl 3 74MIBs: 75.Bl -tag -width "Va kern.wq_reduce_pool_window_usecs" 76.It Va kern.wq_yielded_threshold 77Maximum number of threads to yield within the window. 78.It Va kern.wq_yielded_window_usecs 79Yielded thread window size given in microseconds. 80.It Va kern.wq_stalled_window_usecs 81Number of microseconds until a thread is considered stalled. 82.It Va kern.wq_reduce_pool_window_usecs 83Number of microseconds while a thread is idle until it is 84removed from the thread pool. 85.It Va kern.wq_max_timer_interval_usecs 86Number of microseconds to wait to check for stalled or idle threads. 87.It Va kern.wq_max_threads 88Maximum number of threads in the thread pool. 89.El 90.Pp 91The user may create multiple work queues of different priority and 92manually overcommit the available resources. 93.Pp 94.Fn pthread_workqueue_init_np 95allocates and initializes the thread workqueue subsystem. 96.Pp 97.Fn pthread_workqueue_create_np 98creates a new thread workqueue with the attributes given by 99.Fa attr . 100If 101.Fa attr 102is NULL then the default attributes are used. 103A workqueue handle is returned in the 104.Fa workqp 105parameter. 106.Pp 107Thread workqueue attributes are used to specify parameters to 108.Fn pthread_workqueue_create_np . 109One attribute object can be used in multiple calls to 110.Fn pthread_workqueue_create_np , 111with or without modifications between calls. 112.Pp 113.Fn pthread_workqueue_additem_np 114is used to submit work items to the thread pool specified by the 115.Fa workq 116parameter. 117The work item function and function argument are given by 118.Fa workitem_func 119and 120.Fa workitem_arg . 121The work item handle is returned in 122.Fa itemhandlep . 123.Pp 124The 125.Fn pthread_workqueue_attr_init_np 126function initializes 127.Fa attr 128with all the default thread workqueue attributes. 129.Pp 130The 131.Fn pthread_workqueue_attr_destroy_np 132function destroys 133.Fa attr . 134.Pp 135The 136.Fn pthread_workqueue_attr_set*_np 137functions set the attribute that corresponds to each function name. 138.Fn pthread_workqueue_attr_setovercommit_np 139can be used to set the overcommit flag. 140When the overcommit flag is set, more threads will be started as 141needed. 142This might overcommit the physical resources of the system. 143.Fn pthread_workqueue_attr_setqueuepriority_np 144sets the queue priority attribute of the thread work queue and must be 145set to one of these values: 146.Bl -tag -width "Va WORKQ_DEFAULT_PRIOQUEUE" 147.It Va WORKQ_HIGH_PRIOQUEUE 148Queued work items with this attribute will be given higher priority by 149the thread scheduler. 150.It Va WORKQ_DEFAULT_PRIOQUEUE 151Queued work items in the queue with this attribute are given the default 152priority. 153.It Va WORKQ_LOW_PRIOQUEUE 154Queued work items in the queue with this attribute will be given lower priority 155by the thread scheduler. 156.El 157.Pp 158The 159.Fn pthread_workqueue_attr_get*_np 160functions copy the value of the attribute that corresponds to each function name 161to the location pointed to by the second function parameter. 162.Sh RETURN VALUES 163If successful, these functions return 0. 164Otherwise, an error number is returned to indicate the error. 165.Sh ERRORS 166The 167.Fn pthread_workqueue_init_np 168function will fail with: 169.Bl -tag -width Er 170.It Bq Er ENOMEM 171Out of memory. 172.El 173.Pp 174The 175.Fn pthread_workqueue_create_np 176function will fail with: 177.Bl -tag -width Er 178.It Bq Er ENOMEM 179Out of memory. 180.El 181.Pp 182The 183.Fn pthread_workqueue_additem_np 184function will fail with: 185.Bl -tag -width Er 186.It Bq Er EINVAL 187Invalid workqueue handle. 188.It Bq Er ENOMEM 189Out of memory. 190.It Bq Er ESRCH 191Can not find workqueue. 192.El 193.Pp 194The 195.Fn pthread_workqueue_attr_init_np 196function will fail if: 197.Bl -tag -width Er 198.It Bq Er ENOMEM 199Out of memory. 200.El 201.Pp 202The 203.Fn pthread_workqueue_attr_destroy_np 204function will fail if: 205.Bl -tag -width Er 206.It Bq Er EINVAL 207Invalid value for 208.Fa attr . 209.El 210.Pp 211The 212.Fn pthread_workqueue_attr_setqueuepriority_np 213function will fail if: 214.Bl -tag -width Er 215.It Bq Er EINVAL 216Invalid value for 217.Fa attr 218or for 219.Fa qprio. 220.El 221.Pp 222The 223.Fn pthread_workqueue_attr_setovercommit_np , 224.Fn pthread_workqueue_attr_getovercommit_np 225and 226.Fn pthread_workqueue_attr_getqueuepriority_np 227functions will fail if: 228.Bl -tag -width Er 229.It Bq Er EINVAL 230Invalid value for 231.Fa attr . 232.El 233.Sh SEE ALSO 234.Xr pthread 3 , 235.Xr sysctl 3 236.Sh BUGS 237There is currently no way to remove or destroy work queues or pending 238work items other than exiting the process. 239.Sh HISTORY 240This thread workqueues code was created to support Grand Central Dispatch (GCD 241or libdispatch) and first appeared in 242.Fx 10.1 . 243.Sh AUTHORS 244.An "Stacey Son" Aq sson@FreeBSD.org . 245.\" Copyright (C) 2009-2015 sson@FreeBSD.org 246.\" All rights reserved. 247.\" 248.\" Redistribution and use in source and binary forms, with or without 249.\" modification, are permitted provided that the following conditions 250.\" are met: 251.\" 1. Redistributions of source code must retain the above copyright 252.\" notice(s), this list of conditions and the following disclaimer as 253.\" the first lines of this file unmodified other than the possible 254.\" addition of one or more copyright notices. 255.\" 2. Redistributions in binary form must reproduce the above copyright 256.\" notice(s), this list of conditions and the following disclaimer in 257.\" the documentation and/or other materials provided with the 258.\" distribution. 259.\" 260.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 261.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 262.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 263.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 264.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 265.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 266.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 267.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 268.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 269.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 270.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 271.\" 272.\" $FreeBSD: $ 273.Dd May 1, 2014 274.Dt PTHREAD_WORKQUEUE 3 275.Os 276.Sh NAME 277.Nm pthread_workqueue_init_np , 278.Nm pthread_workqueue_create_np , 279.Nm pthread_workqueue_additem_np 280.Nd thread workqueue operations 281.Pp 282.Nm pthread_workqueue_attr_init_np , 283.Nm pthread_workqueue_attr_destroy_np , 284.Nm pthread_workqueue_attr_getovercommit_np , 285.Nm pthread_workqueue_attr_setovercommit_np , 286.Nm pthread_workqueue_attr_getqueuepriority_np , 287.Nm pthread_workqueue_attr_setqueuepriority_np 288.Nd thread workqueue attribute operations 289.Sh LIBRARY 290.Lb libpthread 291.Sh SYNOPSIS 292.In pthread_np.h 293.Ft int 294.Fn pthread_workqueue_init_np "void" 295.Ft int 296.Fn pthread_workqueue_create_np "pthread_workqueue_t *workqp" "const pthread_workqueue_attr_t * attr" 297.Ft int 298.Fn pthread_workqueue_additem_np "pthread_workqueue_t workq" "void *( *workitem_func)(void *)" "void * workitem_arg" "pthread_workitem_handle_t * itemhandlep" "unsigned int *gencountp" 299.Ft int 300.Fn pthread_workqueue_attr_init_np "pthread_workqueue_attr_t *attr" 301.Ft int 302.Fn pthread_workqueue_attr_destroy_np "pthread_workqueue_attr_t *attr" 303.Ft int 304.Fn pthread_workqueue_attr_getovercommit_np "pthread_workqueue_attr_t *attr" "int *ocommp" 305.Ft int 306.Fn pthread_workqueue_attr_setovercommit_np "pthread_workqueue_attr_t *attr" "int ocomm" 307.Ft int 308.Fn pthread_workqueue_attr_getqueuepriority_np "pthread_workqueue_attr_t *attr" "int *qpriop" 309.Ft int 310.Fn pthread_workqueue_attr_setqueuepriority_np "pthread_workqueue_attr_t *attr" "int qprio" 311.Sh DESCRIPTION 312The 313.Fn pthread_workqueue_*_np 314functions are used to create and submit work items to a thread pool. 315The size of the thread pool is managed by the kernel based on physical 316resources and these tunable 317.Xr sysctl 3 318MIBs: 319.Bl -tag -width "Va kern.wq_reduce_pool_window_usecs" 320.It Va kern.wq_yielded_threshold 321Maximum number of threads to yield within the window. 322.It Va kern.wq_yielded_window_usecs 323Yielded thread window size given in microseconds. 324.It Va kern.wq_stalled_window_usecs 325Number of microseconds until a thread is considered stalled. 326.It Va kern.wq_reduce_pool_window_usecs 327Number of microseconds while a thread is idle until it is 328removed from the thread pool. 329.It Va kern.wq_max_timer_interval_usecs 330Number of microseconds to wait to check for stalled or idle threads. 331.It Va kern.wq_max_threads 332Maximum number of threads in the thread pool. 333.El 334.Pp 335The user may create multiple work queues of different priority and 336manually overcommit the available resources. 337.Pp 338.Fn pthread_workqueue_init_np 339allocates and initializes the thread workqueue subsystem. 340.Pp 341.Fn pthread_workqueue_create_np 342creates a new thread workqueue with the attributes given by 343.Fa attr . 344If 345.Fa attr 346is NULL then the default attributes are used. 347A workqueue handle is returned in the 348.Fa workqp 349parameter. 350.Pp 351Thread workqueue attributes are used to specify parameters to 352.Fn pthread_workqueue_create_np . 353One attribute object can be used in multiple calls to 354.Fn pthread_workqueue_create_np , 355with or without modifications between calls. 356.Pp 357.Fn pthread_workqueue_additem_np 358is used to submit work items to the thread pool specified by the 359.Fa workq 360parameter. 361The work item function and function argument are given by 362.Fa workitem_func 363and 364.Fa workitem_arg . 365The work item handle is returned in 366.Fa itemhandlep . 367.Pp 368The 369.Fn pthread_workqueue_attr_init_np 370function initializes 371.Fa attr 372with all the default thread workqueue attributes. 373.Pp 374The 375.Fn pthread_workqueue_attr_destroy_np 376function destroys 377.Fa attr . 378.Pp 379The 380.Fn pthread_workqueue_attr_set*_np 381functions set the attribute that corresponds to each function name. 382.Fn pthread_workqueue_attr_setovercommit_np 383can be used to set the overcommit flag. 384When the overcommit flag is set, more threads will be started as 385needed. 386This might overcommit the physical resources of the system. 387.Fn pthread_workqueue_attr_setqueuepriority_np 388sets the queue priority attribute of the thread work queue and must be 389set to one of these values: 390.Bl -tag -width "Va WORKQ_DEFAULT_PRIOQUEUE" 391.It Va WORKQ_HIGH_PRIOQUEUE 392Queued work items with this attribute will be given higher priority by 393the thread scheduler. 394.It Va WORKQ_DEFAULT_PRIOQUEUE 395Queued work items in the queue with this attribute are given the default 396priority. 397.It Va WORKQ_LOW_PRIOQUEUE 398Queued work items in the queue with this attribute will be given lower priority 399by the thread scheduler. 400.El 401.Pp 402The 403.Fn pthread_workqueue_attr_get*_np 404functions copy the value of the attribute that corresponds to each function name 405to the location pointed to by the second function parameter. 406.Sh RETURN VALUES 407If successful, these functions return 0. 408Otherwise, an error number is returned to indicate the error. 409.Sh ERRORS 410The 411.Fn pthread_workqueue_init_np 412function will fail with: 413.Bl -tag -width Er 414.It Bq Er ENOMEM 415Out of memory. 416.El 417.Pp 418The 419.Fn pthread_workqueue_create_np 420function will fail with: 421.Bl -tag -width Er 422.It Bq Er ENOMEM 423Out of memory. 424.El 425.Pp 426The 427.Fn pthread_workqueue_additem_np 428function will fail with: 429.Bl -tag -width Er 430.It Bq Er EINVAL 431Invalid workqueue handle. 432.It Bq Er ENOMEM 433Out of memory. 434.It Bq Er ESRCH 435Can not find workqueue. 436.El 437.Pp 438The 439.Fn pthread_workqueue_attr_init_np 440function will fail if: 441.Bl -tag -width Er 442.It Bq Er ENOMEM 443Out of memory. 444.El 445.Pp 446The 447.Fn pthread_workqueue_attr_destroy_np 448function will fail if: 449.Bl -tag -width Er 450.It Bq Er EINVAL 451Invalid value for 452.Fa attr . 453.El 454.Pp 455The 456.Fn pthread_workqueue_attr_setqueuepriority_np 457function will fail if: 458.Bl -tag -width Er 459.It Bq Er EINVAL 460Invalid value for 461.Fa attr 462or for 463.Fa qprio. 464.El 465.Pp 466The 467.Fn pthread_workqueue_attr_setovercommit_np , 468.Fn pthread_workqueue_attr_getovercommit_np 469and 470.Fn pthread_workqueue_attr_getqueuepriority_np 471functions will fail if: 472.Bl -tag -width Er 473.It Bq Er EINVAL 474Invalid value for 475.Fa attr . 476.El 477.Sh SEE ALSO 478.Xr pthread 3 , 479.Xr sysctl 3 480.Sh BUGS 481There is currently no way to remove or destroy work queues or pending 482work items other than exiting the process. 483.Sh HISTORY 484This thread workqueues code was created to support Grand Central Dispatch (GCD 485or libdispatch) and first appeared in 486.Fx 10.1 . 487.Sh AUTHORS 488.An "Stacey Son" Aq sson@FreeBSD.org . 489