.\" Copyright (c) 2010-2012 Apple Inc. All rights reserved.
.Dd December 1, 2010
.Dt dispatch_data_create 3
.Os Darwin
.Sh NAME
.Nm dispatch_data_create ,
.Nm dispatch_data_create_concat ,
.Nm dispatch_data_create_subrange ,
.Nm dispatch_data_create_map ,
.Nm dispatch_data_apply ,
.Nm dispatch_data_copy_region ,
.Nm dispatch_data_get_size
.Nd create and manipulate dispatch data objects
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft dispatch_data_t
.Fo dispatch_data_create
.Fa "const void* buffer"
.Fa "size_t size"
.Fa "dispatch_queue_t queue"
.Fa "dispatch_block_t destructor"
.Fc
.Ft dispatch_data_t
.Fo dispatch_data_create_concat
.Fa "dispatch_data_t data1"
.Fa "dispatch_data_t data2"
.Fc
.Ft dispatch_data_t
.Fo dispatch_data_create_subrange
.Fa "dispatch_data_t data"
.Fa "size_t offset"
.Fa "size_t length"
.Fc
.Ft dispatch_data_t
.Fo dispatch_data_create_map
.Fa "dispatch_data_t data"
.Fa "const void **buffer_ptr"
.Fa "size_t *size_ptr"
.Fc
.Ft bool
.Fo dispatch_data_apply
.Fa "dispatch_data_t data"
.Fa "bool (^applier)(dispatch_data_t, size_t, const void *, size_t)"
.Fc
.Ft dispatch_data_t
.Fo dispatch_data_copy_region
.Fa "dispatch_data_t data"
.Fa "size_t location"
.Fa "size_t *offset_ptr"
.Fc
.Ft size_t
.Fo dispatch_data_get_size
.Fa "dispatch_data_t data"
.Fc
.Vt dispatch_data_t dispatch_data_empty ;
.Sh 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.
.Sh CREATION
The
.Fn dispatch_data_create
function creates a new dispatch data object of given
.Fa size
from a
.Fa buffer .
The provided
.Fa destructor
block will be submitted to the specified
.Fa queue
when the object reaches the end of its lifecycle, indicating that the system no
longer references the
.Fa buffer .
This allows the application to deallocate
the associated storage. The
.Fa queue
argument is ignored if one of the following predefined destructors is passed:
.Bl -tag -width DISPATCH_DATA_DESTRUCTOR_DEFAULT -compact -offset indent
.It DISPATCH_DATA_DESTRUCTOR_FREE
indicates that the provided buffer can be deallocated with
.Xr free 3
directly.
.It 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.
.El
.Pp
The
.Fn dispatch_data_create_concat
function creates a new data object representing the concatenation of the memory
regions represented by the provided data objects.
.Pp
The
.Fn dispatch_data_create_subrange
function creates a new data object representing the sub-region of the provided
.Fa data
object specified by the
.Fa offset
and
.Fa length
parameters.
.Pp
The
.Fn dispatch_data_create_map
function creates a new data object by mapping the memory represented by the
provided
.Fa data
object as a single contiguous memory region (moving or copying memory as
necessary). If the
.Fa buffer_ptr
and
.Fa size_ptr
references are not
.Dv 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.
.Sh ACCESS
The
.Fn 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
.Fa data
argument in logical order, invokes the specified
.Fa applier
block for each region and returns a boolean indicating whether traversal
completed successfully. The
.Fa applier
block is passed the following arguments for each memory region and returns a
boolean indicating whether traversal should continue:
.Bl -tag -width "dispatch_data_t rgn" -compact -offset indent
.It Fa "dispatch_data_t rgn"
data object representing the region
.It Fa "size_t offset"
logical position of the region in
.Fa data
.It Vt "const void *loc"
memory location of the region
.It Vt "size_t size"
extent of the region
.El
The
.Fa rgn
data object is released by the system when the
.Fa applier
block returns.
The associated memory location
.Fa loc
is valid only as long as
.Fa rgn
has not been deallocated; if
.Fa loc
is needed outside of the
.Fa applier
block, the
.Fa rgn
object must be retained in the block.
.Pp
The
.Fn dispatch_data_copy_region
function finds the contiguous memory region containing the logical position
specified by the
.Fa location
argument among the regions represented by the provided
.Fa data
object and returns a newly created copy of the data object representing that
region. The variable specified by the
.Fa offset_ptr
argument is filled with the logical position where the returned object starts
in the
.Fa data
object.
.Pp
The
.Fn dispatch_data_get_size
function returns the logical size of the memory region or regions represented
by the provided
.Fa data
object.
.Sh EMPTY DATA OBJECT
The
.Vt 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.
.Sh MEMORY MODEL
Dispatch data objects are retained and released via calls to
.Fn dispatch_retain
and
.Fn dispatch_release .
Data objects passed as arguments to a dispatch data
.Sy create
or
.Sy copy
function can be released when the function returns. The newly created object
holds implicit references to their constituent memory regions as necessary.
.Pp
The functions
.Fn dispatch_data_create_map
and
.Fn 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
.Li objc_precise_lifetime
attribute, or stored in a
.Li __strong
instance variable instead, to ensure that the object is not released
prematurely before memory accesses via the interor pointer have been completed.
.Sh SEE ALSO
.Xr dispatch 3 ,
.Xr dispatch_object 3 ,
.Xr dispatch_io_read 3