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 57Dispatch data objects are opaque containers of bytes that represent one or more 58regions of memory. They are created either from memory buffers managed by the 59application or the system or from other dispatch data objects. Dispatch data 60objects are immutable and the memory regions they represent are required to 61remain unchanged for the lifetime of all data objects that reference them. 62Dispatch data objects avoid copying the represented memory as much as possible. 63Multiple data objects can represent the same memory regions or subsections 64thereof. 65.Sh CREATION 66The 67.Fn dispatch_data_create 68function creates a new dispatch data object of given 69.Fa size 70from a 71.Fa buffer . 72The provided 73.Fa destructor 74block will be submitted to the specified 75.Fa queue 76when the object reaches the end of its lifecycle, indicating that the system no 77longer references the 78.Fa buffer . 79This allows the application to deallocate 80the associated storage. The 81.Fa queue 82argument 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 85indicates that the provided buffer can be deallocated with 86.Xr free 3 87directly. 88.It DISPATCH_DATA_DESTRUCTOR_DEFAULT 89indicates that the provided buffer is not managed by the application and should 90be copied into memory managed and automatically deallocated by the system. 91.El 92.Pp 93The 94.Fn dispatch_data_create_concat 95function creates a new data object representing the concatenation of the memory 96regions represented by the provided data objects. 97.Pp 98The 99.Fn dispatch_data_create_subrange 100function creates a new data object representing the sub-region of the provided 101.Fa data 102object specified by the 103.Fa offset 104and 105.Fa length 106parameters. 107.Pp 108The 109.Fn dispatch_data_create_map 110function creates a new data object by mapping the memory represented by the 111provided 112.Fa data 113object as a single contiguous memory region (moving or copying memory as 114necessary). If the 115.Fa buffer_ptr 116and 117.Fa size_ptr 118references are not 119.Dv NULL , 120they are filled with the location and extent of the contiguous region, allowing 121direct read access to the mapped memory. These values are valid only as long as 122the newly created object has not been released. 123.Sh ACCESS 124The 125.Fn dispatch_data_apply 126function provides read access to represented memory without requiring it to be 127mapped as a single contiguous region. It traverses the memory regions 128represented by the 129.Fa data 130argument in logical order, invokes the specified 131.Fa applier 132block for each region and returns a boolean indicating whether traversal 133completed successfully. The 134.Fa applier 135block is passed the following arguments for each memory region and returns a 136boolean indicating whether traversal should continue: 137.Bl -tag -width "dispatch_data_t rgn" -compact -offset indent 138.It Fa "dispatch_data_t rgn" 139data object representing the region 140.It Fa "size_t offset" 141logical position of the region in 142.Fa data 143.It Vt "const void *loc" 144memory location of the region 145.It Vt "size_t size" 146extent of the region 147.El 148The 149.Fa rgn 150data object is released by the system when the 151.Fa applier 152block returns. 153The associated memory location 154.Fa loc 155is valid only as long as 156.Fa rgn 157has not been deallocated; if 158.Fa loc 159is needed outside of the 160.Fa applier 161block, the 162.Fa rgn 163object must be retained in the block. 164.Pp 165The 166.Fn dispatch_data_copy_region 167function finds the contiguous memory region containing the logical position 168specified by the 169.Fa location 170argument among the regions represented by the provided 171.Fa data 172object and returns a newly created copy of the data object representing that 173region. The variable specified by the 174.Fa offset_ptr 175argument is filled with the logical position where the returned object starts 176in the 177.Fa data 178object. 179.Pp 180The 181.Fn dispatch_data_get_size 182function returns the logical size of the memory region or regions represented 183by the provided 184.Fa data 185object. 186.Sh EMPTY DATA OBJECT 187The 188.Vt dispatch_data_empty 189object is the global singleton object representing a zero-length memory region. 190It is a valid input to any dispatch_data functions that take data object 191parameters. 192.Sh MEMORY MODEL 193Dispatch data objects are retained and released via calls to 194.Fn dispatch_retain 195and 196.Fn dispatch_release . 197Data objects passed as arguments to a dispatch data 198.Sy create 199or 200.Sy copy 201function can be released when the function returns. The newly created object 202holds implicit references to their constituent memory regions as necessary. 203.Pp 204The functions 205.Fn dispatch_data_create_map 206and 207.Fn dispatch_data_apply 208return an interior pointer to represented memory that is only valid as long as 209an associated object has not been released. When Objective-C Automated 210Reference Counting is enabled, care needs to be taken if that object is held in 211a variable with automatic storage. It may need to be annotated with the 212.Li objc_precise_lifetime 213attribute, or stored in a 214.Li __strong 215instance variable instead, to ensure that the object is not released 216prematurely 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 221