1 /* 2 * Copyright (c) 2009-2013 Apple Inc. All rights reserved. 3 * 4 * @APPLE_APACHE_LICENSE_HEADER_START@ 5 * 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 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 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. 17 * 18 * @APPLE_APACHE_LICENSE_HEADER_END@ 19 */ 20 21 #ifndef __DISPATCH_DATA__ 22 #define __DISPATCH_DATA__ 23 24 #ifndef __DISPATCH_INDIRECT__ 25 #error "Please #include <dispatch/dispatch.h> instead of this file directly." 26 #include <dispatch/base.h> // for HeaderDoc 27 #endif 28 29 __BEGIN_DECLS 30 31 /*! @header 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. 36 */ 37 38 /*! 39 * @typedef dispatch_data_t 40 * A dispatch object representing memory regions. 41 */ 42 DISPATCH_DECL(dispatch_data); 43 44 /*! 45 * @var dispatch_data_empty 46 * @discussion The singleton dispatch data object representing a zero-length 47 * memory region. 48 */ 49 #define dispatch_data_empty \ 50 DISPATCH_GLOBAL_OBJECT(dispatch_data_t, _dispatch_data_empty) 51 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 52 DISPATCH_EXPORT struct dispatch_data_s _dispatch_data_empty; 53 54 /*! 55 * @const DISPATCH_DATA_DESTRUCTOR_DEFAULT 56 * @discussion The default destructor for dispatch data objects. 57 * Used at data object creation to indicate that the supplied buffer should 58 * be copied into internal storage managed by the system. 59 */ 60 #define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL 61 62 #ifdef __BLOCKS__ 63 #if !TARGET_OS_WIN32 64 /*! @parseOnly */ 65 #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ 66 DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_##name 67 #else 68 #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ 69 DISPATCH_EXPORT dispatch_block_t _dispatch_data_destructor_##name 70 #endif 71 #else 72 #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ 73 DISPATCH_EXPORT const dispatch_function_t \ 74 _dispatch_data_destructor_##name 75 #endif /* __BLOCKS__ */ 76 77 /*! 78 * @const DISPATCH_DATA_DESTRUCTOR_FREE 79 * @discussion The destructor for dispatch data objects created from a malloc'd 80 * buffer. Used at data object creation to indicate that the supplied buffer 81 * was allocated by the malloc() family and should be destroyed with free(3). 82 */ 83 #define DISPATCH_DATA_DESTRUCTOR_FREE (_dispatch_data_destructor_free) 84 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 85 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(free); 86 87 /*! 88 * @const DISPATCH_DATA_DESTRUCTOR_MUNMAP 89 * @discussion The destructor for dispatch data objects that have been created 90 * from buffers that require deallocation with munmap(2). 91 */ 92 #define DISPATCH_DATA_DESTRUCTOR_MUNMAP (_dispatch_data_destructor_munmap) 93 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 94 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(munmap); 95 96 #ifdef __BLOCKS__ 97 /*! 98 * @function dispatch_data_create 99 * Creates a dispatch data object from the given contiguous buffer of memory. If 100 * a non-default destructor is provided, ownership of the buffer remains with 101 * the caller (i.e. the bytes will not be copied). The last release of the data 102 * object will result in the invocation of the specified destructor on the 103 * specified queue to free the buffer. 104 * 105 * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will 106 * be freed via free(3) and the queue argument ignored. 107 * 108 * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object 109 * creation will copy the buffer into internal memory managed by the system. 110 * 111 * @param buffer A contiguous buffer of data. 112 * @param size The size of the contiguous buffer of data. 113 * @param queue The queue to which the destructor should be submitted. 114 * @param destructor The destructor responsible for freeing the data when it 115 * is no longer needed. 116 * @result A newly created dispatch data object. 117 */ 118 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 119 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW 120 dispatch_data_t 121 dispatch_data_create(const void *buffer, 122 size_t size, 123 dispatch_queue_t queue, 124 dispatch_block_t destructor); 125 #endif /* __BLOCKS__ */ 126 127 /*! 128 * @function dispatch_data_get_size 129 * Returns the logical size of the memory region(s) represented by the specified 130 * dispatch data object. 131 * 132 * @param data The dispatch data object to query. 133 * @result The number of bytes represented by the data object. 134 */ 135 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 136 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW 137 size_t 138 dispatch_data_get_size(dispatch_data_t data); 139 140 /*! 141 * @function dispatch_data_create_map 142 * Maps the memory represented by the specified dispatch data object as a single 143 * contiguous memory region and returns a new data object representing it. 144 * If non-NULL references to a pointer and a size variable are provided, they 145 * are filled with the location and extent of that region. These allow direct 146 * read access to the represented memory, but are only valid until the returned 147 * object is released. Under ARC, if that object is held in a variable with 148 * automatic storage, care needs to be taken to ensure that it is not released 149 * by the compiler before memory access via the pointer has been completed. 150 * 151 * @param data The dispatch data object to map. 152 * @param buffer_ptr A pointer to a pointer variable to be filled with the 153 * location of the mapped contiguous memory region, or 154 * NULL. 155 * @param size_ptr A pointer to a size_t variable to be filled with the 156 * size of the mapped contiguous memory region, or NULL. 157 * @result A newly created dispatch data object. 158 */ 159 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 160 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED 161 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 162 dispatch_data_t 163 dispatch_data_create_map(dispatch_data_t data, 164 const void **buffer_ptr, 165 size_t *size_ptr); 166 167 /*! 168 * @function dispatch_data_create_concat 169 * Returns a new dispatch data object representing the concatenation of the 170 * specified data objects. Those objects may be released by the application 171 * after the call returns (however, the system might not deallocate the memory 172 * region(s) described by them until the newly created object has also been 173 * released). 174 * 175 * @param data1 The data object representing the region(s) of memory to place 176 * at the beginning of the newly created object. 177 * @param data2 The data object representing the region(s) of memory to place 178 * at the end of the newly created object. 179 * @result A newly created object representing the concatenation of the 180 * data1 and data2 objects. 181 */ 182 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 183 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED 184 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 185 dispatch_data_t 186 dispatch_data_create_concat(dispatch_data_t data1, dispatch_data_t data2); 187 188 /*! 189 * @function dispatch_data_create_subrange 190 * Returns a new dispatch data object representing a subrange of the specified 191 * data object, which may be released by the application after the call returns 192 * (however, the system might not deallocate the memory region(s) described by 193 * that object until the newly created object has also been released). 194 * 195 * @param data The data object representing the region(s) of memory to 196 * create a subrange of. 197 * @param offset The offset into the data object where the subrange 198 * starts. 199 * @param length The length of the range. 200 * @result A newly created object representing the specified 201 * subrange of the data object. 202 */ 203 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 204 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED 205 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 206 dispatch_data_t 207 dispatch_data_create_subrange(dispatch_data_t data, 208 size_t offset, 209 size_t length); 210 211 #ifdef __BLOCKS__ 212 /*! 213 * @typedef dispatch_data_applier_t 214 * A block to be invoked for every contiguous memory region in a data object. 215 * 216 * @param region A data object representing the current region. 217 * @param offset The logical offset of the current region to the start 218 * of the data object. 219 * @param buffer The location of the memory for the current region. 220 * @param size The size of the memory for the current region. 221 * @result A Boolean indicating whether traversal should continue. 222 */ 223 typedef bool (^dispatch_data_applier_t)(dispatch_data_t region, 224 size_t offset, 225 const void *buffer, 226 size_t size); 227 228 /*! 229 * @function dispatch_data_apply 230 * Traverse the memory regions represented by the specified dispatch data object 231 * in logical order and invoke the specified block once for every contiguous 232 * memory region encountered. 233 * 234 * Each invocation of the block is passed a data object representing the current 235 * region and its logical offset, along with the memory location and extent of 236 * the region. These allow direct read access to the memory region, but are only 237 * valid until the passed-in region object is released. Note that the region 238 * object is released by the system when the block returns, it is the 239 * responsibility of the application to retain it if the region object or the 240 * associated memory location are needed after the block returns. 241 * 242 * @param data The data object to traverse. 243 * @param applier The block to be invoked for every contiguous memory 244 * region in the data object. 245 * @result A Boolean indicating whether traversal completed 246 * successfully. 247 */ 248 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 249 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 250 bool 251 dispatch_data_apply(dispatch_data_t data, dispatch_data_applier_t applier); 252 #endif /* __BLOCKS__ */ 253 254 /*! 255 * @function dispatch_data_copy_region 256 * Finds the contiguous memory region containing the specified location among 257 * the regions represented by the specified object and returns a copy of the 258 * internal dispatch data object representing that region along with its logical 259 * offset in the specified object. 260 * 261 * @param data The dispatch data object to query. 262 * @param location The logical position in the data object to query. 263 * @param offset_ptr A pointer to a size_t variable to be filled with the 264 * logical offset of the returned region object to the 265 * start of the queried data object. 266 * @result A newly created dispatch data object. 267 */ 268 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 269 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED 270 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 271 dispatch_data_t 272 dispatch_data_copy_region(dispatch_data_t data, 273 size_t location, 274 size_t *offset_ptr); 275 276 __END_DECLS 277 278 #endif /* __DISPATCH_DATA__ */ 279