2 * Copyright (c) 2009-2011 Apple Inc. All rights reserved.
4 * @APPLE_APACHE_LICENSE_HEADER_START@
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
18 * @APPLE_APACHE_LICENSE_HEADER_END@
21 #ifndef __DISPATCH_DATA__
22 #define __DISPATCH_DATA__
24 #ifndef __DISPATCH_INDIRECT__
25 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
26 #include <dispatch/base.h> // for HeaderDoc
32 * Dispatch data objects describe contiguous or sparse regions of memory that
33 * may be managed by the system or by the application.
34 * Dispatch data objects are immutable, any direct access to memory regions
35 * represented by dispatch objects must not modify that memory.
39 * @typedef dispatch_data_t
40 * A dispatch object representing memory regions.
42 DISPATCH_DECL(dispatch_data
);
45 * @var dispatch_data_empty
46 * @discussion The singleton dispatch data object representing a zero-length
49 #define dispatch_data_empty (&_dispatch_data_empty)
50 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
51 DISPATCH_EXPORT
struct dispatch_data_s _dispatch_data_empty
;
56 * @const DISPATCH_DATA_DESTRUCTOR_DEFAULT
57 * @discussion The default destructor for dispatch data objects.
58 * Used at data object creation to indicate that the supplied buffer should
59 * be copied into internal storage managed by the system.
61 #define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL
64 * @const DISPATCH_DATA_DESTRUCTOR_FREE
65 * @discussion The destructor for dispatch data objects created from a malloc'd
66 * buffer. Used at data object creation to indicate that the supplied buffer
67 * was allocated by the malloc() family and should be destroyed with free(3).
69 #define DISPATCH_DATA_DESTRUCTOR_FREE (_dispatch_data_destructor_free)
70 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
71 DISPATCH_EXPORT
const dispatch_block_t _dispatch_data_destructor_free
;
74 * @function dispatch_data_create
75 * Creates a dispatch data object from the given contiguous buffer of memory. If
76 * a non-default destructor is provided, ownership of the buffer remains with
77 * the caller (i.e. the bytes will not be copied). The last release of the data
78 * object will result in the invocation of the specified destructor on the
79 * specified queue to free the buffer.
81 * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will
82 * be freed via free(3) and the queue argument ignored.
84 * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object
85 * creation will copy the buffer into internal memory managed by the system.
87 * @param buffer A contiguous buffer of data.
88 * @param size The size of the contiguous buffer of data.
89 * @param queue The queue to which the destructor should be submitted.
90 * @param destructor The destructor responsible for freeing the data when it
91 * is no longer needed.
92 * @result A newly created dispatch data object.
94 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
95 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
97 dispatch_data_create(const void *buffer
,
99 dispatch_queue_t queue
,
100 dispatch_block_t destructor
);
103 * @function dispatch_data_get_size
104 * Returns the logical size of the memory region(s) represented by the specified
105 * dispatch data object.
107 * @param data The dispatch data object to query.
108 * @result The number of bytes represented by the data object.
110 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
111 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW
113 dispatch_data_get_size(dispatch_data_t data
);
116 * @function dispatch_data_create_map
117 * Maps the memory represented by the specified dispatch data object as a single
118 * contiguous memory region and returns a new data object representing it.
119 * If non-NULL references to a pointer and a size variable are provided, they
120 * are filled with the location and extent of that region. These allow direct
121 * read access to the represented memory, but are only valid until the copy
122 * object is released.
124 * @param data The dispatch data object to map.
125 * @param buffer_ptr A pointer to a pointer variable to be filled with the
126 * location of the mapped contiguous memory region, or
128 * @param size_ptr A pointer to a size_t variable to be filled with the
129 * size of the mapped contiguous memory region, or NULL.
130 * @result A newly created dispatch data object.
132 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
133 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
135 dispatch_data_create_map(dispatch_data_t data
,
136 const void **buffer_ptr
,
140 * @function dispatch_data_create_concat
141 * Returns a new dispatch data object representing the concatenation of the
142 * specified data objects. Those objects may be released by the application
143 * after the call returns (however, the system might not deallocate the memory
144 * region(s) described by them until the newly created object has also been
147 * @param data1 The data object representing the region(s) of memory to place
148 * at the beginning of the newly created object.
149 * @param data2 The data object representing the region(s) of memory to place
150 * at the end of the newly created object.
151 * @result A newly created object representing the concatenation of the
152 * data1 and data2 objects.
154 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
155 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_NOTHROW
157 dispatch_data_create_concat(dispatch_data_t data1
, dispatch_data_t data2
);
160 * @function dispatch_data_create_subrange
161 * Returns a new dispatch data object representing a subrange of the specified
162 * data object, which may be released by the application after the call returns
163 * (however, the system might not deallocate the memory region(s) described by
164 * that object until the newly created object has also been released).
166 * @param data The data object representing the region(s) of memory to
167 * create a subrange of.
168 * @param offset The offset into the data object where the subrange
170 * @param length The length of the range.
171 * @result A newly created object representing the specified
172 * subrange of the data object.
174 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
175 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
177 dispatch_data_create_subrange(dispatch_data_t data
,
182 * @typedef dispatch_data_applier_t
183 * A block to be invoked for every contiguous memory region in a data object.
185 * @param region A data object representing the current region.
186 * @param offset The logical offset of the current region to the start
187 * of the data object.
188 * @param buffer The location of the memory for the current region.
189 * @param size The size of the memory for the current region.
190 * @result A Boolean indicating whether traversal should continue.
192 typedef bool (^dispatch_data_applier_t
)(dispatch_data_t region
,
198 * @function dispatch_data_apply
199 * Traverse the memory regions represented by the specified dispatch data object
200 * in logical order and invoke the specified block once for every contiguous
201 * memory region encountered.
203 * Each invocation of the block is passed a data object representing the current
204 * region and its logical offset, along with the memory location and extent of
205 * the region. These allow direct read access to the memory region, but are only
206 * valid until the passed-in region object is released. Note that the region
207 * object is released by the system when the block returns, it is the
208 * responsibility of the application to retain it if the region object or the
209 * associated memory location are needed after the block returns.
211 * @param data The data object to traverse.
212 * @param applier The block to be invoked for every contiguous memory
213 * region in the data object.
214 * @result A Boolean indicating whether traversal completed
217 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
218 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
220 dispatch_data_apply(dispatch_data_t data
, dispatch_data_applier_t applier
);
223 * @function dispatch_data_copy_region
224 * Finds the contiguous memory region containing the specified location among
225 * the regions represented by the specified object and returns a copy of the
226 * internal dispatch data object representing that region along with its logical
227 * offset in the specified object.
229 * @param data The dispatch data object to query.
230 * @param location The logical position in the data object to query.
231 * @param offset_ptr A pointer to a size_t variable to be filled with the
232 * logical offset of the returned region object to the
233 * start of the queried data object.
234 * @result A newly created dispatch data object.
236 __OSX_AVAILABLE_STARTING(__MAC_10_7
,__IPHONE_5_0
)
237 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_WARN_RESULT
240 dispatch_data_copy_region(dispatch_data_t data
,
244 #endif /* __BLOCKS__ */
248 #endif /* __DISPATCH_DATA__ */