dispatch/data.h

@typedef dispatch_data_t A dispatch object representing memory regions.

DISPATCH_DATA_DECL_SWIFT(dispatch_data, __DispatchData)

@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)

@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

@parseOnly

#define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_##name

@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)

@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.7), ios(5.0)) DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchData.init(bytes:)") dispatch_data_t dispatch_data_create(
	const void *DISPATCH_SIZED_BY(size) buffer,
	size_t size,
	dispatch_queue_t _Nullable queue,
	dispatch_block_t _Nullable destructor
)

@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_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT size_t dispatch_data_get_size(
	dispatch_data_t data
)

@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_NONNULL1 DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT dispatch_data_t dispatch_data_create_map(
	dispatch_data_t data,
	const void *_Nullable DISPATCH_SIZED_BY(*size_ptr) *_Nullable buffer_ptr,
	size_t *_Nullable size_ptr
)

@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_NONNULL_ALL DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT dispatch_data_t dispatch_data_create_concat(
	dispatch_data_t data1,
	dispatch_data_t data2
)

@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_NONNULL1 DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT dispatch_data_t dispatch_data_create_subrange(
	dispatch_data_t data,
	size_t offset,
	size_t length
)

@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_NONNULL_ALL DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT bool dispatch_data_apply(
	dispatch_data_t data,
	DISPATCH_NOESCAPE dispatch_data_applier_t applier
)

@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_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_REFINED_FOR_SWIFT dispatch_data_t dispatch_data_copy_region(
	dispatch_data_t data,
	size_t location,
	size_t *offset_ptr
)

@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.