--- /dev/null
+.\" Copyright (c) 2010 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.
+.Sh SEE ALSO
+.Xr dispatch 3 ,
+.Xr dispatch_object 3 ,
+.Xr dispatch_io_read 3
projects / apple / libdispatch.git / blobdiff