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