1/*
2 * Copyright (c) 2009-2013 Apple Inc. All rights reserved.
3 *
4 * @APPLE_APACHE_LICENSE_HEADER_START@
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 * @APPLE_APACHE_LICENSE_HEADER_END@
19 */
20
21#ifndef __DISPATCH_DATA__
22#define __DISPATCH_DATA__
23
24#ifndef __DISPATCH_INDIRECT__
25#error "Please #include <dispatch/dispatch.h> instead of this file directly."
26#include <dispatch/base.h> // for HeaderDoc
27#endif
28
29DISPATCH_ASSUME_NONNULL_BEGIN
30DISPATCH_ASSUME_ABI_SINGLE_BEGIN
31
32__BEGIN_DECLS
33
34/*! @header
35 * Dispatch data objects describe contiguous or sparse regions of memory that
36 * may be managed by the system or by the application.
37 * Dispatch data objects are immutable, any direct access to memory regions
38 * represented by dispatch objects must not modify that memory.
39 */
40
41/*!
42 * @typedef dispatch_data_t
43 * A dispatch object representing memory regions.
44 */
45DISPATCH_DATA_DECL_SWIFT(dispatch_data, __DispatchData);
46
47/*!
48 * @var dispatch_data_empty
49 * @discussion The singleton dispatch data object representing a zero-length
50 * memory region.
51 */
52#define dispatch_data_empty \
53 DISPATCH_GLOBAL_OBJECT(dispatch_data_t, _dispatch_data_empty)
54API_AVAILABLE(macos(10.7), ios(5.0))
55DISPATCH_EXPORT struct dispatch_data_s _dispatch_data_empty;
56
57/*!
58 * @const DISPATCH_DATA_DESTRUCTOR_DEFAULT
59 * @discussion The default destructor for dispatch data objects.
60 * Used at data object creation to indicate that the supplied buffer should
61 * be copied into internal storage managed by the system.
62 */
63#define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL
64
65#ifdef __BLOCKS__
66/*! @parseOnly */
67#define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \
68 DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_##name
69#else
70#define DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(name) \
71 DISPATCH_EXPORT const dispatch_function_t \
72 _dispatch_data_destructor_##name
73#endif /* __BLOCKS__ */
74
75/*!
76 * @const DISPATCH_DATA_DESTRUCTOR_FREE
77 * @discussion The destructor for dispatch data objects created from a malloc'd
78 * buffer. Used at data object creation to indicate that the supplied buffer
79 * was allocated by the malloc() family and should be destroyed with free(3).
80 */
81#define DISPATCH_DATA_DESTRUCTOR_FREE (_dispatch_data_destructor_free)
82API_AVAILABLE(macos(10.7), ios(5.0))
83DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift")
84DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(free);
85
86/*!
87 * @const DISPATCH_DATA_DESTRUCTOR_MUNMAP
88 * @discussion The destructor for dispatch data objects that have been created
89 * from buffers that require deallocation with munmap(2).
90 */
91#define DISPATCH_DATA_DESTRUCTOR_MUNMAP (_dispatch_data_destructor_munmap)
92API_AVAILABLE(macos(10.9), ios(7.0))
93DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift")
94DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(munmap);
95
96#ifdef __BLOCKS__
97/*!
98 * @function dispatch_data_create
99 * Creates a dispatch data object from the given contiguous buffer of memory. If
100 * a non-default destructor is provided, ownership of the buffer remains with
101 * the caller (i.e. the bytes will not be copied). The last release of the data
102 * object will result in the invocation of the specified destructor on the
103 * specified queue to free the buffer.
104 *
105 * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will
106 * be freed via free(3) and the queue argument ignored.
107 *
108 * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object
109 * creation will copy the buffer into internal memory managed by the system.
110 *
111 * @param buffer A contiguous buffer of data.
112 * @param size The size of the contiguous buffer of data.
113 * @param queue The queue to which the destructor should be submitted.
114 * @param destructor The destructor responsible for freeing the data when it
115 * is no longer needed.
116 * @result A newly created dispatch data object.
117 */
118API_AVAILABLE(macos(10.7), ios(5.0))
119DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
120DISPATCH_SWIFT_UNAVAILABLE("Use DispatchData.init(bytes:)")
121dispatch_data_t
122dispatch_data_create(const void *DISPATCH_SIZED_BY(size) buffer,
123 size_t size,
124 dispatch_queue_t _Nullable queue,
125 dispatch_block_t _Nullable destructor);
126#endif /* __BLOCKS__ */
127
128/*!
129 * @function dispatch_data_get_size
130 * Returns the logical size of the memory region(s) represented by the specified
131 * dispatch data object.
132 *
133 * @param data The dispatch data object to query.
134 * @result The number of bytes represented by the data object.
135 */
136API_AVAILABLE(macos(10.7), ios(5.0))
137DISPATCH_EXPORT DISPATCH_PURE DISPATCH_NONNULL1 DISPATCH_NOTHROW
138DISPATCH_REFINED_FOR_SWIFT
139size_t
140dispatch_data_get_size(dispatch_data_t data);
141
142/*!
143 * @function dispatch_data_create_map
144 * Maps the memory represented by the specified dispatch data object as a single
145 * contiguous memory region and returns a new data object representing it.
146 * If non-NULL references to a pointer and a size variable are provided, they
147 * are filled with the location and extent of that region. These allow direct
148 * read access to the represented memory, but are only valid until the returned
149 * object is released. Under ARC, if that object is held in a variable with
150 * automatic storage, care needs to be taken to ensure that it is not released
151 * by the compiler before memory access via the pointer has been completed.
152 *
153 * @param data The dispatch data object to map.
154 * @param buffer_ptr A pointer to a pointer variable to be filled with the
155 * location of the mapped contiguous memory region, or
156 * NULL.
157 * @param size_ptr A pointer to a size_t variable to be filled with the
158 * size of the mapped contiguous memory region, or NULL.
159 * @result A newly created dispatch data object.
160 */
161API_AVAILABLE(macos(10.7), ios(5.0))
162DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED
163DISPATCH_WARN_RESULT DISPATCH_NOTHROW
164DISPATCH_REFINED_FOR_SWIFT
165dispatch_data_t
166dispatch_data_create_map(dispatch_data_t data,
167 const void *_Nullable DISPATCH_SIZED_BY(*size_ptr) *_Nullable buffer_ptr,
168 size_t *_Nullable size_ptr);
169
170/*!
171 * @function dispatch_data_create_concat
172 * Returns a new dispatch data object representing the concatenation of the
173 * specified data objects. Those objects may be released by the application
174 * after the call returns (however, the system might not deallocate the memory
175 * region(s) described by them until the newly created object has also been
176 * released).
177 *
178 * @param data1 The data object representing the region(s) of memory to place
179 * at the beginning of the newly created object.
180 * @param data2 The data object representing the region(s) of memory to place
181 * at the end of the newly created object.
182 * @result A newly created object representing the concatenation of the
183 * data1 and data2 objects.
184 */
185API_AVAILABLE(macos(10.7), ios(5.0))
186DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED
187DISPATCH_WARN_RESULT DISPATCH_NOTHROW
188DISPATCH_REFINED_FOR_SWIFT
189dispatch_data_t
190dispatch_data_create_concat(dispatch_data_t data1, dispatch_data_t data2);
191
192/*!
193 * @function dispatch_data_create_subrange
194 * Returns a new dispatch data object representing a subrange of the specified
195 * data object, which may be released by the application after the call returns
196 * (however, the system might not deallocate the memory region(s) described by
197 * that object until the newly created object has also been released).
198 *
199 * @param data The data object representing the region(s) of memory to
200 * create a subrange of.
201 * @param offset The offset into the data object where the subrange
202 * starts.
203 * @param length The length of the range.
204 * @result A newly created object representing the specified
205 * subrange of the data object.
206 */
207API_AVAILABLE(macos(10.7), ios(5.0))
208DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_RETURNS_RETAINED
209DISPATCH_WARN_RESULT DISPATCH_NOTHROW
210DISPATCH_REFINED_FOR_SWIFT
211dispatch_data_t
212dispatch_data_create_subrange(dispatch_data_t data,
213 size_t offset,
214 size_t length);
215
216#ifdef __BLOCKS__
217/*!
218 * @typedef dispatch_data_applier_t
219 * A block to be invoked for every contiguous memory region in a data object.
220 *
221 * @param region A data object representing the current region.
222 * @param offset The logical offset of the current region to the start
223 * of the data object.
224 * @param buffer The location of the memory for the current region.
225 * @param size The size of the memory for the current region.
226 * @result A Boolean indicating whether traversal should continue.
227 */
228DISPATCH_SWIFT_UNAVAILABLE("Unavailable in Swift")
229typedef bool (^dispatch_data_applier_t)(dispatch_data_t region,
230 size_t offset,
231 const void *DISPATCH_SIZED_BY(size) buffer,
232 size_t size);
233
234/*!
235 * @function dispatch_data_apply
236 * Traverse the memory regions represented by the specified dispatch data object
237 * in logical order and invoke the specified block once for every contiguous
238 * memory region encountered.
239 *
240 * Each invocation of the block is passed a data object representing the current
241 * region and its logical offset, along with the memory location and extent of
242 * the region. These allow direct read access to the memory region, but are only
243 * valid until the passed-in region object is released. Note that the region
244 * object is released by the system when the block returns, it is the
245 * responsibility of the application to retain it if the region object or the
246 * associated memory location are needed after the block returns.
247 *
248 * @param data The data object to traverse.
249 * @param applier The block to be invoked for every contiguous memory
250 * region in the data object.
251 * @result A Boolean indicating whether traversal completed
252 * successfully.
253 */
254API_AVAILABLE(macos(10.7), ios(5.0))
255DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
256DISPATCH_REFINED_FOR_SWIFT
257bool
258dispatch_data_apply(dispatch_data_t data,
259 DISPATCH_NOESCAPE dispatch_data_applier_t applier);
260#endif /* __BLOCKS__ */
261
262/*!
263 * @function dispatch_data_copy_region
264 * Finds the contiguous memory region containing the specified location among
265 * the regions represented by the specified object and returns a copy of the
266 * internal dispatch data object representing that region along with its logical
267 * offset in the specified object.
268 *
269 * @param data The dispatch data object to query.
270 * @param location The logical position in the data object to query.
271 * @param offset_ptr A pointer to a size_t variable to be filled with the
272 * logical offset of the returned region object to the
273 * start of the queried data object.
274 * @result A newly created dispatch data object.
275 */
276API_AVAILABLE(macos(10.7), ios(5.0))
277DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED
278DISPATCH_WARN_RESULT DISPATCH_NOTHROW
279DISPATCH_REFINED_FOR_SWIFT
280dispatch_data_t
281dispatch_data_copy_region(dispatch_data_t data,
282 size_t location,
283 size_t *offset_ptr);
284
285__END_DECLS
286
287DISPATCH_ASSUME_ABI_SINGLE_END
288DISPATCH_ASSUME_NONNULL_END
289
290#endif /* __DISPATCH_DATA__ */