Manpages - dispatch_io_create.3

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

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.

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

page. The dispatch I/O framework also provides the convenience functions

and

for uses that do not require the full functionality provided by I/O channels.

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.

Dispatch I/O channels can have one of the following types:

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.

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).

The

and

functions create a dispatch I/O channel of provided

from a file descriptor

or an absolute pathname, respectively. They can be thought of as analogous to the

POSIX function and the

function in the standard C library. For a channel created from a pathname, the provided

and

parameters will be passed to

when the first I/O operation on the channel is ready to execute.

The provided

block will be submitted to the specified

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

block will be submitted immediately and passed an

parameter with the POSIX error encountered. If an invalid

or a non-absolute

argument is specified, these functions will return NULL and the

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

is invoked, see

for details.

The

function closes a dispatch I/O channel to new submissions of I/O operations. If

is passed in the

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

error code, along with any partial results.

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.

The

and

functions configure the water mark settings of a

The system will read or write at least the number of bytes specified by

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

The

function configures the time

at which I/O handlers are submitted (measured in nanoseconds). If

is passed in the

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.

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:

the final handler invocation for an I/O operation

EOF was encountered

the channel has an interval with the

flag set

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.

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

When an application creates a dispatch I/O channel from a file descriptor with the

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

the file descriptor. While a file descriptor is under the control of a dispatch I/O channel, file descriptor flags such as

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

and

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.

The

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

on the underlying file descriptor have finished. No new I/O operations will start until the barrier block finishes.

The barrier block may operate on the underlying file descriptor with functions like

As discussed in the

section, the barrier block must not

the file descriptor, and if it changes any flags on the file descriptor, it must restore them before finishing.

There is no synchronization between a barrier block and any

handler blocks; they may be running at the same time. The barrier block itself is responsible for any required synchronization.

Dispatch I/O channel objects are retained and released via calls to

and