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