dispatch/io.h

   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__ */