1dispatch_queue_create(3) BSD Library Functions Manual dispatch_queue_create(3)
2
4 dispatch_queue_create, dispatch_queue_get_label,
5 dispatch_get_current_queue, dispatch_get_global_queue,
6 dispatch_get_main_queue, dispatch_main, dispatch_set_target_queue — where
7 blocks are scheduled for execution
8
10 #include <dispatch/dispatch.h>
11 dispatch_queue_t
13 dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);
14 const char *
16 dispatch_queue_get_label(dispatch_queue_t queue);
17 dispatch_queue_t
19 dispatch_get_global_queue(long priority, unsigned long flags);
20 dispatch_queue_t
22 dispatch_get_main_queue(void);
23 void
25 dispatch_main(void);
26 void
28 dispatch_set_target_queue(dispatch_object_t object,
29 dispatch_queue_t target);
30
32 Queues are the fundamental mechanism for scheduling blocks for execution
33 within the dispatch(3) framework.
34 All blocks submitted to dispatch queues are dequeued in FIFO order.
36 Queues created with the DISPATCH_QUEUE_SERIAL attribute wait for the pre‐
37 viously dequeued block to complete before dequeuing the next block. A
38 queue with this FIFO completion behavior is usually simply described as a
39 "serial queue." All memory writes performed by a block dispatched to a
40 serial queue are guaranteed to be visible to subsequent blocks dispatched
41 to the same queue. Queues are not bound to any specific thread of execu‐
42 tion and blocks submitted to independent queues may execute concurrently.
43 Queues created with the DISPATCH_QUEUE_CONCURRENT attribute may execute
45 dequeued blocks concurrently and support barrier blocks submitted with
46 the dispatch barrier API.
47
49 Queues are created with the dispatch_queue_create() function. Queues,
50 like all dispatch objects, are reference counted and newly created queues
51 have a reference count of one.
52 The optional label argument is used to describe the purpose of the queue
54 and is useful during debugging and performance analysis. If a label is
55 provided, it is copied. By convention, clients should pass a reverse DNS
56 style label. For example:
57 my_queue = dispatch_queue_create("com.example.subsystem.taskXYZ",
59 DISPATCH_QUEUE_SERIAL);
60 The attr argument specifies the type of queue to create and must be
62 either DISPATCH_QUEUE_SERIAL or DISPATCH_QUEUE_CONCURRENT.
63 The dispatch_queue_get_label() function returns the label provided when
65 the given queue was created (or an empty C string if no label was pro‐
66 vided at creation). Passing the constant DISPATCH_CURRENT_QUEUE_LABEL to
67 dispatch_queue_get_label() returns the label of the current queue.
68
70 Queues may be temporarily suspended and resumed with the functions
71 dispatch_suspend() and dispatch_resume() respectively. Suspension is
72 checked prior to block execution and is not preemptive.
73
75 The dispatch framework provides a default serial queue for the applica‐
76 tion to use. This queue is accessed via the dispatch_get_main_queue()
77 function.
78 Programs must call dispatch_main() at the end of main() in order to
80 process blocks submitted to the main queue. (See the COMPATIBILITY sec‐
81 tion for exceptions.) The dispatch_main() function never returns.
82
84 Unlike the main queue or queues allocated with dispatch_queue_create(),
85 the global concurrent queues schedule blocks as soon as threads become
86 available (non-FIFO completion order). Four global concurrent queues are
87 provided, representing the following priority bands:
88 · DISPATCH_QUEUE_PRIORITY_HIGH
89 · DISPATCH_QUEUE_PRIORITY_DEFAULT
90 · DISPATCH_QUEUE_PRIORITY_LOW
91 · DISPATCH_QUEUE_PRIORITY_BACKGROUND
92 The priority of a global concurrent queue controls the scheduling prior‐
94 ity of the threads created by the system to invoke the blocks submitted
95 to that queue. Global queues with lower priority will be scheduled for
96 execution after all global queues with higher priority have been sched‐
97 uled. Additionally, items on the background priority global queue will
98 execute on threads with background state as described in setpriority(2)
99 (i.e. disk I/O is throttled and the thread's scheduling priority is set
100 to lowest value).
101 Use the dispatch_get_global_queue() function to obtain the global queue
103 of given priority. The flags argument is reserved for future use and must
104 be zero. Passing any value other than zero may result in a NULL return
105 value.
106
108 The dispatch_set_target_queue() function updates the target queue of the
109 given dispatch object. The target queue of an object is responsible for
110 processing the object.
111 The new target queue is retained by the given object before the previous
113 target queue is released. The new target queue setting will take effect
114 between block executions on the object, but not in the middle of any
115 existing block executions (non-preemptive).
116 The default target queue of all dispatch objects created by the applica‐
118 tion is the default priority global concurrent queue. To reset an
119 object's target queue to the default, pass the
120 DISPATCH_TARGET_QUEUE_DEFAULT constant to dispatch_set_target_queue().
121 The priority of a dispatch queue is inherited from its target queue. In
123 order to change the priority of a queue created with
124 dispatch_queue_create(), use the dispatch_get_global_queue() function to
125 obtain a target queue of the desired priority.
126 Blocks submitted to a serial queue whose target queue is another serial
128 queue will not be invoked concurrently with blocks submitted to the tar‐
129 get queue or to any other queue with that same target queue.
130 The target queue of a dispatch source specifies where its event handler
132 and cancellation handler blocks will be submitted. See
133 dispatch_source_create(3) for more information about dispatch sources.
134 The target queue of a dispatch I/O channel specifies the priority of the
136 global queue where its I/O operations are executed. See
137 dispatch_io_create(3) for more information about dispatch I/O channels.
138 For all other dispatch object types, the only function of the target
140 queue is to determine where an object's finalizer function is invoked.
141 The result of passing the main queue or a global concurrent queue as the
143 first argument of dispatch_set_target_queue() is undefined.
144 Directly or indirectly setting the target queue of a dispatch queue to
146 itself is undefined.
147
149 The following functions are deprecated and will be removed in a future
150 release:
151 dispatch_queue_t dispatch_get_current_queue(void);
153 dispatch_get_current_queue() always returns a valid queue. When called
155 from within a block submitted to a dispatch queue, that queue will be
156 returned. If this function is called from the main thread before
157 dispatch_main() is called, then the result of dispatch_get_main_queue()
158 is returned. In all other cases, the default target queue will be
159 returned.
160 The use of dispatch_get_current_queue() is strongly discouraged except
162 for debugging and logging purposes. Code must not make any assumptions
163 about the queue returned, unless it is one of the global queues or a
164 queue the code has itself created. The returned queue may have arbitrary
165 policies that may surprise code that tries to schedule work with the
166 queue. The list of policies includes, but is not limited to, queue width
167 (i.e. serial vs. concurrent), scheduling priority, security credential
168 or filesystem configuration. This function is deprecated and will be
169 removed in a future release.
170 It is equally unsafe for code to assume that synchronous execution onto a
172 queue is safe from deadlock if that queue is not the one returned by
173 dispatch_get_current_queue().
174 The result of dispatch_get_main_queue() may or may not equal the result
176 of dispatch_get_current_queue() when called on the main thread. Comparing
177 the two is not a valid way to test whether code is executing on the main
178 thread. Foundation/AppKit programs should use [NSThread isMainThread].
179 POSIX programs may use pthread_main_np(3).
180 dispatch_get_current_queue() may return a queue owned by a different sub‐
182 system which has already had all external references to it released.
183 While such a queue will continue to exist until all blocks submitted to
184 it have completed, attempting to retain it is forbidden and will trigger
185 an assertion. If Objective-C Automatic Reference Counting is enabled, any
186 use of the object returned by dispatch_get_current_queue() will cause
187 retain calls to be automatically generated, so the use of
188 dispatch_get_current_queue() for any reason in code built with ARC is
189 particularly strongly discouraged.
190
192 Cocoa applications need not call dispatch_main(). Blocks submitted to
193 the main queue will be executed as part of the "common modes" of the
194 application's main NSRunLoop or CFRunLoop. However, blocks submitted to
195 the main queue in applications using dispatch_main() are not guaranteed
196 to execute on the main thread.
197 The dispatch framework is a pure C level API. As a result, it does not
199 catch exceptions generated by higher level languages such as Objective-C
200 or C++. Applications MUST catch all exceptions before returning from a
201 block submitted to a dispatch queue; otherwise the process will be termi‐
202 nated with an uncaught exception.
203 The dispatch framework manages the relationship between dispatch queues
205 and threads of execution. As a result, applications MUST NOT delete or
206 mutate objects that they did not create. The following interfaces MUST
207 NOT be called by blocks submitted to a dispatch queue:
208 · pthread_cancel()
210 · pthread_detach()
212 · pthread_join()
214 · pthread_kill()
216 · pthread_exit()
218 Applications MAY call the following interfaces from a block submitted to
220 a dispatch queue if and only if they restore the thread to its original
221 state before returning:
222 · pthread_setcancelstate()
224 · pthread_setcanceltype()
226 · pthread_setschedparam()
228 · pthread_sigmask()
230 · pthread_setugid_np()
232 Applications MUST NOT rely on the following interfaces returning pre‐
234 dictable results between invocations of blocks submitted to a dispatch
235 queue:
236 · pthread_self()
238 · pthread_getschedparam()
240 · pthread_get_stacksize_np()
242 · pthread_get_stackaddr_np()
244 · pthread_mach_thread_np()
246 · pthread_from_mach_thread_np()
248 While the result of pthread_self() may change between invocations of
250 blocks, the value will not change during the execution of any single
251 block. Because the underlying thread may change beteween block invoca‐
252 tions on a single queue, using per-thread data as an out-of-band return
253 value is error prone. In other words, the result of calling
254 pthread_setspecific() and pthread_getspecific() is well defined within a
255 signle block, but not across multiple blocks. Also, one cannot make any
256 assumptions about when the destructor passed to pthread_key_create() is
257 called. The destructor may be called between the invocation of blocks on
258 the same queue, or during the idle state of a process.
259 The following example code correctly handles per-thread return values:
261 __block int r;
263 __block int e;
264 dispatch_sync(queue, ^{
265 r = kill(1, 0);
266 // Copy the per-thread return value to the callee thread
267 e = errno;
268 });
269 printf("kill(1,0) returned %d and errno %d0, r, e);
270 Note that in the above example errno is a per-thread variable and must be
272 copied out explicitly as the block may be invoked on different thread of
273 execution than the caller. Another example of per-thread data that would
274 need to be copied is the use of getpwnam() instead of getpwnam_r().
275 As an optimization, dispatch_sync() invokes the block on the current
277 thread when possible. In this case, the thread specific data such as
278 errno may persist from the block until back to the caller. Great care
279 should be taken not to accidentally rely on this side-effect.
280
282 dispatch(3), dispatch_async(3), dispatch_object(3),
283 dispatch_source_create(3)
284Darwin May 1, 2008 Darwin