--- name: "dispatch_data_create" section: "3" platform: "linux" package: "libdispatch" version: "6.2.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "macos"] url: "https://new.carta.tech/dispatch_data_create" --- # dispatch\_data\_create(3) create and manipulate dispatch data objects ## NAME **dispatch\_data\_create**, **dispatch\_data\_create\_concat**, **dispatch\_data\_create\_subrange**, **dispatch\_data\_create\_map**, **dispatch\_data\_apply**, **dispatch\_data\_copy\_region**, **dispatch\_data\_get\_size** – create and manipulate dispatch data objects ## SYNOPSIS **#include \** *dispatch\_data\_t*\ **dispatch\_data\_create**(*const void\* buffer*, *size\_t size*, *dispatch\_queue\_t queue*, *dispatch\_block\_t destructor*); *dispatch\_data\_t*\ **dispatch\_data\_create\_concat**(*dispatch\_data\_t data1*, *dispatch\_data\_t data2*); *dispatch\_data\_t*\ **dispatch\_data\_create\_subrange**(*dispatch\_data\_t data*, *size\_t offset*, *size\_t length*); *dispatch\_data\_t*\ **dispatch\_data\_create\_map**(*dispatch\_data\_t data*, *const void \*\*buffer\_ptr*, *size\_t \*size\_ptr*); *bool*\ **dispatch\_data\_apply**(*dispatch\_data\_t data*, *bool (^applier)(dispatch\_data\_t, size\_t, const void \*, size\_t)*); *dispatch\_data\_t*\ **dispatch\_data\_copy\_region**(*dispatch\_data\_t data*, *size\_t location*, *size\_t \*offset\_ptr*); *size\_t*\ **dispatch\_data\_get\_size**(*dispatch\_data\_t data*); *dispatch\_data\_t* *dispatch\_data\_empty*; ## DESCRIPTION Dispatch data objects are opaque containers of bytes that represent one or more regions of memory. They are created either from memory buffers managed by the application or the system or from other dispatch data objects. Dispatch data objects are immutable and the memory regions they represent are required to remain unchanged for the lifetime of all data objects that reference them. Dispatch data objects avoid copying the represented memory as much as possible. Multiple data objects can represent the same memory regions or subsections thereof. ## CREATION The **dispatch\_data\_create**() function creates a new dispatch data object of given *size* from a *buffer*. The provided *destructor* block will be submitted to the specified *queue* when the object reaches the end of its lifecycle, indicating that the system no longer references the *buffer*. This allows the application to deallocate the associated storage. The *queue* argument is ignored if one of the following predefined destructors is passed: - DISPATCH\_DATA\_DESTRUCTOR\_FREE indicates that the provided buffer can be deallocated with [free(3)](/free/3.md) directly. - DISPATCH\_DATA\_DESTRUCTOR\_DEFAULT indicates that the provided buffer is not managed by the application and should be copied into memory managed and automatically deallocated by the system. The **dispatch\_data\_create\_concat**() function creates a new data object representing the concatenation of the memory regions represented by the provided data objects. The **dispatch\_data\_create\_subrange**() function creates a new data object representing the sub-region of the provided *data* object specified by the *offset* and *length* parameters. The **dispatch\_data\_create\_map**() function creates a new data object by mapping the memory represented by the provided *data* object as a single contiguous memory region (moving or copying memory as necessary). If the *buffer\_ptr* and *size\_ptr* references are not NULL, they are filled with the location and extent of the contiguous region, allowing direct read access to the mapped memory. These values are valid only as long as the newly created object has not been released. ## ACCESS The **dispatch\_data\_apply**() function provides read access to represented memory without requiring it to be mapped as a single contiguous region. It traverses the memory regions represented by the *data* argument in logical order, invokes the specified *applier* block for each region and returns a boolean indicating whether traversal completed successfully. The *applier* block is passed the following arguments for each memory region and returns a boolean indicating whether traversal should continue: - *dispatch\_data\_t rgn* data object representing the region - *size\_t offset* logical position of the region in *data* - *const void \*loc* memory location of the region - *size\_t size* extent of the region The *rgn* data object is released by the system when the *applier* block returns. The associated memory location *loc* is valid only as long as *rgn* has not been deallocated; if *loc* is needed outside of the *applier* block, the *rgn* object must be retained in the block. The **dispatch\_data\_copy\_region**() function finds the contiguous memory region containing the logical position specified by the *location* argument among the regions represented by the provided *data* object and returns a newly created copy of the data object representing that region. The variable specified by the *offset\_ptr* argument is filled with the logical position where the returned object starts in the *data* object. The **dispatch\_data\_get\_size**() function returns the logical size of the memory region or regions represented by the provided *data* object. ## EMPTY DATA OBJECT The *dispatch\_data\_empty* object is the global singleton object representing a zero-length memory region. It is a valid input to any dispatch\_data functions that take data object parameters. ## MEMORY MODEL Dispatch data objects are retained and released via calls to **dispatch\_retain**() and **dispatch\_release**(). Data objects passed as arguments to a dispatch data **create** or **copy** function can be released when the function returns. The newly created object holds implicit references to their constituent memory regions as necessary. The functions **dispatch\_data\_create\_map**() and **dispatch\_data\_apply**() return an interior pointer to represented memory that is only valid as long as an associated object has not been released. When Objective-C Automated Reference Counting is enabled, care needs to be taken if that object is held in a variable with automatic storage. It may need to be annotated with the objc\_precise\_lifetime attribute, or stored in a \_\_strong instance variable instead, to ensure that the object is not released prematurely before memory accesses via the interor pointer have been completed. ## SEE ALSO [dispatch(3)](/dispatch/3.md), [dispatch\_object(3)](/dispatch_object/3.md), [dispatch\_io\_read(3)](/dispatch_io_read/3.md)