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 __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__ */