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 /* 22 * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch 23 * which are subject to change in future releases of Mac OS X. Any applications 24 * relying on these interfaces WILL break. 25 */ 26 27 #ifndef __DISPATCH_IO_PRIVATE__ 28 #define __DISPATCH_IO_PRIVATE__ 29 30 #ifndef __DISPATCH_INDIRECT__ 31 #error "Please #include <dispatch/dispatch.h> instead of this file directly." 32 #include <dispatch/base.h> // for HeaderDoc 33 #endif 34 35 __BEGIN_DECLS 36 37 /*! 38 * @function dispatch_read_f 39 * Schedule a read operation for asynchronous execution on the specified file 40 * descriptor. The specified handler is enqueued with the data read from the 41 * file descriptor when the operation has completed or an error occurs. 42 * 43 * The data object passed to the handler will be automatically released by the 44 * system when the handler returns. It is the responsibility of the application 45 * to retain, concatenate or copy the data object if it is needed after the 46 * handler returns. 47 * 48 * The data object passed to the handler will only contain as much data as is 49 * currently available from the file descriptor (up to the specified length). 50 * 51 * If an unrecoverable error occurs on the file descriptor, the handler will be 52 * enqueued with the appropriate error code along with a data object of any data 53 * that could be read successfully. 54 * 55 * An invocation of the handler with an error code of zero and an empty data 56 * object indicates that EOF was reached. 57 * 58 * The system takes control of the file descriptor until the handler is 59 * enqueued, and during this time file descriptor flags such as O_NONBLOCK will 60 * be modified by the system on behalf of the application. It is an error for 61 * the application to modify a file descriptor directly while it is under the 62 * control of the system, but it may create additional dispatch I/O convenience 63 * operations or dispatch I/O channels associated with that file descriptor. 64 * 65 * @param fd The file descriptor from which to read the data. 66 * @param length The length of data to read from the file descriptor, 67 * or SIZE_MAX to indicate that all of the data currently 68 * available from the file descriptor should be read. 69 * @param queue The dispatch queue to which the handler should be 70 * submitted. 71 * @param context The application-defined context parameter to pass to 72 * the handler function. 73 * @param handler The handler to enqueue when data is ready to be 74 * delivered. 75 * param context Application-defined context parameter. 76 * param data The data read from the file descriptor. 77 * param error An errno condition for the read operation or 78 * zero if the read was successful. 79 */ 80 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 81 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NONNULL5 DISPATCH_NOTHROW 82 void 83 dispatch_read_f(dispatch_fd_t fd, 84 size_t length, 85 dispatch_queue_t queue, 86 void *context, 87 void (*handler)(void *context, dispatch_data_t data, int error)); 88 89 /*! 90 * @function dispatch_write_f 91 * Schedule a write operation for asynchronous execution on the specified file 92 * descriptor. The specified handler is enqueued when the operation has 93 * completed or an error occurs. 94 * 95 * If an unrecoverable error occurs on the file descriptor, the handler will be 96 * enqueued with the appropriate error code along with the data that could not 97 * be successfully written. 98 * 99 * An invocation of the handler with an error code of zero indicates that the 100 * data was fully written to the channel. 101 * 102 * The system takes control of the file descriptor until the handler is 103 * enqueued, and during this time file descriptor flags such as O_NONBLOCK will 104 * be modified by the system on behalf of the application. It is an error for 105 * the application to modify a file descriptor directly while it is under the 106 * control of the system, but it may create additional dispatch I/O convenience 107 * operations or dispatch I/O channels associated with that file descriptor. 108 * 109 * @param fd The file descriptor to which to write the data. 110 * @param data The data object to write to the file descriptor. 111 * @param queue The dispatch queue to which the handler should be 112 * submitted. 113 * @param context The application-defined context parameter to pass to 114 * the handler function. 115 * @param handler The handler to enqueue when the data has been written. 116 * param context Application-defined context parameter. 117 * param data The data that could not be written to the I/O 118 * channel, or NULL. 119 * param error An errno condition for the write operation or 120 * zero if the write was successful. 121 */ 122 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 123 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL5 124 DISPATCH_NOTHROW 125 void 126 dispatch_write_f(dispatch_fd_t fd, 127 dispatch_data_t data, 128 dispatch_queue_t queue, 129 void *context, 130 void (*handler)(void *context, dispatch_data_t data, int error)); 131 132 /*! 133 * @function dispatch_io_create_f 134 * Create a dispatch I/O channel associated with a file descriptor. The system 135 * takes control of the file descriptor until the channel is closed, an error 136 * occurs on the file descriptor or all references to the channel are released. 137 * At that time the specified cleanup handler will be enqueued and control over 138 * the file descriptor relinquished. 139 * 140 * While a file descriptor is under the control of a dispatch I/O channel, file 141 * descriptor flags such as O_NONBLOCK will be modified by the system on behalf 142 * of the application. It is an error for the application to modify a file 143 * descriptor directly while it is under the control of a dispatch I/O channel, 144 * but it may create additional channels associated with that file descriptor. 145 * 146 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 147 * or DISPATCH_IO_RANDOM). 148 * @param fd The file descriptor to associate with the I/O channel. 149 * @param queue The dispatch queue to which the handler should be submitted. 150 * @param context The application-defined context parameter to pass to 151 * the cleanup handler function. 152 * @param cleanup_handler The handler to enqueue when the system 153 * relinquishes control over the file descriptor. 154 * param context Application-defined context parameter. 155 * param error An errno condition if control is relinquished 156 * because channel creation failed, zero otherwise. 157 * @result The newly created dispatch I/O channel or NULL if an error 158 * occurred (invalid type specified). 159 */ 160 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 161 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT 162 DISPATCH_NOTHROW 163 dispatch_io_t 164 dispatch_io_create_f(dispatch_io_type_t type, 165 dispatch_fd_t fd, 166 dispatch_queue_t queue, 167 void *context, 168 void (*cleanup_handler)(void *context, int error)); 169 170 /*! 171 * @function dispatch_io_create_with_path_f 172 * Create a dispatch I/O channel associated with a path name. The specified 173 * path, oflag and mode parameters will be passed to open(2) when the first I/O 174 * operation on the channel is ready to execute and the resulting file 175 * descriptor will remain open and under the control of the system until the 176 * channel is closed, an error occurs on the file descriptor or all references 177 * to the channel are released. At that time the file descriptor will be closed 178 * and the specified cleanup handler will be enqueued. 179 * 180 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 181 * or DISPATCH_IO_RANDOM). 182 * @param path The absolute path to associate with the I/O channel. 183 * @param oflag The flags to pass to open(2) when opening the file at 184 * path. 185 * @param mode The mode to pass to open(2) when creating the file at 186 * path (i.e. with flag O_CREAT), zero otherwise. 187 * @param queue The dispatch queue to which the handler should be 188 * submitted. 189 * @param context The application-defined context parameter to pass to 190 * the cleanup handler function. 191 * @param cleanup_handler The handler to enqueue when the system 192 * has closed the file at path. 193 * param context Application-defined context parameter. 194 * param error An errno condition if control is relinquished 195 * because channel creation or opening of the 196 * specified file failed, zero otherwise. 197 * @result The newly created dispatch I/O channel or NULL if an error 198 * occurred (invalid type or non-absolute path specified). 199 */ 200 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 201 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED 202 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 203 dispatch_io_t 204 dispatch_io_create_with_path_f(dispatch_io_type_t type, 205 const char *path, int oflag, mode_t mode, 206 dispatch_queue_t queue, 207 void *context, 208 void (*cleanup_handler)(void *context, int error)); 209 210 /*! 211 * @function dispatch_io_create_with_io_f 212 * Create a new dispatch I/O channel from an existing dispatch I/O channel. 213 * The new channel inherits the file descriptor or path name associated with 214 * the existing channel, but not its channel type or policies. 215 * 216 * If the existing channel is associated with a file descriptor, control by the 217 * system over that file descriptor is extended until the new channel is also 218 * closed, an error occurs on the file descriptor, or all references to both 219 * channels are released. At that time the specified cleanup handler will be 220 * enqueued and control over the file descriptor relinquished. 221 * 222 * While a file descriptor is under the control of a dispatch I/O channel, file 223 * descriptor flags such as O_NONBLOCK will be modified by the system on behalf 224 * of the application. It is an error for the application to modify a file 225 * descriptor directly while it is under the control of a dispatch I/O channel, 226 * but it may create additional channels associated with that file descriptor. 227 * 228 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 229 * or DISPATCH_IO_RANDOM). 230 * @param io The existing channel to create the new I/O channel from. 231 * @param queue The dispatch queue to which the handler should be submitted. 232 * @param context The application-defined context parameter to pass to 233 * the cleanup handler function. 234 * @param cleanup_handler The handler to enqueue when the system 235 * relinquishes control over the file descriptor 236 * (resp. closes the file at path) associated with 237 * the existing channel. 238 * param context Application-defined context parameter. 239 * param error An errno condition if control is relinquished 240 * because channel creation failed, zero otherwise. 241 * @result The newly created dispatch I/O channel or NULL if an error 242 * occurred (invalid type specified). 243 */ 244 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 245 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED 246 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 247 dispatch_io_t 248 dispatch_io_create_with_io_f(dispatch_io_type_t type, 249 dispatch_io_t io, 250 dispatch_queue_t queue, 251 void *context, 252 void (*cleanup_handler)(void *context, int error)); 253 254 /*! 255 * @typedef dispatch_io_handler_function_t 256 * The prototype of I/O handler functions for dispatch I/O operations. 257 * 258 * @param context Application-defined context parameter. 259 * @param done A flag indicating whether the operation is complete. 260 * @param data The data object to be handled. 261 * @param error An errno condition for the operation. 262 */ 263 typedef void (*dispatch_io_handler_function_t)(void *context, bool done, 264 dispatch_data_t data, int error); 265 266 /*! 267 * @function dispatch_io_read_f 268 * Schedule a read operation for asynchronous execution on the specified I/O 269 * channel. The I/O handler is enqueued one or more times depending on the 270 * general load of the system and the policy specified on the I/O channel. 271 * 272 * Any data read from the channel is described by the dispatch data object 273 * passed to the I/O handler. This object will be automatically released by the 274 * system when the I/O handler returns. It is the responsibility of the 275 * application to retain, concatenate or copy the data object if it is needed 276 * after the I/O handler returns. 277 * 278 * Dispatch I/O handlers are not reentrant. The system will ensure that no new 279 * I/O handler instance is invoked until the previously enqueued handler 280 * function has returned. 281 * 282 * An invocation of the I/O handler with the done flag set indicates that the 283 * read operation is complete and that the handler will not be enqueued again. 284 * 285 * If an unrecoverable error occurs on the I/O channel's underlying file 286 * descriptor, the I/O handler will be enqueued with the done flag set, the 287 * appropriate error code and a NULL data object. 288 * 289 * An invocation of the I/O handler with the done flag set, an error code of 290 * zero and an empty data object indicates that EOF was reached. 291 * 292 * @param channel The dispatch I/O channel from which to read the data. 293 * @param offset The offset relative to the channel position from which 294 * to start reading (only for DISPATCH_IO_RANDOM). 295 * @param length The length of data to read from the I/O channel, or 296 * SIZE_MAX to indicate that data should be read until EOF 297 * is reached. 298 * @param queue The dispatch queue to which the I/O handler should be 299 * submitted. 300 * @param context The application-defined context parameter to pass to 301 * the handler function. 302 * @param io_handler The I/O handler to enqueue when data is ready to be 303 * delivered. 304 * param context Application-defined context parameter. 305 * param done A flag indicating whether the operation is complete. 306 * param data An object with the data most recently read from the 307 * I/O channel as part of this read operation, or NULL. 308 * param error An errno condition for the read operation or zero if 309 * the read was successful. 310 */ 311 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 312 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL6 313 DISPATCH_NOTHROW 314 void 315 dispatch_io_read_f(dispatch_io_t channel, 316 off_t offset, 317 size_t length, 318 dispatch_queue_t queue, 319 void *context, 320 dispatch_io_handler_function_t io_handler); 321 322 /*! 323 * @function dispatch_io_write_f 324 * Schedule a write operation for asynchronous execution on the specified I/O 325 * channel. The I/O handler is enqueued one or more times depending on the 326 * general load of the system and the policy specified on the I/O channel. 327 * 328 * Any data remaining to be written to the I/O channel is described by the 329 * dispatch data object passed to the I/O handler. This object will be 330 * automatically released by the system when the I/O handler returns. It is the 331 * responsibility of the application to retain, concatenate or copy the data 332 * object if it is needed after the I/O handler returns. 333 * 334 * Dispatch I/O handlers are not reentrant. The system will ensure that no new 335 * I/O handler instance is invoked until the previously enqueued handler 336 * function has returned. 337 * 338 * An invocation of the I/O handler with the done flag set indicates that the 339 * write operation is complete and that the handler will not be enqueued again. 340 * 341 * If an unrecoverable error occurs on the I/O channel's underlying file 342 * descriptor, the I/O handler will be enqueued with the done flag set, the 343 * appropriate error code and an object containing the data that could not be 344 * written. 345 * 346 * An invocation of the I/O handler with the done flag set and an error code of 347 * zero indicates that the data was fully written to the channel. 348 * 349 * @param channel The dispatch I/O channel on which to write the data. 350 * @param offset The offset relative to the channel position from which 351 * to start writing (only for DISPATCH_IO_RANDOM). 352 * @param data The data to write to the I/O channel. The data object 353 * will be retained by the system until the write operation 354 * is complete. 355 * @param queue The dispatch queue to which the I/O handler should be 356 * submitted. 357 * @param context The application-defined context parameter to pass to 358 * the handler function. 359 * @param io_handler The I/O handler to enqueue when data has been delivered. 360 * param context Application-defined context parameter. 361 * param done A flag indicating whether the operation is complete. 362 * param data An object of the data remaining to be 363 * written to the I/O channel as part of this write 364 * operation, or NULL. 365 * param error An errno condition for the write operation or zero 366 * if the write was successful. 367 */ 368 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 369 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4 370 DISPATCH_NONNULL6 DISPATCH_NOTHROW 371 void 372 dispatch_io_write_f(dispatch_io_t channel, 373 off_t offset, 374 dispatch_data_t data, 375 dispatch_queue_t queue, 376 void *context, 377 dispatch_io_handler_function_t io_handler); 378 379 /*! 380 * @function dispatch_io_barrier_f 381 * Schedule a barrier operation on the specified I/O channel; all previously 382 * scheduled operations on the channel will complete before the provided 383 * barrier function is enqueued onto the global queue determined by the 384 * channel's target queue, and no subsequently scheduled operations will start 385 * until the barrier function has returned. 386 * 387 * If multiple channels are associated with the same file descriptor, a barrier 388 * operation scheduled on any of these channels will act as a barrier across all 389 * channels in question, i.e. all previously scheduled operations on any of the 390 * channels will complete before the barrier function is enqueued, and no 391 * operations subsequently scheduled on any of the channels will start until the 392 * barrier function has returned. 393 * 394 * While the barrier function is running, it may safely operate on the channel's 395 * underlying file descriptor with fsync(2), lseek(2) etc. (but not close(2)). 396 * 397 * @param channel The dispatch I/O channel to schedule the barrier on. 398 * @param context The application-defined context parameter to pass to 399 * the barrier function. 400 * @param barrier The barrier function. 401 */ 402 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 403 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW 404 void 405 dispatch_io_barrier_f(dispatch_io_t channel, 406 void *context, 407 dispatch_function_t barrier); 408 409 __END_DECLS 410 411 #endif /* __DISPATCH_IO_PRIVATE__ */ 412