[apple/libdispatch.git] / man / dispatch_data_create.3

.\" 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.
.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
Commit	Line	Data
e85f4437 A	1	.\" Copyright (c) 2010 Apple Inc. All rights reserved.
	2	.Dd December 1, 2010
	3	.Dt dispatch_data_create 3
	4	.Os Darwin
	5	.Sh NAME
	6	.Nm dispatch_data_create ,
	7	.Nm dispatch_data_create_concat ,
	8	.Nm dispatch_data_create_subrange ,
	9	.Nm dispatch_data_create_map ,
	10	.Nm dispatch_data_apply ,
	11	.Nm dispatch_data_copy_region ,
	12	.Nm dispatch_data_get_size
	13	.Nd create and manipulate dispatch data objects
	14	.Sh SYNOPSIS
	15	.Fd #include <dispatch/dispatch.h>
	16	.Ft dispatch_data_t
	17	.Fo dispatch_data_create
	18	.Fa "const void* buffer"
	19	.Fa "size_t size"
	20	.Fa "dispatch_queue_t queue"
	21	.Fa "dispatch_block_t destructor"
	22	.Fc
	23	.Ft dispatch_data_t
	24	.Fo dispatch_data_create_concat
	25	.Fa "dispatch_data_t data1"
	26	.Fa "dispatch_data_t data2"
	27	.Fc
	28	.Ft dispatch_data_t
	29	.Fo dispatch_data_create_subrange
	30	.Fa "dispatch_data_t data"
	31	.Fa "size_t offset"
	32	.Fa "size_t length"
	33	.Fc
	34	.Ft dispatch_data_t
	35	.Fo dispatch_data_create_map
	36	.Fa "dispatch_data_t data"
	37	.Fa "const void **buffer_ptr"
	38	.Fa "size_t *size_ptr"
	39	.Fc
	40	.Ft bool
	41	.Fo dispatch_data_apply
	42	.Fa "dispatch_data_t data"
	43	.Fa "bool (^applier)(dispatch_data_t, size_t, const void *, size_t)"
	44	.Fc
	45	.Ft dispatch_data_t
	46	.Fo dispatch_data_copy_region
	47	.Fa "dispatch_data_t data"
	48	.Fa "size_t location"
	49	.Fa "size_t *offset_ptr"
	50	.Fc
	51	.Ft size_t
	52	.Fo dispatch_data_get_size
	53	.Fa "dispatch_data_t data"
	54	.Fc
	55	.Vt dispatch_data_t dispatch_data_empty ;
	56	.Sh DESCRIPTION
	57	Dispatch data objects are opaque containers of bytes that represent one or more
	58	regions of memory. They are created either from memory buffers managed by the
	59	application or the system or from other dispatch data objects. Dispatch data
	60	objects are immutable and the memory regions they represent are required to
	61	remain unchanged for the lifetime of all data objects that reference them.
	62	Dispatch data objects avoid copying the represented memory as much as possible.
	63	Multiple data objects can represent the same memory regions or subsections
	64	thereof.
