~ubuntu-branches/ubuntu/saucy/libpthread-workqueue/saucy

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

.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

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.

Older »