data.h (11403B) - Raw
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 DISPATCH_ASSUME_NONNULL_BEGIN 30 DISPATCH_ASSUME_ABI_SINGLE_BEGIN 31 32 __BEGIN_DECLS 33 34 /*! @header 35 * Dispatch data objects describe contiguous or sparse regions of memory that 36 * may be managed by the system or by the application. 37 * Dispatch data objects are immutable, any direct access to memory regions 38 * represented by dispatch objects must not modify that memory. 39 */ 40 41 /*! 42 * @typedef dispatch_data_t 43 * A dispatch object representing memory regions. 44 */ 45 DISPATCH_DATA_DECL_SWIFT(dispatch_data, __DispatchData); 46 47 /*! 48 * @var dispatch_data_empty 49 * @discussion The singleton dispatch data object representing a zero-length 50 * memory region. 51 */ 52 #define dispatch_data_empty \ 53 DISPATCH_GLOBAL_OBJECT(dispatch_data_t, _dispatch_data_empty) 54 API_AVAILABLE(macos(10.7), ios(5.0)) 55 DISPATCH_EXPORT struct dispatch_data_s _dispatch_data_empty; 56 57 /*! 58 * @const DISPATCH_DATA_DESTRUCTOR_DEFAULT 59 * @discussion The default destructor for dispatch data objects. 60 * Used at data object creation to indicate that the supplied buffer should 61 * be copied into internal storage managed by the system. 62 */ 63 #define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL 64 65 #ifdef __BLOCKS__ 66 /*! @parseOnly */ 67 #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ 68 DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_##name 69 #else 70 #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ 71 DISPATCH_EXPORT const dispatch_function_t \ 72 _dispatch_data_destructor_##name 73 #endif /* __BLOCKS__ */ 74 75 /*! 76 * @const DISPATCH_DATA_DESTRUCTOR_FREE 77 * @discussion The destructor for dispatch data objects created from a malloc'd 78 * buffer. Used at data object creation to indicate that the supplied buffer 79 * was allocated by the malloc() family and should be destroyed with free(3). 80 */ 81 #define DISPATCH_DATA_DESTRUCTOR_FREE (_dispatch_data_destructor_free) 82 API_AVAILABLE(macos(10.7), ios(5.0)) 83 DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift") 84 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(free); 85 86 /*! 87 * @const DISPATCH_DATA_DESTRUCTOR_MUNMAP 88 * @discussion The destructor for dispatch data objects that have been created 89 * from buffers that require deallocation with munmap(2). 90 */ 91 #define DISPATCH_DATA_DESTRUCTOR_MUNMAP (_dispatch_data_destructor_munmap) 92 API_AVAILABLE(macos(10.9), ios(7.0)) 93 DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift") 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 API_AVAILABLE(macos(10.7), ios(5.0)) 119 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW 120 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchData.init(bytes:)") 121 dispatch_data_t 122 dispatch_data_create(const void *DISPATCH_SIZED_BY(size) buffer, 123 size_t size, 124 dispatch_queue_t _Nullable queue, 125 dispatch_block_t _Nullable destructor); 126 #endif /* __BLOCKS__ */ 127 128 /*! 129 * @function dispatch_data_get_size 130 * Returns the logical size of the memory region(s) represented by the specified 131 * dispatch data object. 132 * 133 * @param data The dispatch data object to query. 134 * @result The number of bytes represented by the data object. 135 */ 136 API_AVAILABLE(macos(10.7), ios(5.0)) 137 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW 138 DISPATCH_REFINED_FOR_SWIFT 139 size_t 140 dispatch_data_get_size(dispatch_data_t data); 141 142 /*! 143 * @function dispatch_data_create_map 144 * Maps the memory represented by the specified dispatch data object as a single 145 * contiguous memory region and returns a new data object representing it. 146 * If non-NULL references to a pointer and a size variable are provided, they 147 * are filled with the location and extent of that region. These allow direct 148 * read access to the represented memory, but are only valid until the returned 149 * object is released. Under ARC, if that object is held in a variable with 150 * automatic storage, care needs to be taken to ensure that it is not released 151 * by the compiler before memory access via the pointer has been completed. 152 * 153 * @param data The dispatch data object to map. 154 * @param buffer_ptr A pointer to a pointer variable to be filled with the 155 * location of the mapped contiguous memory region, or 156 * NULL. 157 * @param size_ptr A pointer to a size_t variable to be filled with the 158 * size of the mapped contiguous memory region, or NULL. 159 * @result A newly created dispatch data object. 160 */ 161 API_AVAILABLE(macos(10.7), ios(5.0)) 162 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED 163 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 164 DISPATCH_REFINED_FOR_SWIFT 165 dispatch_data_t 166 dispatch_data_create_map(dispatch_data_t data, 167 const void *_Nullable DISPATCH_SIZED_BY(*size_ptr) *_Nullable buffer_ptr, 168 size_t *_Nullable size_ptr); 169 170 /*! 171 * @function dispatch_data_create_concat 172 * Returns a new dispatch data object representing the concatenation of the 173 * specified data objects. Those objects may be released by the application 174 * after the call returns (however, the system might not deallocate the memory 175 * region(s) described by them until the newly created object has also been 176 * released). 177 * 178 * @param data1 The data object representing the region(s) of memory to place 179 * at the beginning of the newly created object. 180 * @param data2 The data object representing the region(s) of memory to place 181 * at the end of the newly created object. 182 * @result A newly created object representing the concatenation of the 183 * data1 and data2 objects. 184 */ 185 API_AVAILABLE(macos(10.7), ios(5.0)) 186 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED 187 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 188 DISPATCH_REFINED_FOR_SWIFT 189 dispatch_data_t 190 dispatch_data_create_concat(dispatch_data_t data1, dispatch_data_t data2); 191 192 /*! 193 * @function dispatch_data_create_subrange 194 * Returns a new dispatch data object representing a subrange of the specified 195 * data object, which may be released by the application after the call returns 196 * (however, the system might not deallocate the memory region(s) described by 197 * that object until the newly created object has also been released). 198 * 199 * @param data The data object representing the region(s) of memory to 200 * create a subrange of. 201 * @param offset The offset into the data object where the subrange 202 * starts. 203 * @param length The length of the range. 204 * @result A newly created object representing the specified 205 * subrange of the data object. 206 */ 207 API_AVAILABLE(macos(10.7), ios(5.0)) 208 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED 209 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 210 DISPATCH_REFINED_FOR_SWIFT 211 dispatch_data_t 212 dispatch_data_create_subrange(dispatch_data_t data, 213 size_t offset, 214 size_t length); 215 216 #ifdef __BLOCKS__ 217 /*! 218 * @typedef dispatch_data_applier_t 219 * A block to be invoked for every contiguous memory region in a data object. 220 * 221 * @param region A data object representing the current region. 222 * @param offset The logical offset of the current region to the start 223 * of the data object. 224 * @param buffer The location of the memory for the current region. 225 * @param size The size of the memory for the current region. 226 * @result A Boolean indicating whether traversal should continue. 227 */ 228 DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift") 229 typedef bool (^dispatch_data_applier_t)(dispatch_data_t region, 230 size_t offset, 231 const void *DISPATCH_SIZED_BY(size) buffer, 232 size_t size); 233 234 /*! 235 * @function dispatch_data_apply 236 * Traverse the memory regions represented by the specified dispatch data object 237 * in logical order and invoke the specified block once for every contiguous 238 * memory region encountered. 239 * 240 * Each invocation of the block is passed a data object representing the current 241 * region and its logical offset, along with the memory location and extent of 242 * the region. These allow direct read access to the memory region, but are only 243 * valid until the passed-in region object is released. Note that the region 244 * object is released by the system when the block returns, it is the 245 * responsibility of the application to retain it if the region object or the 246 * associated memory location are needed after the block returns. 247 * 248 * @param data The data object to traverse. 249 * @param applier The block to be invoked for every contiguous memory 250 * region in the data object. 251 * @result A Boolean indicating whether traversal completed 252 * successfully. 253 */ 254 API_AVAILABLE(macos(10.7), ios(5.0)) 255 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 256 DISPATCH_REFINED_FOR_SWIFT 257 bool 258 dispatch_data_apply(dispatch_data_t data, 259 DISPATCH_NOESCAPE dispatch_data_applier_t applier); 260 #endif /* __BLOCKS__ */ 261 262 /*! 263 * @function dispatch_data_copy_region 264 * Finds the contiguous memory region containing the specified location among 265 * the regions represented by the specified object and returns a copy of the 266 * internal dispatch data object representing that region along with its logical 267 * offset in the specified object. 268 * 269 * @param data The dispatch data object to query. 270 * @param location The logical position in the data object to query. 271 * @param offset_ptr A pointer to a size_t variable to be filled with the 272 * logical offset of the returned region object to the 273 * start of the queried data object. 274 * @result A newly created dispatch data object. 275 */ 276 API_AVAILABLE(macos(10.7), ios(5.0)) 277 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED 278 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 279 DISPATCH_REFINED_FOR_SWIFT 280 dispatch_data_t 281 dispatch_data_copy_region(dispatch_data_t data, 282 size_t location, 283 size_t *offset_ptr); 284 285 __END_DECLS 286 287 DISPATCH_ASSUME_ABI_SINGLE_END 288 DISPATCH_ASSUME_NONNULL_END 289 290 #endif /* __DISPATCH_DATA__ */