| /* |
| * Copyright (c) 2009-2013 Apple Inc. All rights reserved. |
| * |
| * @APPLE_APACHE_LICENSE_HEADER_START@ |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| * @APPLE_APACHE_LICENSE_HEADER_END@ |
| */ |
| |
| #ifndef __DISPATCH_DATA__ |
| #define __DISPATCH_DATA__ |
| |
| #ifndef __DISPATCH_INDIRECT__ |
| #error "Please #include <dispatch/dispatch.h> instead of this file directly." |
| #include <dispatch/base.h> // for HeaderDoc |
| #endif |
| |
| DISPATCH_ASSUME_NONNULL_BEGIN |
| |
| __BEGIN_DECLS |
| |
| /*! @header |
| * Dispatch data objects describe contiguous or sparse regions of memory that |
| * may be managed by the system or by the application. |
| * Dispatch data objects are immutable, any direct access to memory regions |
| * represented by dispatch objects must not modify that memory. |
| */ |
| |
| /*! |
| * @typedef dispatch_data_t |
| * A dispatch object representing memory regions. |
| */ |
| DISPATCH_DATA_DECL(dispatch_data); |
| |
| /*! |
| * @var dispatch_data_empty |
| * @discussion The singleton dispatch data object representing a zero-length |
| * memory region. |
| */ |
| #define dispatch_data_empty \ |
| DISPATCH_GLOBAL_OBJECT(dispatch_data_t, _dispatch_data_empty) |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT struct dispatch_data_s _dispatch_data_empty; |
| |
| /*! |
| * @const DISPATCH_DATA_DESTRUCTOR_DEFAULT |
| * @discussion The default destructor for dispatch data objects. |
| * Used at data object creation to indicate that the supplied buffer should |
| * be copied into internal storage managed by the system. |
| */ |
| #define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL |
| |
| #ifdef __BLOCKS__ |
| #if !TARGET_OS_WIN32 |
| /*! @parseOnly */ |
| #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ |
| DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_##name |
| #else |
| #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ |
| DISPATCH_EXPORT dispatch_block_t _dispatch_data_destructor_##name |
| #endif |
| #else |
| #define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \ |
| DISPATCH_EXPORT const dispatch_function_t \ |
| _dispatch_data_destructor_##name |
| #endif /* __BLOCKS__ */ |
| |
| /*! |
| * @const DISPATCH_DATA_DESTRUCTOR_FREE |
| * @discussion The destructor for dispatch data objects created from a malloc'd |
| * buffer. Used at data object creation to indicate that the supplied buffer |
| * was allocated by the malloc() family and should be destroyed with free(3). |
| */ |
| #define DISPATCH_DATA_DESTRUCTOR_FREE (_dispatch_data_destructor_free) |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(free); |
| |
| /*! |
| * @const DISPATCH_DATA_DESTRUCTOR_MUNMAP |
| * @discussion The destructor for dispatch data objects that have been created |
| * from buffers that require deallocation with munmap(2). |
| */ |
| #define DISPATCH_DATA_DESTRUCTOR_MUNMAP (_dispatch_data_destructor_munmap) |
| API_AVAILABLE(macos(10.9), ios(7.0)) |
| DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(munmap); |
| |
| #ifdef __BLOCKS__ |
| /*! |
| * @function dispatch_data_create |
| * Creates a dispatch data object from the given contiguous buffer of memory. If |
| * a non-default destructor is provided, ownership of the buffer remains with |
| * the caller (i.e. the bytes will not be copied). The last release of the data |
| * object will result in the invocation of the specified destructor on the |
| * specified queue to free the buffer. |
| * |
| * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will |
| * be freed via free(3) and the queue argument ignored. |
| * |
| * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object |
| * creation will copy the buffer into internal memory managed by the system. |
| * |
| * @param buffer A contiguous buffer of data. |
| * @param size The size of the contiguous buffer of data. |
| * @param queue The queue to which the destructor should be submitted. |
| * @param destructor The destructor responsible for freeing the data when it |
| * is no longer needed. |
| * @result A newly created dispatch data object. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW |
| dispatch_data_t |
| dispatch_data_create(const void *buffer, |
| size_t size, |
| dispatch_queue_t _Nullable queue, |
| dispatch_block_t _Nullable destructor); |
| #endif /* __BLOCKS__ */ |
| |
| /*! |
| * @function dispatch_data_get_size |
| * Returns the logical size of the memory region(s) represented by the specified |
| * dispatch data object. |
| * |
| * @param data The dispatch data object to query. |
| * @result The number of bytes represented by the data object. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW |
| size_t |
| dispatch_data_get_size(dispatch_data_t data); |
| |
| /*! |
| * @function dispatch_data_create_map |
| * Maps the memory represented by the specified dispatch data object as a single |
| * contiguous memory region and returns a new data object representing it. |
| * If non-NULL references to a pointer and a size variable are provided, they |
| * are filled with the location and extent of that region. These allow direct |
| * read access to the represented memory, but are only valid until the returned |
| * object is released. Under ARC, if that object is held in a variable with |
| * automatic storage, care needs to be taken to ensure that it is not released |
| * by the compiler before memory access via the pointer has been completed. |
| * |
| * @param data The dispatch data object to map. |
| * @param buffer_ptr A pointer to a pointer variable to be filled with the |
| * location of the mapped contiguous memory region, or |
| * NULL. |
| * @param size_ptr A pointer to a size_t variable to be filled with the |
| * size of the mapped contiguous memory region, or NULL. |
| * @result A newly created dispatch data object. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED |
| DISPATCH_WARN_RESULT DISPATCH_NOTHROW |
| dispatch_data_t |
| dispatch_data_create_map(dispatch_data_t data, |
| const void *_Nullable *_Nullable buffer_ptr, |
| size_t *_Nullable size_ptr); |
| |
| /*! |
| * @function dispatch_data_create_concat |
| * Returns a new dispatch data object representing the concatenation of the |
| * specified data objects. Those objects may be released by the application |
| * after the call returns (however, the system might not deallocate the memory |
| * region(s) described by them until the newly created object has also been |
| * released). |
| * |
| * @param data1 The data object representing the region(s) of memory to place |
| * at the beginning of the newly created object. |
| * @param data2 The data object representing the region(s) of memory to place |
| * at the end of the newly created object. |
| * @result A newly created object representing the concatenation of the |
| * data1 and data2 objects. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED |
| DISPATCH_WARN_RESULT DISPATCH_NOTHROW |
| dispatch_data_t |
| dispatch_data_create_concat(dispatch_data_t data1, dispatch_data_t data2); |
| |
| /*! |
| * @function dispatch_data_create_subrange |
| * Returns a new dispatch data object representing a subrange of the specified |
| * data object, which may be released by the application after the call returns |
| * (however, the system might not deallocate the memory region(s) described by |
| * that object until the newly created object has also been released). |
| * |
| * @param data The data object representing the region(s) of memory to |
| * create a subrange of. |
| * @param offset The offset into the data object where the subrange |
| * starts. |
| * @param length The length of the range. |
| * @result A newly created object representing the specified |
| * subrange of the data object. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED |
| DISPATCH_WARN_RESULT DISPATCH_NOTHROW |
| dispatch_data_t |
| dispatch_data_create_subrange(dispatch_data_t data, |
| size_t offset, |
| size_t length); |
| |
| #ifdef __BLOCKS__ |
| /*! |
| * @typedef dispatch_data_applier_t |
| * A block to be invoked for every contiguous memory region in a data object. |
| * |
| * @param region A data object representing the current region. |
| * @param offset The logical offset of the current region to the start |
| * of the data object. |
| * @param buffer The location of the memory for the current region. |
| * @param size The size of the memory for the current region. |
| * @result A Boolean indicating whether traversal should continue. |
| */ |
| typedef bool (^dispatch_data_applier_t)(dispatch_data_t region, |
| size_t offset, |
| const void *buffer, |
| size_t size); |
| |
| /*! |
| * @function dispatch_data_apply |
| * Traverse the memory regions represented by the specified dispatch data object |
| * in logical order and invoke the specified block once for every contiguous |
| * memory region encountered. |
| * |
| * Each invocation of the block is passed a data object representing the current |
| * region and its logical offset, along with the memory location and extent of |
| * the region. These allow direct read access to the memory region, but are only |
| * valid until the passed-in region object is released. Note that the region |
| * object is released by the system when the block returns, it is the |
| * responsibility of the application to retain it if the region object or the |
| * associated memory location are needed after the block returns. |
| * |
| * @param data The data object to traverse. |
| * @param applier The block to be invoked for every contiguous memory |
| * region in the data object. |
| * @result A Boolean indicating whether traversal completed |
| * successfully. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
| bool |
| dispatch_data_apply(dispatch_data_t data, |
| DISPATCH_NOESCAPE dispatch_data_applier_t applier); |
| #endif /* __BLOCKS__ */ |
| |
| /*! |
| * @function dispatch_data_copy_region |
| * Finds the contiguous memory region containing the specified location among |
| * the regions represented by the specified object and returns a copy of the |
| * internal dispatch data object representing that region along with its logical |
| * offset in the specified object. |
| * |
| * @param data The dispatch data object to query. |
| * @param location The logical position in the data object to query. |
| * @param offset_ptr A pointer to a size_t variable to be filled with the |
| * logical offset of the returned region object to the |
| * start of the queried data object. |
| * @result A newly created dispatch data object. |
| */ |
| API_AVAILABLE(macos(10.7), ios(5.0)) |
| DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED |
| DISPATCH_WARN_RESULT DISPATCH_NOTHROW |
| dispatch_data_t |
| dispatch_data_copy_region(dispatch_data_t data, |
| size_t location, |
| size_t *offset_ptr); |
| |
| __END_DECLS |
| |
| DISPATCH_ASSUME_NONNULL_END |
| |
| #endif /* __DISPATCH_DATA__ */ |