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