.\" 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