data.h

Introduction

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.

Functions

dispatch_data_apply

dispatch_data_copy_region

dispatch_data_create

dispatch_data_create_concat

dispatch_data_create_map

dispatch_data_create_subrange

dispatch_data_get_size

dispatch_data_apply

(
    macos(
        10.7),
    ios(
        5.0))  bool dispatch_data_apply(
    dispatch_data_t data, 
    DISPATCH_NOESCAPE dispatch_data_applier_t applier);  

Parameters

Return Value

A Boolean indicating whether traversal completed successfully.

Discussion

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.

dispatch_data_copy_region

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED  dispatch_data_t dispatch_data_copy_region(
    dispatch_data_t data, 
    size_t location, 
    size_t *offset_ptr);  

Parameters

Return Value

A newly created dispatch data object.

Discussion

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.

dispatch_data_create

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_RETURNS_RETAINED  dispatch_data_t dispatch_data_create(
    const void *buffer, 
    size_t size, 
    dispatch_queue_t _Nullable queue, 
    dispatch_block_t _Nullable destructor);  

Parameters

Return Value

A newly created dispatch data object.

Discussion

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.

dispatch_data_create_concat

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_RETURNS_RETAINED  dispatch_data_t dispatch_data_create_concat(
    dispatch_data_t data1,
    dispatch_data_t data2);  

Parameters

Return Value

A newly created object representing the concatenation of the data1 and data2 objects.

Discussion

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

dispatch_data_create_map

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED  dispatch_data_t dispatch_data_create_map(
    dispatch_data_t data, 
    const void *_Nullable *_Nullable buffer_ptr, 
    size_t *_Nullable size_ptr);  

Parameters

Return Value

A newly created dispatch data object.

Discussion

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.

dispatch_data_create_subrange

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED  dispatch_data_t dispatch_data_create_subrange(
    dispatch_data_t data, 
    size_t offset, 
    size_t length);  

Parameters

Return Value

A newly created object representing the specified subrange of the data object.

Discussion

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

dispatch_data_get_size

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1  size_t dispatch_data_get_size(
    dispatch_data_t data);  

Parameters

Return Value

The number of bytes represented by the data object.

Discussion

Returns the logical size of the memory region(s) represented by the specified dispatch data object.

Typedefs

dispatch_data_applier_t

dispatch_data_t

dispatch_data_applier_t

typedef bool (^dispatch_data_applier_t)(
    dispatch_data_t region, 
    size_t offset, 
    const void *buffer, 
    size_t size);  

Parameters

Return Value

A Boolean indicating whether traversal should continue.

Discussion

A block to be invoked for every contiguous memory region in a data object.

dispatch_data_t

typedef struct dispatch_data_s *dispatch_data_t;  

Discussion

A dispatch object representing memory regions.

Globals

_dispatch_data_empty

dispatch_data_empty

_dispatch_data_empty

(
    macos(
        10.7),
    ios(
        5.0)) struct dispatch_data_s _dispatch_data_empty;  

Discussion

The singleton dispatch data object representing a zero-length memory region.

See Also

dispatch_data_empty

(
    macos(
        10.7),
    ios(
        5.0)) struct dispatch_data_s _dispatch_data_empty;  

Discussion

The singleton dispatch data object representing a zero-length memory region.

See Also

Macro Definitions

DISPATCH_DATA_DESTRUCTOR_DEFAULT

DISPATCH_DATA_DESTRUCTOR_FREE

DISPATCH_DATA_DESTRUCTOR_MUNMAP

dispatch_data_empty

DISPATCH_DATA_DESTRUCTOR_DEFAULT

#define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL 

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.

DISPATCH_DATA_DESTRUCTOR_FREE

#define 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).

DISPATCH_DATA_DESTRUCTOR_MUNMAP

#define DISPATCH_DATA_DESTRUCTOR_MUNMAP  

Discussion

The destructor for dispatch data objects that have been created from buffers that require deallocation with munmap(2).

dispatch_data_empty

#define dispatch_data_empty \ 
    DISPATCH_GLOBAL_OBJECT(dispatch_data_t, _dispatch_data_empty) 

Discussion

The singleton dispatch data object representing a zero-length memory region.

See Also