1dispatch_data_create(3) BSD Library Functions Manual dispatch_data_create(3)
2
4 dispatch_data_create, dispatch_data_create_concat,
5 dispatch_data_create_subrange, dispatch_data_create_map,
6 dispatch_data_apply, dispatch_data_copy_region, dispatch_data_get_size —
7 create and manipulate dispatch data objects
8
10 #include <dispatch/dispatch.h>
11 dispatch_data_t
13 dispatch_data_create(const void* buffer, size_t size,
14 dispatch_queue_t queue, dispatch_block_t destructor);
15 dispatch_data_t
17 dispatch_data_create_concat(dispatch_data_t data1,
18 dispatch_data_t data2);
19 dispatch_data_t
21 dispatch_data_create_subrange(dispatch_data_t data, size_t offset,
22 size_t length);
23 dispatch_data_t
25 dispatch_data_create_map(dispatch_data_t data, const void **buffer_ptr,
26 size_t *size_ptr);
27 bool
29 dispatch_data_apply(dispatch_data_t data,
30 bool (^applier)(dispatch_data_t, size_t, const void *, size_t));
31 dispatch_data_t
33 dispatch_data_copy_region(dispatch_data_t data, size_t location,
34 size_t *offset_ptr);
35 size_t
37 dispatch_data_get_size(dispatch_data_t data);
38 dispatch_data_t dispatch_data_empty;
40
42 Dispatch data objects are opaque containers of bytes that represent one
43 or more regions of memory. They are created either from memory buffers
44 managed by the application or the system or from other dispatch data
45 objects. Dispatch data objects are immutable and the memory regions they
46 represent are required to remain unchanged for the lifetime of all data
47 objects that reference them. Dispatch data objects avoid copying the
48 represented memory as much as possible. Multiple data objects can repre‐
49 sent the same memory regions or subsections thereof.
50
52 The dispatch_data_create() function creates a new dispatch data object of
53 given size from a buffer. The provided destructor block will be submit‐
54 ted to the specified queue when the object reaches the end of its lifecy‐
55 cle, indicating that the system no longer references the buffer. This
56 allows the application to deallocate the associated storage. The queue
57 argument is ignored if one of the following predefined destructors is
58 passed:
59 DISPATCH_DATA_DESTRUCTOR_FREE indicates that the provided buf‐
60 fer can be deallocated with
61 free(3) directly.
62 DISPATCH_DATA_DESTRUCTOR_DEFAULT indicates that the provided buf‐
63 fer is not managed by the appli‐
64 cation and should be copied into
65 memory managed and automatically
66 deallocated by the system.
67 The dispatch_data_create_concat() function creates a new data object rep‐
69 resenting the concatenation of the memory regions represented by the pro‐
70 vided data objects.
71 The dispatch_data_create_subrange() function creates a new data object
73 representing the sub-region of the provided data object specified by the
74 offset and length parameters.
75 The dispatch_data_create_map() function creates a new data object by map‐
77 ping the memory represented by the provided data object as a single con‐
78 tiguous memory region (moving or copying memory as necessary). If the
79 buffer_ptr and size_ptr references are not NULL, they are filled with the
80 location and extent of the contiguous region, allowing direct read access
81 to the mapped memory. These values are valid only as long as the newly
82 created object has not been released.
83
85 The dispatch_data_apply() function provides read access to represented
86 memory without requiring it to be mapped as a single contiguous region.
87 It traverses the memory regions represented by the data argument in logi‐
88 cal order, invokes the specified applier block for each region and
89 returns a boolean indicating whether traversal completed successfully.
90 The applier block is passed the following arguments for each memory
91 region and returns a boolean indicating whether traversal should con‐
92 tinue:
93 dispatch_data_t rgn data object representing the region
94 size_t offset logical position of the region in data
95 const void *loc memory location of the region
96 size_t size extent of the region
97 The rgn data object is released by the system when the applier block
98 returns. The associated memory location loc is valid only as long as rgn
99 has not been deallocated; if loc is needed outside of the applier block,
100 the rgn object must be retained in the block.
101 The dispatch_data_copy_region() function finds the contiguous memory
103 region containing the logical position specified by the location argument
104 among the regions represented by the provided data object and returns a
105 newly created copy of the data object representing that region. The vari‐
106 able specified by the offset_ptr argument is filled with the logical
107 position where the returned object starts in the data object.
108 The dispatch_data_get_size() function returns the logical size of the
110 memory region or regions represented by the provided data object.
111
113 The dispatch_data_empty object is the global singleton object represent‐
114 ing a zero-length memory region. It is a valid input to any dis‐
115 patch_data functions that take data object parameters.
116
118 Dispatch data objects are retained and released via calls to
119 dispatch_retain() and dispatch_release(). Data objects passed as argu‐
120 ments to a dispatch data create or copy function can be released when the
121 function returns. The newly created object holds implicit references to
122 their constituent memory regions as necessary.
123 The functions dispatch_data_create_map() and dispatch_data_apply() return
125 an interior pointer to represented memory that is only valid as long as
126 an associated object has not been released. When Objective-C Automated
127 Reference Counting is enabled, care needs to be taken if that object is
128 held in a variable with automatic storage. It may need to be annotated
129 with the objc_precise_lifetime attribute, or stored in a __strong
130 instance variable instead, to ensure that the object is not released pre‐
131 maturely before memory accesses via the interor pointer have been com‐
132 pleted.
133
135 dispatch(3), dispatch_object(3), dispatch_io_read(3)
136Darwin December 1, 2010 Darwin