pthread_workqueue-0.8.2/pthread_workqueue.3

   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
  67 The
  68 .Fn pthread_workqueue_*_np
  69 functions are used to create and submit work items to a thread pool.
  70 .Pp
  71 The user may create multiple work queues of different priority and
  72 manually overcommit the available resources.
  73 .Pp
  74 .Fn pthread_workqueue_init_np
  75 allocates and initializes the thread workqueue subsystem.
  76 .Pp
  77 .Fn pthread_workqueue_create_np
  78 creates a new thread workqueue with the attributes given by
  79 .Fa attr .
  80 If
  81 .Fa attr
  82 is NULL then the default attributes are used.
  83 A workqueue handle is returned in the
  84 .Fa workqp
  85 parameter.
  86 .Pp
  87 Thread workqueue attributes are used to specify parameters to
  88 .Fn pthread_workqueue_create_np .
  89 One attribute object can be used in multiple calls to
  90 .Fn pthread_workqueue_create_np ,
  91 with or without modifications between calls.
  92 .Pp
  93 .Fn pthread_workqueue_additem_np
  94 is used to submit work items to the thread pool specified by
  95 .Fa workq
  96 parameter.
  97 The work item function and function argument are given by
  98 .Fa workitem_func
  99 and
 100 .Fa workitem_arg .
 101 The work item handle is returned in
 102 .Fa itemhandlep .
 103 .Pp
 104 The
 105 .Fn pthread_workqueue_attr_init_np
 106 function initializes
 107 .Fa attr
 108 with all the default thread workqueue attributes.
 109 .Pp
 110 The
 111 .Fn pthread_workqueue_attr_destroy_np
 112 function destroys
 113 .Fa attr .
 114 .Pp
 115 The
 116 .Fn pthread_workqueue_attr_set*_np
 117 functions set the attribute that corresponds to each function name.
 118 .Fn pthread_workqueue_attr_setovercommit_np
 119 can be used to set the overcommit flag.
 120 If the overcommit flag is set then more threads will be started, if
 121 needed, which may overcommit the physical resources of the system.
 122 .Fn pthread_workqueue_attr_setqueuepriority_np
 123 sets the queue priority attribute of the thread work queue and must be
 124 set to one of the following values:
 125 .Bl -tag -width "Va WORKQ_DEFAULT_PRIOQUEUE"
 126 .It Va WORKQ_HIGH_PRIOQUEUE
 127 Work items in the queue with this attribute will be given higher priority by
 128 the thread scheduler.
 129 .It Va WORKQ_DEFAULT_PRIOQUEUE
 130 Work items in the queue with this attribute are given the default
 131 priority.
 132 .It Va WORKQ_LOW_PRIOQUEUE
 133 Work items in the queue with this attribute will be given lower priority
 134 by the thread scheduler.
 135 .El
 136 .Pp
 137 The
 138 .Fn pthread_workqueue_attr_get*_np
 139 functions copy the value of the attribute that corresponds to each function name
 140 to the location pointed to by the second function parameter.
 141 .Sh RETURN VALUES
 142 If successful, these functions return 0.
 143 Otherwise, an error number is returned to indicate the error.
 144 .Sh ERRORS
 145 The
 146 .Fn pthread_workqueue_init_np
 147 function will fail if:
 148 .Bl -tag -width Er
 149 .It Bq Er ENOMEM
 150 Out of memory.
 151 .El
 152 .Pp
 153 The
 154 .Fn pthread_workqueue_create_np
 155 function will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er ENOMEM
 158 Out of memory.
 159 .El
 160 .Pp
 161 The
 162 .Fn pthread_workqueue_additem_np
 163 function will fail if:
 164 .Bl -tag -width Er
 165 .It Bq Er EINVAL
 166 Invalid workqueue handle.
 167 .It Bq Er ENOMEM
 168 Out of memory.
 169 .It Bq Er ESRCH
 170 Can not find workqueue.
 171 .El
 172 .Pp
 173 The
 174 .Fn pthread_workqueue_attr_init_np
 175 function will fail if:
 176 .Bl -tag -width Er
 177 .It Bq Er ENOMEM
 178 Out of memory.
 179 .El
 180 .Pp
 181 The
 182 .Fn pthread_workqueue_attr_destroy_np
 183 function will fail if:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 Invalid value for
 187 .Fa attr .
 188 .El
 189 .Pp
 190 The
 191 .Fn pthread_workqueue_attr_setqueuepriority_np
 192 function will fail if:
 193 .Bl -tag -width Er
 194 .It Bq Er EINVAL
 195 Invalid value for
 196 .Fa attr
 197 or for
 198 .Fa qprio.
 199 .El
 200 .Pp
 201 The
 202 .Fn pthread_workqueue_attr_setovercommit_np ,
 203 .Fn pthread_workqueue_attr_getovercommit_np
 204 and
 205 .Fn pthread_workqueue_attr_getqueuepriority_np
 206 functions will fail if:
 207 .Bl -tag -width Er
 208 .It Bq Er EINVAL
 209 Invalid value for
 210 .Fa attr .
 211 .El
 212 .Sh SEE ALSO
 213 .Xr pthread 3 ,
 214 .Xr sysctl 3
 215 .Sh BUGS
 216 There is no way, currently, to remove or destory work queues and pending
 217 work items other than exiting the process.
 218 .Pp
 219 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.
 220 .Sh HISTORY
 221 This thread workqueues code was created to support Grand Central Dispatch (GCD
 222 or libdispatch) and first appeared in
 223 .Fx 8.0 .
 224 .Sh AUTHORS
 225 .An "Mark Heily" Aq mark@heily.com .
 226 .Br
 227 .Pp
 228 Based on earlier work by
 229 .An "Stacey Son" Aq sson@FreeBSD.org
 230 and
 231 .An Apple, Inc.