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 for the legacy Objective-C runtime.
 105 It can also be disabled manually by using compiler options to define the
 106 .Dv OS_OBJECT_USE_OBJC
 107 preprocessor macro to
 108 .Li 0 .
 109 .Ed
 110 .Pp
 111 .Em Important :
 112 When building with a plain C/C++ compiler or when integration with Objective-C
 113 is disabled, dispatch objects are
 114 .Em not
 115 automatically retained and released when captured by a block. Therefore, when a
 116 dispatch object is captured by a block that will be executed asynchronously,
 117 the object must be manually retained and released:
 118 .Pp
 119 .Bd -literal -offset indent
 120 dispatch_retain(object);
 121 dispatch_async(queue, ^{
 122         do_something_with_object(object);
 123         dispatch_release(object);
 124 });
 125 .Ed
 126 .Sh SUSPENSION
 127 The invocation of blocks on dispatch queues or dispatch sources may be suspended
 128 or resumed with the functions
 129 .Fn dispatch_suspend
 130 and
 131 .Fn dispatch_resume
 132 respectively. Other dispatch objects do not support suspension.
 133 .Pp
 134 The dispatch framework always checks the suspension status before executing a
 135 block, but such changes never affect a block during execution (non-preemptive).
 136 Therefore the suspension of an object is asynchronous, unless it is performed
 137 from the context of the target queue for the given object.
 138 The result of suspending or resuming an object that is not a dispatch queue or
 139 a dispatch source is undefined.
 140 .Pp
 141 .Em Important :
 142 suspension applies to all aspects of the dispatch object life cycle, including
 143 the finalizer function and cancellation handler. Suspending an object causes it
 144 to be retained and resuming an object causes it to be released. Therefore it is
 145 important to balance calls to
 146 .Fn dispatch_suspend
 147 and
 148 .Fn dispatch_resume
 149 such that the dispatch object is fully resumed when the last reference is
 150 released. The result of releasing all references to a dispatch object while in
 151 a suspended state is undefined.
 152 .Sh CONTEXT POINTERS
 153 Dispatch objects support supplemental context pointers. The value of the
 154 context pointer may be retrieved and updated with
 155 .Fn dispatch_get_context
 156 and
 157 .Fn dispatch_set_context
 158 respectively.
 159 The
 160 .Fn dispatch_set_finalizer_f
 161 specifies an optional per-object finalizer function that is invoked
 162 asynchronously if the context pointer is not NULL when the last
 163 reference to the object is released.
 164 This gives the
 165 application an opportunity to free the context data associated with the object.
 166 The finalizer will be run on the object's target queue.
 167 .Sh SEE ALSO
 168 .Xr dispatch 3 ,
 169 .Xr dispatch_async 3 ,
 170 .Xr dispatch_group_create 3 ,
 171 .Xr dispatch_queue_create 3 ,
 172 .Xr dispatch_semaphore_create 3 ,
 173 .Xr dispatch_set_target_queue 3 ,
 174 .Xr dispatch_source_cancel 3 ,
 175 .Xr dispatch_source_create 3