afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
221 lines
6.4 KiB
Groff
221 lines
6.4 KiB
Groff
.\" 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
|