dispatch/data.h

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