]> git.saurik.com Git - apple/libdispatch.git/blob - man/dispatch_object.3
libdispatch-913.30.4.tar.gz
[apple/libdispatch.git] / man / dispatch_object.3
1 .\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
2 .Dd March 1, 2012
3 .Dt dispatch_object 3
4 .Os Darwin
5 .Sh NAME
6 .Nm dispatch_object
7 .Nd General manipulation of dispatch objects
8 .Sh SYNOPSIS
9 .Fd #include <dispatch/dispatch.h>
10 .Ft void
11 .Fo dispatch_retain
12 .Fa "dispatch_object_t object"
13 .Fc
14 .Ft void
15 .Fo dispatch_release
16 .Fa "dispatch_object_t object"
17 .Fc
18 .Ft void
19 .Fo dispatch_suspend
20 .Fa "dispatch_object_t object"
21 .Fc
22 .Ft void
23 .Fo dispatch_resume
24 .Fa "dispatch_object_t object"
25 .Fc
26 .Ft void
27 .Fo dispatch_activate
28 .Fa "dispatch_object_t object"
29 .Fc
30 .Ft "void *"
31 .Fo dispatch_get_context
32 .Fa "dispatch_object_t object"
33 .Fc
34 .Ft void
35 .Fo dispatch_set_context
36 .Fa "dispatch_object_t object"
37 .Fa "void *context"
38 .Fc
39 .Ft void
40 .Fo dispatch_set_finalizer_f
41 .Fa "dispatch_object_t object"
42 .Fa "dispatch_function_t finalizer"
43 .Fc
44 .Sh DESCRIPTION
45 Dispatch objects share functions for coordinating memory management, suspension,
46 cancellation and context pointers.
47 .Sh MEMORY MANAGEMENT
48 Objects returned by creation functions in the dispatch framework may be
49 uniformly retained and released with the functions
50 .Fn dispatch_retain
51 and
52 .Fn dispatch_release
53 respectively.
54 .Pp
55 The dispatch framework does not guarantee that any given client has the last or
56 only reference to a given object. Objects may be retained internally by the
57 system.
58 .Ss INTEGRATION WITH OBJECTIVE-C
59 .Bd -filled -offset indent
60 When building with an Objective-C or Objective-C++ compiler, dispatch objects
61 are declared as Objective-C types. This results in the following differences
62 compared to building as plain C/C++:
63 .Bl -dash
64 .It
65 if Objective-C Automated Reference Counting is enabled, dispatch objects are
66 memory managed by the Objective-C runtime and explicit calls to the
67 .Fn dispatch_retain
68 and
69 .Fn dispatch_release
70 functions will produce build errors.
71 .Pp
72 .Em Note :
73 when ARC is enabled, care needs to be taken with dispatch API returning an
74 interior pointer that is only valid as long as an associated object has not
75 been released. If that object is held in a variable with automatic storage, it
76 may need to be annotated with the
77 .Li objc_precise_lifetime
78 attribute, or stored in a
79 .Li __strong
80 instance variable instead, to ensure that the object is not prematurely
81 released. The functions returning interior pointers are
82 .Xr dispatch_data_create_map 3
83 and
84 .Xr dispatch_data_apply 3 .
85 .It
86 the Blocks runtime automatically retains and releases dispatch objects captured
87 by blocks upon
88 .Fn Block_copy
89 and
90 .Fn Block_release ,
91 e.g.\& as performed during asynchronous execution of a block via
92 .Xr dispatch_async 3 .
93 .Pp
94 .Em Note :
95 retain cycles may be encountered if dispatch source objects are captured by
96 their handler blocks; these cycles can be broken by declaring the captured
97 object
98 .Li __weak
99 or by calling
100 .Xr dispatch_source_cancel 3
101 to cause its handler blocks to be released explicitly.
102 .It
103 dispatch objects can be added directly to Cocoa collections, and their
104 lifetime is tracked by the Objective-C static analyzer.
105 .El
106 .Pp
107 Integration of dispatch objects with Objective-C requires targeting Mac\ OS\ X
108 10.8 or later, and is disabled when building for the legacy Objective-C runtime.
109 It can also be disabled manually by using compiler options to define the
110 .Dv OS_OBJECT_USE_OBJC
111 preprocessor macro to
112 .Li 0 .
113 .Ed
114 .Pp
115 .Em Important :
116 When building with a plain C/C++ compiler or when integration with Objective-C
117 is disabled, dispatch objects are
118 .Em not
119 automatically retained and released when captured by a block. Therefore, when a
120 dispatch object is captured by a block that will be executed asynchronously,
121 the object must be manually retained and released:
122 .Pp
123 .Bd -literal -offset indent
124 dispatch_retain(object);
125 dispatch_async(queue, ^{
126 do_something_with_object(object);
127 dispatch_release(object);
128 });
129 .Ed
130 .Sh ACTIVATION
131 Dispatch objects such as queues and sources may be created in an inactive
132 state. Objects in this state must be activated before any blocks
133 associated with them will be invoked. Calling
134 .Fn dispatch_activate
135 on an active object has no effect.
136 .Pp
137 Changing attributes such as the target queue or a source handler is no longer permitted
138 once the object has been activated (see
139 .Xr dispatch_set_target_queue 3 ,
140 .Xr dispatch_source_set_event_handler 3 ).
141 .Sh SUSPENSION
142 The invocation of blocks on dispatch queues or dispatch sources may be suspended
143 or resumed with the functions
144 .Fn dispatch_suspend
145 and
146 .Fn dispatch_resume
147 respectively. Other dispatch objects do not support suspension.
148 .Pp
149 The dispatch framework always checks the suspension status before executing a
150 block, but such changes never affect a block during execution (non-preemptive).
151 Therefore the suspension of an object is asynchronous, unless it is performed
152 from the context of the target queue for the given object.
153 The result of suspending or resuming an object that is not a dispatch queue or
154 a dispatch source is undefined.
155 .Pp
156 .Em Important :
157 suspension applies to all aspects of the dispatch object life cycle, including
158 the finalizer function and cancellation handler. Suspending an object causes it
159 to be retained and resuming an object causes it to be released. Therefore it is
160 important to balance calls to
161 .Fn dispatch_suspend
162 and
163 .Fn dispatch_resume
164 such that the dispatch object is fully resumed when the last reference is
165 released. The result of releasing all references to a dispatch object while in
166 an inactive or suspended state is undefined.
167 .Sh CONTEXT POINTERS
168 Dispatch objects support supplemental context pointers. The value of the
169 context pointer may be retrieved and updated with
170 .Fn dispatch_get_context
171 and
172 .Fn dispatch_set_context
173 respectively.
174 The
175 .Fn dispatch_set_finalizer_f
176 specifies an optional per-object finalizer function that is invoked
177 asynchronously if the context pointer is not NULL when the last
178 reference to the object is released.
179 This gives the
180 application an opportunity to free the context data associated with the object.
181 The finalizer will be run on the object's target queue.
182 .Sh SEE ALSO
183 .Xr dispatch 3 ,
184 .Xr dispatch_async 3 ,
185 .Xr dispatch_group_create 3 ,
186 .Xr dispatch_queue_create 3 ,
187 .Xr dispatch_semaphore_create 3 ,
188 .Xr dispatch_set_target_queue 3 ,
189 .Xr dispatch_source_cancel 3 ,
190 .Xr dispatch_source_create 3