1dispatch_object(3) BSD Library Functions Manual dispatch_object(3)
2
4 dispatch_object — General manipulation of dispatch objects
5
7 #include <dispatch/dispatch.h>
8 void
10 dispatch_retain(dispatch_object_t object);
11 void
13 dispatch_release(dispatch_object_t object);
14 void
16 dispatch_suspend(dispatch_object_t object);
17 void
19 dispatch_resume(dispatch_object_t object);
20 void
22 dispatch_activate(dispatch_object_t object);
23 void *
25 dispatch_get_context(dispatch_object_t object);
26 void
28 dispatch_set_context(dispatch_object_t object, void *context);
29 void
31 dispatch_set_finalizer_f(dispatch_object_t object,
32 dispatch_function_t finalizer);
33
35 Dispatch objects share functions for coordinating memory management, sus‐
36 pension, cancellation and context pointers.
37
39 Objects returned by creation functions in the dispatch framework may be
40 uniformly retained and released with the functions dispatch_retain() and
41 dispatch_release() respectively.
42 The dispatch framework does not guarantee that any given client has the
44 last or only reference to a given object. Objects may be retained inter‐
45 nally by the system.
46 INTEGRATION WITH OBJECTIVE-C
48 When building with an Objective-C or Objective-C++ compiler, dis‐
49 patch objects are declared as Objective-C types. This results in
50 the following differences compared to building as plain C/C++:
51 - if Objective-C Automated Reference Counting is enabled, dis‐
53 patch objects are memory managed by the Objective-C runtime and
54 explicit calls to the dispatch_retain() and dispatch_release()
55 functions will produce build errors.
56 Note: when ARC is enabled, care needs to be taken with dispatch
58 API returning an interior pointer that is only valid as long as
59 an associated object has not been released. If that object is
60 held in a variable with automatic storage, it may need to be
61 annotated with the objc_precise_lifetime attribute, or stored
62 in a __strong instance variable instead, to ensure that the
63 object is not prematurely released. The functions returning
64 interior pointers are dispatch_data_create_map(3) and
65 dispatch_data_apply(3).
66 - the Blocks runtime automatically retains and releases dispatch
68 objects captured by blocks upon Block_copy() and
69 Block_release(), e.g. as performed during asynchronous execu‐
70 tion of a block via dispatch_async(3).
71 Note: retain cycles may be encountered if dispatch source
73 objects are captured by their handler blocks; these cycles can
74 be broken by declaring the captured object __weak or by calling
75 dispatch_source_cancel(3) to cause its handler blocks to be
76 released explicitly.
77 - dispatch objects can be added directly to Cocoa collections,
79 and their lifetime is tracked by the Objective-C static ana‐
80 lyzer.
81 Integration of dispatch objects with Objective-C requires targeting
83 Mac OS X 10.8 or later, and is disabled when building for the
84 legacy Objective-C runtime. It can also be disabled manually by
85 using compiler options to define the OS_OBJECT_USE_OBJC preproces‐
86 sor macro to 0.
87 Important: When building with a plain C/C++ compiler or when integration
89 with Objective-C is disabled, dispatch objects are not automatically
90 retained and released when captured by a block. Therefore, when a dis‐
91 patch object is captured by a block that will be executed asynchronously,
92 the object must be manually retained and released:
93 dispatch_retain(object);
95 dispatch_async(queue, ^{
96 do_something_with_object(object);
97 dispatch_release(object);
98 });
99
101 Dispatch objects such as queues and sources may be created in an inactive
102 state. Objects in this state must be activated before any blocks associ‐
103 ated with them will be invoked. Calling dispatch_activate() on an active
104 object has no effect.
105 Changing attributes such as the target queue or a source handler is no
107 longer permitted once the object has been activated (see
108 dispatch_set_target_queue(3), dispatch_source_set_event_handler(3) ).
109
111 The invocation of blocks on dispatch queues or dispatch sources may be
112 suspended or resumed with the functions dispatch_suspend() and
113 dispatch_resume() respectively. Other dispatch objects do not support
114 suspension.
115 The dispatch framework always checks the suspension status before execut‐
117 ing a block, but such changes never affect a block during execution (non-
118 preemptive). Therefore the suspension of an object is asynchronous,
119 unless it is performed from the context of the target queue for the given
120 object. The result of suspending or resuming an object that is not a
121 dispatch queue or a dispatch source is undefined.
122 Important: suspension applies to all aspects of the dispatch object life
124 cycle, including the finalizer function and cancellation handler. Sus‐
125 pending an object causes it to be retained and resuming an object causes
126 it to be released. Therefore it is important to balance calls to
127 dispatch_suspend() and dispatch_resume() such that the dispatch object is
128 fully resumed when the last reference is released. The result of releas‐
129 ing all references to a dispatch object while in an inactive or suspended
130 state is undefined.
131
133 Dispatch objects support supplemental context pointers. The value of the
134 context pointer may be retrieved and updated with dispatch_get_context()
135 and dispatch_set_context() respectively. The dispatch_set_finalizer_f()
136 specifies an optional per-object finalizer function that is invoked asyn‐
137 chronously if the context pointer is not NULL when the last reference to
138 the object is released. This gives the application an opportunity to
139 free the context data associated with the object. The finalizer will be
140 run on the object's target queue.
141
143 dispatch(3), dispatch_async(3), dispatch_group_create(3),
144 dispatch_queue_create(3), dispatch_semaphore_create(3),
145 dispatch_set_target_queue(3), dispatch_source_cancel(3),
146 dispatch_source_create(3)
147Darwin March 1, 2012 Darwin