man/dispatch_data_create.3

   1 .\" Copyright (c) 2010-2012 Apple Inc. All rights reserved.
   2 .Dd December 1, 2010
   3 .Dt dispatch_data_create 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_data_create ,
   7 .Nm dispatch_data_create_concat ,
   8 .Nm dispatch_data_create_subrange ,
   9 .Nm dispatch_data_create_map ,
  10 .Nm dispatch_data_apply ,
  11 .Nm dispatch_data_copy_region ,
  12 .Nm dispatch_data_get_size
  13 .Nd create and manipulate dispatch data objects
  14 .Sh SYNOPSIS
  15 .Fd #include <dispatch/dispatch.h>
  16 .Ft dispatch_data_t
  17 .Fo dispatch_data_create
  18 .Fa "const void* buffer"
  19 .Fa "size_t size"
  20 .Fa "dispatch_queue_t queue"
  21 .Fa "dispatch_block_t destructor"
  22 .Fc
  23 .Ft dispatch_data_t
  24 .Fo dispatch_data_create_concat
  25 .Fa "dispatch_data_t data1"
  26 .Fa "dispatch_data_t data2"
  27 .Fc
  28 .Ft dispatch_data_t
  29 .Fo dispatch_data_create_subrange
  30 .Fa "dispatch_data_t data"
  31 .Fa "size_t offset"
  32 .Fa "size_t length"
  33 .Fc
  34 .Ft dispatch_data_t
  35 .Fo dispatch_data_create_map
  36 .Fa "dispatch_data_t data"
  37 .Fa "const void **buffer_ptr"
  38 .Fa "size_t *size_ptr"
  39 .Fc
  40 .Ft bool
  41 .Fo dispatch_data_apply
  42 .Fa "dispatch_data_t data"
  43 .Fa "bool (^applier)(dispatch_data_t, size_t, const void *, size_t)"
  44 .Fc
  45 .Ft dispatch_data_t
  46 .Fo dispatch_data_copy_region
  47 .Fa "dispatch_data_t data"
  48 .Fa "size_t location"
  49 .Fa "size_t *offset_ptr"
  50 .Fc
  51 .Ft size_t
  52 .Fo dispatch_data_get_size
  53 .Fa "dispatch_data_t data"
  54 .Fc
  55 .Vt dispatch_data_t dispatch_data_empty ;
  56 .Sh DESCRIPTION
  57 Dispatch data objects are opaque containers of bytes that represent one or more
  58 regions of memory. They are created either from memory buffers managed by the
  59 application or the system or from other dispatch data objects. Dispatch data
  60 objects are immutable and the memory regions they represent are required to
  61 remain unchanged for the lifetime of all data objects that reference them.
  62 Dispatch data objects avoid copying the represented memory as much as possible.
  63 Multiple data objects can represent the same memory regions or subsections
  64 thereof.
  65 .Sh CREATION
  66 The
  67 .Fn dispatch_data_create
  68 function creates a new dispatch data object of given
  69 .Fa size
  70 from a
  71 .Fa buffer .
  72 The provided
  73 .Fa destructor
  74 block will be submitted to the specified
  75 .Fa queue
  76 when the object reaches the end of its lifecycle, indicating that the system no
  77 longer references the
  78 .Fa buffer .
  79 This allows the application to deallocate
  80 the associated storage. The
  81 .Fa queue
  82 argument is ignored if one of the following predefined destructors is passed:
  83 .Bl -tag -width DISPATCH_DATA_DESTRUCTOR_DEFAULT -compact -offset indent
  84 .It DISPATCH_DATA_DESTRUCTOR_FREE
  85 indicates that the provided buffer can be deallocated with
  86 .Xr free 3
  87 directly.
  88 .It DISPATCH_DATA_DESTRUCTOR_DEFAULT
  89 indicates that the provided buffer is not managed by the application and should
  90 be copied into memory managed and automatically deallocated by the system.
  91 .El
  92 .Pp
  93 The
  94 .Fn dispatch_data_create_concat
  95 function creates a new data object representing the concatenation of the memory
  96 regions represented by the provided data objects.
  97 .Pp
  98 The
  99 .Fn dispatch_data_create_subrange
 100 function creates a new data object representing the sub-region of the provided
 101 .Fa data
 102 object specified by the
 103 .Fa offset
 104 and
 105 .Fa length
 106 parameters.
 107 .Pp
 108 The
 109 .Fn dispatch_data_create_map
 110 function creates a new data object by mapping the memory represented by the
 111 provided
 112 .Fa data
 113 object as a single contiguous memory region (moving or copying memory as
 114 necessary). If the
 115 .Fa buffer_ptr
 116 and
 117 .Fa size_ptr
 118 references are not
 119 .Dv NULL ,
 120 they are filled with the location and extent of the contiguous region, allowing
 121 direct read access to the mapped memory. These values are valid only as long as
 122 the newly created object has not been released.
 123 .Sh ACCESS
 124 The
 125 .Fn dispatch_data_apply
 126 function provides read access to represented memory without requiring it to be
 127 mapped as a single contiguous region. It traverses the memory regions
 128 represented by the
 129 .Fa data
 130 argument in logical order, invokes the specified
 131 .Fa applier
 132 block for each region and returns a boolean indicating whether traversal
 133 completed successfully. The
 134 .Fa applier
 135 block is passed the following arguments for each memory region and returns a
 136 boolean indicating whether traversal should continue:
 137 .Bl -tag -width "dispatch_data_t rgn" -compact -offset indent
 138 .It Fa "dispatch_data_t rgn"
 139 data object representing the region
 140 .It Fa "size_t offset"
 141 logical position of the region in
 142 .Fa data
 143 .It Vt "const void *loc"
 144 memory location of the region
 145 .It Vt "size_t size"
 146 extent of the region
 147 .El
 148 The
 149 .Fa rgn
 150 data object is released by the system when the
 151 .Fa applier
 152 block returns.
 153 The associated memory location
 154 .Fa loc
 155 is valid only as long as
 156 .Fa rgn
 157 has not been deallocated; if
 158 .Fa loc
 159 is needed outside of the
 160 .Fa applier
 161 block, the
 162 .Fa rgn
 163 object must be retained in the block.
 164 .Pp
 165 The
 166 .Fn dispatch_data_copy_region
 167 function finds the contiguous memory region containing the logical position
 168 specified by the
 169 .Fa location
 170 argument among the regions represented by the provided
 171 .Fa data
 172 object and returns a newly created copy of the data object representing that
 173 region. The variable specified by the
 174 .Fa offset_ptr
 175 argument is filled with the logical position where the returned object starts
 176 in the
 177 .Fa data
 178 object.
 179 .Pp
 180 The
 181 .Fn dispatch_data_get_size
 182 function returns the logical size of the memory region or regions represented
 183 by the provided
 184 .Fa data
 185 object.
 186 .Sh EMPTY DATA OBJECT
 187 The
 188 .Vt dispatch_data_empty
 189 object is the global singleton object representing a zero-length memory region.
 190 It is a valid input to any dispatch_data functions that take data object
 191 parameters.
 192 .Sh MEMORY MODEL
 193 Dispatch data objects are retained and released via calls to
 194 .Fn dispatch_retain
 195 and
 196 .Fn dispatch_release .
 197 Data objects passed as arguments to a dispatch data
 198 .Sy create
 199 or
 200 .Sy copy
 201 function can be released when the function returns. The newly created object
 202 holds implicit references to their constituent memory regions as necessary.
 203 .Pp
 204 The functions
 205 .Fn dispatch_data_create_map
 206 and
 207 .Fn dispatch_data_apply
 208 return an interior pointer to represented memory that is only valid as long as
 209 an associated object has not been released. When Objective-C Automated
 210 Reference Counting is enabled, care needs to be taken if that object is held in
 211 a variable with automatic storage. It may need to be annotated with the
 212 .Li objc_precise_lifetime
 213 attribute, or stored in a
 214 .Li __strong
 215 instance variable instead, to ensure that the object is not released
 216 prematurely before memory accesses via the interor pointer have been completed.
 217 .Sh SEE ALSO
 218 .Xr dispatch 3 ,
 219 .Xr dispatch_object 3 ,
 220 .Xr dispatch_io_read 3