65	.Sh CREATION
66	The
67	.Fn dispatch_data_create
68	function creates a new dispatch data object of given
69	.Fa size
70	from a
71	.Fa buffer .
72	The provided
73	.Fa destructor
74	block will be submitted to the specified
75	.Fa queue
76	when the object reaches the end of its lifecycle, indicating that the system no
77	longer references the
78	.Fa buffer .
79	This allows the application to deallocate
80	the associated storage. The
81	.Fa queue
82	argument is ignored if one of the following predefined destructors is passed:
83	.Bl -tag -width DISPATCH_DATA_DESTRUCTOR_DEFAULT -compact -offset indent
84	.It DISPATCH_DATA_DESTRUCTOR_FREE
85	indicates that the provided buffer can be deallocated with
86	.Xr free 3
87	directly.
88	.It DISPATCH_DATA_DESTRUCTOR_DEFAULT
89	indicates that the provided buffer is not managed by the application and should
90	be copied into memory managed and automatically deallocated by the system.
91	.El
92	.Pp
93	The
94	.Fn dispatch_data_create_concat
95	function creates a new data object representing the concatenation of the memory
96	regions represented by the provided data objects.
97	.Pp
98	The
99	.Fn dispatch_data_create_subrange
100	function creates a new data object representing the sub-region of the provided
101	.Fa data
102	object specified by the
103	.Fa offset
104	and
105	.Fa length
106	parameters.
107	.Pp
108	The
109	.Fn dispatch_data_create_map
110	function creates a new data object by mapping the memory represented by the
111	provided
112	.Fa data
113	object as a single contiguous memory region (moving or copying memory as
114	necessary). If the
115	.Fa buffer_ptr
116	and
117	.Fa size_ptr
118	references are not
119	.Dv NULL ,
120	they are filled with the location and extent of the contiguous region, allowing
121	direct read access to the mapped memory. These values are valid only as long as
122	the newly created object has not been released.
123	.Sh ACCESS
124	The
125	.Fn dispatch_data_apply
126	function provides read access to represented memory without requiring it to be
127	mapped as a single contiguous region. It traverses the memory regions
128	represented by the
129	.Fa data
130	argument in logical order, invokes the specified
131	.Fa applier
132	block for each region and returns a boolean indicating whether traversal
133	completed successfully. The
134	.Fa applier
135	block is passed the following arguments for each memory region and returns a
136	boolean indicating whether traversal should continue:
137	.Bl -tag -width "dispatch_data_t rgn" -compact -offset indent
138	.It Fa "dispatch_data_t rgn"
139	data object representing the region
140	.It Fa "size_t offset"
141	logical position of the region in
142	.Fa data
143	.It Vt "const void *loc"
144	memory location of the region
145	.It Vt "size_t size"
146	extent of the region
147	.El
148	The
149	.Fa rgn
150	data object is released by the system when the
151	.Fa applier
152	block returns.
153	The associated memory location
154	.Fa loc
155	is valid only as long as
156	.Fa rgn
157	has not been deallocated; if
158	.Fa loc
159	is needed outside of the
160	.Fa applier
161	block, the
162	.Fa rgn
163	object must be retained in the block.
164	.Pp
165	The
166	.Fn dispatch_data_copy_region
167	function finds the contiguous memory region containing the logical position
168	specified by the
169	.Fa location
170	argument among the regions represented by the provided
171	.Fa data
172	object and returns a newly created copy of the data object representing that
173	region. The variable specified by the
174	.Fa offset_ptr
175	argument is filled with the logical position where the returned object starts
176	in the
177	.Fa data
178	object.
179	.Pp
180	The
181	.Fn dispatch_data_get_size
182	function returns the logical size of the memory region or regions represented
183	by the provided
184	.Fa data
185	object.
186	.Sh EMPTY DATA OBJECT
187	The
188	.Vt dispatch_data_empty
189	object is the global singleton object representing a zero-length memory region.
190	It is a valid input to any dispatch_data functions that take data object
191	parameters.
192	.Sh MEMORY MODEL
193	Dispatch data objects are retained and released via calls to
194	.Fn dispatch_retain
195	and
196	.Fn dispatch_release .
197	Data objects passed as arguments to a dispatch data
198	.Sy create
199	or
200	.Sy copy
201	function can be released when the function returns. The newly created object
202	holds implicit references to their constituent memory regions as necessary.
c093abd6 A	203	.Pp
	204	The functions
	205	.Fn dispatch_data_create_map
	206	and
	207	.Fn dispatch_data_apply
	208	return an interior pointer to represented memory that is only valid as long as
	209	an associated object has not been released. When Objective-C Automated
	210	Reference Counting is enabled, care needs to be taken if that object is held in
	211	a variable with automatic storage. It may need to be annotated with the
	212	.Li objc_precise_lifetime
	213	attribute, or stored in a
	214	.Li __strong
	215	instance variable instead, to ensure that the object is not released
	216	prematurely before memory accesses via the interor pointer have been completed.
e85f4437 A	217	.Sh SEE ALSO
	218	.Xr dispatch 3 ,
	219	.Xr dispatch_object 3 ,
	220	.Xr dispatch_io_read 3