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