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_IO__ 22 #define __DISPATCH_IO__ 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 29 __BEGIN_DECLS 30 31 /*! @header 32 * Dispatch I/O provides both stream and random access asynchronous read and 33 * write operations on file descriptors. One or more dispatch I/O channels may 34 * be created from a file descriptor as either the DISPATCH_IO_STREAM type or 35 * DISPATCH_IO_RANDOM type. Once a channel has been created the application may 36 * schedule asynchronous read and write operations. 37 * 38 * The application may set policies on the dispatch I/O channel to indicate the 39 * desired frequency of I/O handlers for long-running operations. 40 * 41 * Dispatch I/O also provides a memory managment model for I/O buffers that 42 * avoids unnecessary copying of data when pipelined between channels. Dispatch 43 * I/O monitors the overall memory pressure and I/O access patterns for the 44 * application to optimize resource utilization. 45 */ 46 47 /*! 48 * @typedef dispatch_fd_t 49 * Native file descriptor type for the platform. 50 */ 51 typedef int dispatch_fd_t; 52 53 /*! 54 * @functiongroup Dispatch I/O Convenience API 55 * Convenience wrappers around the dispatch I/O channel API, with simpler 56 * callback handler semantics and no explicit management of channel objects. 57 * File descriptors passed to the convenience API are treated as streams, and 58 * scheduling multiple operations on one file descriptor via the convenience API 59 * may incur more overhead than by using the dispatch I/O channel API directly. 60 */ 61 62 #ifdef __BLOCKS__ 63 /*! 64 * @function dispatch_read 65 * Schedule a read operation for asynchronous execution on the specified file 66 * descriptor. The specified handler is enqueued with the data read from the 67 * file descriptor when the operation has completed or an error occurs. 68 * 69 * The data object passed to the handler will be automatically released by the 70 * system when the handler returns. It is the responsibility of the application 71 * to retain, concatenate or copy the data object if it is needed after the 72 * handler returns. 73 * 74 * The data object passed to the handler will only contain as much data as is 75 * currently available from the file descriptor (up to the specified length). 76 * 77 * If an unrecoverable error occurs on the file descriptor, the handler will be 78 * enqueued with the appropriate error code along with a data object of any data 79 * that could be read successfully. 80 * 81 * An invocation of the handler with an error code of zero and an empty data 82 * object indicates that EOF was reached. 83 * 84 * The system takes control of the file descriptor until the handler is 85 * enqueued, and during this time file descriptor flags such as O_NONBLOCK will 86 * be modified by the system on behalf of the application. It is an error for 87 * the application to modify a file descriptor directly while it is under the 88 * control of the system, but it may create additional dispatch I/O convenience 89 * operations or dispatch I/O channels associated with that file descriptor. 90 * 91 * @param fd The file descriptor from which to read the data. 92 * @param length The length of data to read from the file descriptor, 93 * or SIZE_MAX to indicate that all of the data currently 94 * available from the file descriptor should be read. 95 * @param queue The dispatch queue to which the handler should be 96 * submitted. 97 * @param handler The handler to enqueue when data is ready to be 98 * delivered. 99 * param data The data read from the file descriptor. 100 * param error An errno condition for the read operation or 101 * zero if the read was successful. 102 */ 103 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 104 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NONNULL4 DISPATCH_NOTHROW 105 void 106 dispatch_read(dispatch_fd_t fd, 107 size_t length, 108 dispatch_queue_t queue, 109 void (^handler)(dispatch_data_t data, int error)); 110 111 /*! 112 * @function dispatch_write 113 * Schedule a write operation for asynchronous execution on the specified file 114 * descriptor. The specified handler is enqueued when the operation has 115 * completed or an error occurs. 116 * 117 * If an unrecoverable error occurs on the file descriptor, the handler will be 118 * enqueued with the appropriate error code along with the data that could not 119 * be successfully written. 120 * 121 * An invocation of the handler with an error code of zero indicates that the 122 * data was fully written to the channel. 123 * 124 * The system takes control of the file descriptor until the handler is 125 * enqueued, and during this time file descriptor flags such as O_NONBLOCK will 126 * be modified by the system on behalf of the application. It is an error for 127 * the application to modify a file descriptor directly while it is under the 128 * control of the system, but it may create additional dispatch I/O convenience 129 * operations or dispatch I/O channels associated with that file descriptor. 130 * 131 * @param fd The file descriptor to which to write the data. 132 * @param data The data object to write to the file descriptor. 133 * @param queue The dispatch queue to which the handler should be 134 * submitted. 135 * @param handler The handler to enqueue when the data has been written. 136 * param data The data that could not be written to the I/O 137 * channel, or NULL. 138 * param error An errno condition for the write operation or 139 * zero if the write was successful. 140 */ 141 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 142 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL4 143 DISPATCH_NOTHROW 144 void 145 dispatch_write(dispatch_fd_t fd, 146 dispatch_data_t data, 147 dispatch_queue_t queue, 148 void (^handler)(dispatch_data_t data, int error)); 149 #endif /* __BLOCKS__ */ 150 151 /*! 152 * @functiongroup Dispatch I/O Channel API 153 */ 154 155 /*! 156 * @typedef dispatch_io_t 157 * A dispatch I/O channel represents the asynchronous I/O policy applied to a 158 * file descriptor. I/O channels are first class dispatch objects and may be 159 * retained and released, suspended and resumed, etc. 160 */ 161 DISPATCH_DECL(dispatch_io); 162 163 /*! 164 * @typedef dispatch_io_type_t 165 * The type of a dispatch I/O channel: 166 * 167 * @const DISPATCH_IO_STREAM A dispatch I/O channel representing a stream of 168 * bytes. Read and write operations on a channel of this type are performed 169 * serially (in order of creation) and read/write data at the file pointer 170 * position that is current at the time the operation starts executing. 171 * Operations of different type (read vs. write) may be perfomed simultaneously. 172 * Offsets passed to operations on a channel of this type are ignored. 173 * 174 * @const DISPATCH_IO_RANDOM A dispatch I/O channel representing a random 175 * access file. Read and write operations on a channel of this type may be 176 * performed concurrently and read/write data at the specified offset. Offsets 177 * are interpreted relative to the file pointer position current at the time the 178 * I/O channel is created. Attempting to create a channel of this type for a 179 * file descriptor that is not seekable will result in an error. 180 */ 181 #define DISPATCH_IO_STREAM 0 182 #define DISPATCH_IO_RANDOM 1 183 184 typedef unsigned long dispatch_io_type_t; 185 186 #ifdef __BLOCKS__ 187 /*! 188 * @function dispatch_io_create 189 * Create a dispatch I/O channel associated with a file descriptor. The system 190 * takes control of the file descriptor until the channel is closed, an error 191 * occurs on the file descriptor or all references to the channel are released. 192 * At that time the specified cleanup handler will be enqueued and control over 193 * the file descriptor relinquished. 194 * 195 * While a file descriptor is under the control of a dispatch I/O channel, file 196 * descriptor flags such as O_NONBLOCK will be modified by the system on behalf 197 * of the application. It is an error for the application to modify a file 198 * descriptor directly while it is under the control of a dispatch I/O channel, 199 * but it may create additional channels associated with that file descriptor. 200 * 201 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 202 * or DISPATCH_IO_RANDOM). 203 * @param fd The file descriptor to associate with the I/O channel. 204 * @param queue The dispatch queue to which the handler should be submitted. 205 * @param cleanup_handler The handler to enqueue when the system 206 * relinquishes control over the file descriptor. 207 * param error An errno condition if control is relinquished 208 * because channel creation failed, zero otherwise. 209 * @result The newly created dispatch I/O channel or NULL if an error 210 * occurred (invalid type specified). 211 */ 212 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 213 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT 214 DISPATCH_NOTHROW 215 dispatch_io_t 216 dispatch_io_create(dispatch_io_type_t type, 217 dispatch_fd_t fd, 218 dispatch_queue_t queue, 219 void (^cleanup_handler)(int error)); 220 221 /*! 222 * @function dispatch_io_create_with_path 223 * Create a dispatch I/O channel associated with a path name. The specified 224 * path, oflag and mode parameters will be passed to open(2) when the first I/O 225 * operation on the channel is ready to execute and the resulting file 226 * descriptor will remain open and under the control of the system until the 227 * channel is closed, an error occurs on the file descriptor or all references 228 * to the channel are released. At that time the file descriptor will be closed 229 * and the specified cleanup handler will be enqueued. 230 * 231 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 232 * or DISPATCH_IO_RANDOM). 233 * @param path The absolute path to associate with the I/O channel. 234 * @param oflag The flags to pass to open(2) when opening the file at 235 * path. 236 * @param mode The mode to pass to open(2) when creating the file at 237 * path (i.e. with flag O_CREAT), zero otherwise. 238 * @param queue The dispatch queue to which the handler should be 239 * submitted. 240 * @param cleanup_handler The handler to enqueue when the system 241 * has closed the file at path. 242 * param error An errno condition if control is relinquished 243 * because channel creation or opening of the 244 * specified file failed, zero otherwise. 245 * @result The newly created dispatch I/O channel or NULL if an error 246 * occurred (invalid type or non-absolute path specified). 247 */ 248 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 249 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED 250 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 251 dispatch_io_t 252 dispatch_io_create_with_path(dispatch_io_type_t type, 253 const char *path, int oflag, mode_t mode, 254 dispatch_queue_t queue, 255 void (^cleanup_handler)(int error)); 256 257 /*! 258 * @function dispatch_io_create_with_io 259 * Create a new dispatch I/O channel from an existing dispatch I/O channel. 260 * The new channel inherits the file descriptor or path name associated with 261 * the existing channel, but not its channel type or policies. 262 * 263 * If the existing channel is associated with a file descriptor, control by the 264 * system over that file descriptor is extended until the new channel is also 265 * closed, an error occurs on the file descriptor, or all references to both 266 * channels are released. At that time the specified cleanup handler will be 267 * enqueued and control over the file descriptor relinquished. 268 * 269 * While a file descriptor is under the control of a dispatch I/O channel, file 270 * descriptor flags such as O_NONBLOCK will be modified by the system on behalf 271 * of the application. It is an error for the application to modify a file 272 * descriptor directly while it is under the control of a dispatch I/O channel, 273 * but it may create additional channels associated with that file descriptor. 274 * 275 * @param type The desired type of I/O channel (DISPATCH_IO_STREAM 276 * or DISPATCH_IO_RANDOM). 277 * @param io The existing channel to create the new I/O channel from. 278 * @param queue The dispatch queue to which the handler should be submitted. 279 * @param cleanup_handler The handler to enqueue when the system 280 * relinquishes control over the file descriptor 281 * (resp. closes the file at path) associated with 282 * the existing channel. 283 * param error An errno condition if control is relinquished 284 * because channel creation failed, zero otherwise. 285 * @result The newly created dispatch I/O channel or NULL if an error 286 * occurred (invalid type specified). 287 */ 288 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 289 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED 290 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 291 dispatch_io_t 292 dispatch_io_create_with_io(dispatch_io_type_t type, 293 dispatch_io_t io, 294 dispatch_queue_t queue, 295 void (^cleanup_handler)(int error)); 296 297 /*! 298 * @typedef dispatch_io_handler_t 299 * The prototype of I/O handler blocks for dispatch I/O operations. 300 * 301 * @param done A flag indicating whether the operation is complete. 302 * @param data The data object to be handled. 303 * @param error An errno condition for the operation. 304 */ 305 typedef void (^dispatch_io_handler_t)(bool done, dispatch_data_t data, 306 int error); 307 308 /*! 309 * @function dispatch_io_read 310 * Schedule a read operation for asynchronous execution on the specified I/O 311 * channel. The I/O handler is enqueued one or more times depending on the 312 * general load of the system and the policy specified on the I/O channel. 313 * 314 * Any data read from the channel is described by the dispatch data object 315 * passed to the I/O handler. This object will be automatically released by the 316 * system when the I/O handler returns. It is the responsibility of the 317 * application to retain, concatenate or copy the data object if it is needed 318 * after the I/O handler returns. 319 * 320 * Dispatch I/O handlers are not reentrant. The system will ensure that no new 321 * I/O handler instance is invoked until the previously enqueued handler block 322 * has returned. 323 * 324 * An invocation of the I/O handler with the done flag set indicates that the 325 * read operation is complete and that the handler will not be enqueued again. 326 * 327 * If an unrecoverable error occurs on the I/O channel's underlying file 328 * descriptor, the I/O handler will be enqueued with the done flag set, the 329 * appropriate error code and a NULL data object. 330 * 331 * An invocation of the I/O handler with the done flag set, an error code of 332 * zero and an empty data object indicates that EOF was reached. 333 * 334 * @param channel The dispatch I/O channel from which to read the data. 335 * @param offset The offset relative to the channel position from which 336 * to start reading (only for DISPATCH_IO_RANDOM). 337 * @param length The length of data to read from the I/O channel, or 338 * SIZE_MAX to indicate that data should be read until EOF 339 * is reached. 340 * @param queue The dispatch queue to which the I/O handler should be 341 * submitted. 342 * @param io_handler The I/O handler to enqueue when data is ready to be 343 * delivered. 344 * param done A flag indicating whether the operation is complete. 345 * param data An object with the data most recently read from the 346 * I/O channel as part of this read operation, or NULL. 347 * param error An errno condition for the read operation or zero if 348 * the read was successful. 349 */ 350 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 351 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL5 352 DISPATCH_NOTHROW 353 void 354 dispatch_io_read(dispatch_io_t channel, 355 off_t offset, 356 size_t length, 357 dispatch_queue_t queue, 358 dispatch_io_handler_t io_handler); 359 360 /*! 361 * @function dispatch_io_write 362 * Schedule a write operation for asynchronous execution on the specified I/O 363 * channel. The I/O handler is enqueued one or more times depending on the 364 * general load of the system and the policy specified on the I/O channel. 365 * 366 * Any data remaining to be written to the I/O channel is described by the 367 * dispatch data object passed to the I/O handler. This object will be 368 * automatically released by the system when the I/O handler returns. It is the 369 * responsibility of the application to retain, concatenate or copy the data 370 * object if it is needed after the I/O handler returns. 371 * 372 * Dispatch I/O handlers are not reentrant. The system will ensure that no new 373 * I/O handler instance is invoked until the previously enqueued handler block 374 * has returned. 375 * 376 * An invocation of the I/O handler with the done flag set indicates that the 377 * write operation is complete and that the handler will not be enqueued again. 378 * 379 * If an unrecoverable error occurs on the I/O channel's underlying file 380 * descriptor, the I/O handler will be enqueued with the done flag set, the 381 * appropriate error code and an object containing the data that could not be 382 * written. 383 * 384 * An invocation of the I/O handler with the done flag set and an error code of 385 * zero indicates that the data was fully written to the channel. 386 * 387 * @param channel The dispatch I/O channel on which to write the data. 388 * @param offset The offset relative to the channel position from which 389 * to start writing (only for DISPATCH_IO_RANDOM). 390 * @param data The data to write to the I/O channel. The data object 391 * will be retained by the system until the write operation 392 * is complete. 393 * @param queue The dispatch queue to which the I/O handler should be 394 * submitted. 395 * @param io_handler The I/O handler to enqueue when data has been delivered. 396 * param done A flag indicating whether the operation is complete. 397 * param data An object of the data remaining to be 398 * written to the I/O channel as part of this write 399 * operation, or NULL. 400 * param error An errno condition for the write operation or zero 401 * if the write was successful. 402 */ 403 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 404 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4 405 DISPATCH_NONNULL5 DISPATCH_NOTHROW 406 void 407 dispatch_io_write(dispatch_io_t channel, 408 off_t offset, 409 dispatch_data_t data, 410 dispatch_queue_t queue, 411 dispatch_io_handler_t io_handler); 412 #endif /* __BLOCKS__ */ 413 414 /*! 415 * @typedef dispatch_io_close_flags_t 416 * The type of flags you can set on a dispatch_io_close() call 417 * 418 * @const DISPATCH_IO_STOP Stop outstanding operations on a channel when 419 * the channel is closed. 420 */ 421 #define DISPATCH_IO_STOP 0x1 422 423 typedef unsigned long dispatch_io_close_flags_t; 424 425 /*! 426 * @function dispatch_io_close 427 * Close the specified I/O channel to new read or write operations; scheduling 428 * operations on a closed channel results in their handler returning an error. 429 * 430 * If the DISPATCH_IO_STOP flag is provided, the system will make a best effort 431 * to interrupt any outstanding read and write operations on the I/O channel, 432 * otherwise those operations will run to completion normally. 433 * Partial results of read and write operations may be returned even after a 434 * channel is closed with the DISPATCH_IO_STOP flag. 435 * The final invocation of an I/O handler of an interrupted operation will be 436 * passed an ECANCELED error code, as will the I/O handler of an operation 437 * scheduled on a closed channel. 438 * 439 * @param channel The dispatch I/O channel to close. 440 * @param flags The flags for the close operation. 441 */ 442 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 443 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 444 void 445 dispatch_io_close(dispatch_io_t channel, dispatch_io_close_flags_t flags); 446 447 #ifdef __BLOCKS__ 448 /*! 449 * @function dispatch_io_barrier 450 * Schedule a barrier operation on the specified I/O channel; all previously 451 * scheduled operations on the channel will complete before the provided 452 * barrier block is enqueued onto the global queue determined by the channel's 453 * target queue, and no subsequently scheduled operations will start until the 454 * barrier block has returned. 455 * 456 * If multiple channels are associated with the same file descriptor, a barrier 457 * operation scheduled on any of these channels will act as a barrier across all 458 * channels in question, i.e. all previously scheduled operations on any of the 459 * channels will complete before the barrier block is enqueued, and no 460 * operations subsequently scheduled on any of the channels will start until the 461 * barrier block has returned. 462 * 463 * While the barrier block is running, it may safely operate on the channel's 464 * underlying file descriptor with fsync(2), lseek(2) etc. (but not close(2)). 465 * 466 * @param channel The dispatch I/O channel to schedule the barrier on. 467 * @param barrier The barrier block. 468 */ 469 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 470 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 471 void 472 dispatch_io_barrier(dispatch_io_t channel, dispatch_block_t barrier); 473 #endif /* __BLOCKS__ */ 474 475 /*! 476 * @function dispatch_io_get_descriptor 477 * Returns the file descriptor underlying a dispatch I/O channel. 478 * 479 * Will return -1 for a channel closed with dispatch_io_close() and for a 480 * channel associated with a path name that has not yet been open(2)ed. 481 * 482 * If called from a barrier block scheduled on a channel associated with a path 483 * name that has not yet been open(2)ed, this will trigger the channel open(2) 484 * operation and return the resulting file descriptor. 485 * 486 * @param channel The dispatch I/O channel to query. 487 * @result The file descriptor underlying the channel, or -1. 488 */ 489 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 490 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_NOTHROW 491 dispatch_fd_t 492 dispatch_io_get_descriptor(dispatch_io_t channel); 493 494 /*! 495 * @function dispatch_io_set_high_water 496 * Set a high water mark on the I/O channel for all operations. 497 * 498 * The system will make a best effort to enqueue I/O handlers with partial 499 * results as soon the number of bytes processed by an operation (i.e. read or 500 * written) reaches the high water mark. 501 * 502 * The size of data objects passed to I/O handlers for this channel will never 503 * exceed the specified high water mark. 504 * 505 * The default value for the high water mark is unlimited (i.e. SIZE_MAX). 506 * 507 * @param channel The dispatch I/O channel on which to set the policy. 508 * @param high_water The number of bytes to use as a high water mark. 509 */ 510 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 511 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 512 void 513 dispatch_io_set_high_water(dispatch_io_t channel, size_t high_water); 514 515 /*! 516 * @function dispatch_io_set_low_water 517 * Set a low water mark on the I/O channel for all operations. 518 * 519 * The system will process (i.e. read or write) at least the low water mark 520 * number of bytes for an operation before enqueueing I/O handlers with partial 521 * results. 522 * 523 * The size of data objects passed to intermediate I/O handler invocations for 524 * this channel (i.e. excluding the final invocation) will never be smaller than 525 * the specified low water mark, except if the channel has an interval with the 526 * DISPATCH_IO_STRICT_INTERVAL flag set or if EOF or an error was encountered. 527 * 528 * I/O handlers should be prepared to receive amounts of data significantly 529 * larger than the low water mark in general. If an I/O handler requires 530 * intermediate results of fixed size, set both the low and and the high water 531 * mark to that size. 532 * 533 * The default value for the low water mark is unspecified, but must be assumed 534 * to be such that intermediate handler invocations may occur. 535 * If I/O handler invocations with partial results are not desired, set the 536 * low water mark to SIZE_MAX. 537 * 538 * @param channel The dispatch I/O channel on which to set the policy. 539 * @param low_water The number of bytes to use as a low water mark. 540 */ 541 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 542 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 543 void 544 dispatch_io_set_low_water(dispatch_io_t channel, size_t low_water); 545 546 /*! 547 * @typedef dispatch_io_interval_flags_t 548 * Type of flags to set on dispatch_io_set_interval() 549 * 550 * @const DISPATCH_IO_STRICT_INTERVAL Enqueue I/O handlers at a channel's 551 * interval setting even if the amount of data ready to be delivered is inferior 552 * to the low water mark (or zero). 553 */ 554 #define DISPATCH_IO_STRICT_INTERVAL 0x1 555 556 typedef unsigned long dispatch_io_interval_flags_t; 557 558 /*! 559 * @function dispatch_io_set_interval 560 * Set a nanosecond interval at which I/O handlers are to be enqueued on the 561 * I/O channel for all operations. 562 * 563 * This allows an application to receive periodic feedback on the progress of 564 * read and write operations, e.g. for the purposes of displaying progress bars. 565 * 566 * If the amount of data ready to be delivered to an I/O handler at the interval 567 * is inferior to the channel low water mark, the handler will only be enqueued 568 * if the DISPATCH_IO_STRICT_INTERVAL flag is set. 569 * 570 * Note that the system may defer enqueueing interval I/O handlers by a small 571 * unspecified amount of leeway in order to align with other system activity for 572 * improved system performance or power consumption. 573 * 574 * @param channel The dispatch I/O channel on which to set the policy. 575 * @param interval The interval in nanoseconds at which delivery of the I/O 576 * handler is desired. 577 * @param flags Flags indicating desired data delivery behavior at 578 * interval time. 579 */ 580 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0) 581 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 582 void 583 dispatch_io_set_interval(dispatch_io_t channel, 584 uint64_t interval, 585 dispatch_io_interval_flags_t flags); 586 587 __END_DECLS 588 589 #endif /* __DISPATCH_IO__ */ 590