| .\" Copyright (c) 2010-2013 Apple Inc. All rights reserved. |
| .Dd December 1, 2010 |
| .Dt dispatch_io_create 3 |
| .Os Darwin |
| .Sh NAME |
| .Nm dispatch_io_create , |
| .Nm dispatch_io_create_with_path , |
| .Nm dispatch_io_close , |
| .Nm dispatch_io_set_high_water , |
| .Nm dispatch_io_set_low_water , |
| .Nm dispatch_io_set_interval , |
| .Nm dispatch_io_barrier |
| .Nd open, close and configure dispatch I/O channels |
| .Sh SYNOPSIS |
| .Fd #include <dispatch/dispatch.h> |
| .Ft dispatch_io_t |
| .Fo dispatch_io_create |
| .Fa "dispatch_io_type_t type" |
| .Fa "int fd" |
| .Fa "dispatch_queue_t queue" |
| .Fa "void (^cleanup_handler)(int error)" |
| .Fc |
| .Ft dispatch_io_t |
| .Fo dispatch_io_create_with_path |
| .Fa "dispatch_io_type_t type" |
| .Fa "const char *path" |
| .Fa "int oflag" |
| .Fa "mode_t mode" |
| .Fa "dispatch_queue_t queue" |
| .Fa "void (^cleanup_handler)(int error)" |
| .Fc |
| .Ft void |
| .Fo dispatch_io_close |
| .Fa "dispatch_io_t channel" |
| .Fa "dispatch_io_close_flags_t flags" |
| .Fc |
| .Ft void |
| .Fo dispatch_io_set_high_water |
| .Fa "dispatch_io_t channel" |
| .Fa "size_t high_water" |
| .Fc |
| .Ft void |
| .Fo dispatch_io_set_low_water |
| .Fa "dispatch_io_t channel" |
| .Fa "size_t low_water" |
| .Fc |
| .Ft void |
| .Fo dispatch_io_set_interval |
| .Fa "dispatch_io_t channel" |
| .Fa "uint64_t interval" |
| .Fa "dispatch_io_interval_flags_t flags" |
| .Fc |
| .Ft void |
| .Fo dispatch_io_barrier |
| .Fa "dispatch_io_t channel" |
| .Fa "void (^barrier)(void)" |
| .Fc |
| .Sh DESCRIPTION |
| The dispatch I/O framework is an API for asynchronous read and write I/O |
| operations. It is an application of the ideas and idioms present in the |
| .Xr dispatch 3 |
| framework to device I/O. Dispatch I/O enables an application to more easily |
| avoid blocking I/O operations and allows it to more directly express its I/O |
| requirements than by using the raw POSIX file API. Dispatch I/O will make a |
| best effort to optimize how and when asynchronous I/O operations are performed |
| based on the capabilities of the targeted device. |
| .Pp |
| This page provides details on how to create and configure dispatch I/O |
| channels. Reading from and writing to these channels is covered in the |
| .Xr dispatch_io_read 3 |
| page. The dispatch I/O framework also provides the convenience functions |
| .Xr dispatch_read 3 |
| and |
| .Xr dispatch_write 3 |
| for uses that do not require the full functionality provided by I/O channels. |
| .Sh FUNDAMENTALS |
| A dispatch I/O channel represents the asynchronous I/O policy applied to a file |
| descriptor and encapsulates it for the purposes of ownership tracking while |
| I/O operations are ongoing. |
| .Sh CHANNEL TYPES |
| Dispatch I/O channels can have one of the following types: |
| .Bl -tag -width DISPATCH_IO_STREAM -compact -offset indent |
| .It DISPATCH_IO_STREAM |
| channels that represent a stream of bytes and do not support reads and writes |
| at arbitrary offsets, such as pipes or sockets. Channels of this type perform |
| read and write operations sequentially at the current file pointer position and |
| ignore any offset specified. Depending on the underlying file descriptor, read |
| operations may be performed simultaneously with write operations. |
| .It DISPATCH_IO_RANDOM |
| channels that represent random access files on disk. Only supported for |
| seekable file descriptors and paths. Channels of this type may perform |
| submitted read and write operations concurrently at the specified offset |
| (interpreted relative to the position of the file pointer when the channel was |
| created). |
| .El |
| .Sh CHANNEL OPENING AND CLOSING |
| The |
| .Fn dispatch_io_create |
| and |
| .Fn dispatch_io_create_with_path |
| functions create a dispatch I/O channel of provided |
| .Fa type |
| from a file descriptor |
| .Fa fd |
| or an absolute pathname, respectively. They can be thought of as analogous to |
| the |
| .Xr fdopen 3 |
| POSIX function and the |
| .Xr fopen 3 |
| function in the standard C library. For a channel created from a pathname, the |
| provided |
| .Fa path , |
| .Fa oflag |
| and |
| .Fa mode |
| parameters will be passed to |
| .Xr open 2 |
| when the first I/O operation on the channel is ready to execute. |
| .Pp |
| The provided |
| .Fa cleanup_handler |
| block will be submitted to the specified |
| .Fa queue |
| when all I/O operations on the channel have completed and it is closed or |
| reaches the end of its lifecycle. If an error occurs during channel creation, |
| the |
| .Fa cleanup_handler |
| block will be submitted immediately and passed an |
| .Fa error |
| parameter with the POSIX error encountered. If an invalid |
| .Fa type |
| or a non-absolute |
| .Fa path |
| argument is specified, these functions will return NULL and the |
| .Fa cleanup_handler |
| will not be invoked. After successfully creating a dispatch I/O channel from a |
| file descriptor, the application must take care not to modify that file |
| descriptor until the associated |
| .Fa cleanup_handler |
| is invoked, see |
| .Sx "FILEDESCRIPTOR OWNERSHIP" |
| for details. |
| .Pp |
| The |
| .Fn dispatch_io_close |
| function closes a dispatch I/O channel to new submissions of I/O operations. If |
| .Dv DISPATCH_IO_STOP |
| is passed in the |
| .Fa flags |
| parameter, the system will in addition not perform the I/O operations already |
| submitted to the channel that are still pending and will make a best effort to |
| interrupt any ongoing operations. Handlers for operations so affected will be |
| passed the |
| .Er ECANCELED |
| error code, along with any partial results. |
| .Sh CHANNEL CONFIGURATION |
| Dispatch I/O channels have high-water mark, low-water mark and interval |
| configuration settings that determine if and when partial results from I/O |
| operations are delivered via their associated I/O handlers. |
| .Pp |
| The |
| .Fn dispatch_io_set_high_water |
| and |
| .Fn dispatch_io_set_low_water |
| functions configure the water mark settings of a |
| .Fa channel . |
| The system will read |
| or write at least the number of bytes specified by |
| .Fa low_water |
| before submitting an I/O handler with partial results, and will make a best |
| effort to submit an I/O handler as soon as the number of bytes read or written |
| reaches |
| .Fa high_water . |
| .Pp |
| The |
| .Fn dispatch_io_set_interval |
| function configures the time |
| .Fa interval |
| at which I/O handlers are submitted (measured in nanoseconds). If |
| .Dv DISPATCH_IO_STRICT_INTERVAL |
| is passed in the |
| .Fa flags |
| parameter, the interval will be strictly observed even if there is an |
| insufficient amount of data to deliver; otherwise delivery will be skipped for |
| intervals where the amount of available data is inferior to the channel's |
| low-water mark. Note that the system may defer enqueueing interval I/O handlers |
| by a small unspecified amount of leeway in order to align with other system |
| activity for improved system performance or power consumption. |
| .Pp |
| .Sh DATA DELIVERY |
| The size of data objects passed to I/O handlers for a channel will never be |
| larger than the high-water mark set on the channel; it will also never be |
| smaller than the low-water mark, except in the following cases: |
| .Bl -dash -offset indent -compact |
| .It |
| the final handler invocation for an I/O operation |
| .It |
| EOF was encountered |
| .It |
| the channel has an interval with the |
| .Dv DISPATCH_IO_STRICT_INTERVAL |
| flag set |
| .El |
| Bear in mind that dispatch I/O channels will typically deliver amounts of data |
| significantly higher than the low-water mark. The default value for the |
| low-water mark is unspecified, but must be assumed to allow intermediate |
| handler invocations. The default value for the high-water mark is |
| unlimited (i.e.\& |
| .Dv SIZE_MAX ) . |
| Channels that require intermediate results of fixed size should have both the |
| low-water and the high-water mark set to that size. Channels that do not wish |
| to receive any intermediate results should have the low-water mark set to |
| .Dv SIZE_MAX . |
| .Pp |
| .Sh FILEDESCRIPTOR OWNERSHIP |
| When an application creates a dispatch I/O channel from a file descriptor with |
| the |
| .Fn dispatch_io_create |
| function, the system takes control of that file descriptor until the channel is |
| closed, an error occurs on the file descriptor or all references to the channel |
| are released. At that time the channel's cleanup handler will be enqueued and |
| control over the file descriptor relinquished, making it safe for the |
| application to |
| .Xr close 2 |
| the file descriptor. While a file descriptor is under the control of a dispatch |
| I/O channel, file descriptor flags such as |
| .Dv O_NONBLOCK |
| will be modified by the system on behalf of the application. It is an error for |
| the application to modify a file descriptor directly while it is under the |
| control of a dispatch I/O channel, but it may create further I/O channels |
| from that file descriptor or use the |
| .Xr dispatch_read 3 |
| and |
| .Xr dispatch_write 3 |
| convenience functions with that file descriptor. If multiple I/O channels have |
| been created from the same file descriptor, all the associated cleanup handlers |
| will be submitted together once the last channel has been closed resp.\& all |
| references to those channels have been released. If convenience functions have |
| also been used on that file descriptor, submission of their handlers will be |
| tied to the submission of the channel cleanup handlers as well. |
| .Pp |
| .Sh BARRIER OPERATIONS |
| The |
| .Fn dispatch_io_barrier |
| function schedules a barrier operation on an I/O channel. The specified barrier |
| block will be run once, after all current I/O operations (such as |
| .Xr read 2 or |
| .Xr write 2 ) |
| on the underlying |
| file descriptor have finished. No new I/O operations will start until the |
| barrier block finishes. |
| .Pp |
| The barrier block may operate on the underlying file descriptor with functions |
| like |
| .Xr fsync 2 |
| or |
| .Xr lseek 2 . |
| As discussed in the |
| .Sx FILEDESCRIPTOR OWNERSHIP |
| section, the barrier block must not |
| .Xr close 2 |
| the file descriptor, and if it changes any flags on the file descriptor, it |
| must restore them before finishing. |
| .Pp |
| There is no synchronization between a barrier block and any |
| .Xr dispatch_io_read 3 |
| or |
| .Xr dispatch_io_write 3 |
| handler blocks; they may be running at the same time. The barrier block itself |
| is responsible for any required synchronization. |
| .Sh MEMORY MODEL |
| Dispatch I/O channel objects are retained and released via calls to |
| .Fn dispatch_retain |
| and |
| .Fn dispatch_release . |
| .Sh SEE ALSO |
| .Xr dispatch 3 , |
| .Xr dispatch_io_read 3 , |
| .Xr dispatch_object 3 , |
| .Xr dispatch_read 3 , |
| .Xr fopen 3 , |
| .Xr open 2 |