io.h

Dispatch I/O provides both stream and random access asynchronous read and write operations on file descriptors. One or more dispatch I/O channels may be created from a file descriptor as either the DISPATCH_IO_STREAM type or DISPATCH_IO_RANDOM type. Once a channel has been created the application may schedule asynchronous read and write operations.

The application may set policies on the dispatch I/O channel to indicate the desired frequency of I/O handlers for long-running operations.

Dispatch I/O also provides a memory management model for I/O buffers that avoids unnecessary copying of data when pipelined between channels. Dispatch I/O monitors the overall memory pressure and I/O access patterns for the application to optimize resource utilization.

Dispatch I/O Channel API

Group members:

Dispatch I/O Convenience API

Convenience wrappers around the dispatch I/O channel API, with simpler callback handler semantics and no explicit management of channel objects. File descriptors passed to the convenience API are treated as streams, and scheduling multiple operations on one file descriptor via the convenience API may incur more overhead than by using the dispatch I/O channel API directly.

Group members:

Functions

dispatch_io_barrier

Parameters

channel: The dispatch I/O channel to schedule the barrier on.
barrier: The barrier block.

Discussion

Schedule a barrier operation on the specified I/O channel; all previously scheduled operations on the channel will complete before the provided barrier block is enqueued onto the global queue determined by the channel's target queue, and no subsequently scheduled operations will start until the barrier block has returned.

If multiple channels are associated with the same file descriptor, a barrier operation scheduled on any of these channels will act as a barrier across all channels in question, i.e. all previously scheduled operations on any of the channels will complete before the barrier block is enqueued, and no operations subsequently scheduled on any of the channels will start until the barrier block has returned.

While the barrier block is running, it may safely operate on the channel's underlying file descriptor with fsync(2), lseek(2) etc. (but not close(2)).

dispatch_io_close

Parameters

channel: The dispatch I/O channel to close.
flags: The flags for the close operation.

Discussion

Close the specified I/O channel to new read or write operations; scheduling operations on a closed channel results in their handler returning an error.

If the DISPATCH_IO_STOP flag is provided, the system will make a best effort to interrupt any outstanding read and write operations on the I/O channel, otherwise those operations will run to completion normally. Partial results of read and write operations may be returned even after a channel is closed with the DISPATCH_IO_STOP flag. The final invocation of an I/O handler of an interrupted operation will be passed an ECANCELED error code, as will the I/O handler of an operation scheduled on a closed channel.

dispatch_io_create

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED   dispatch_io_t dispatch_io_create(
    dispatch_io_type_t type, 
    dispatch_fd_t fd, 
    dispatch_queue_t queue, 
    void (^cleanup_handler)(
        int error));

Parameters

type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).
fd: The file descriptor to associate with the I/O channel.
queue: The dispatch queue to which the handler should be submitted.
cleanup_handler: The handler to enqueue when the system relinquishes control over the file descriptor. param error An errno condition if control is relinquished because channel creation failed, zero otherwise.

Return Value

The newly created dispatch I/O channel or NULL if an error occurred (invalid type specified).

Discussion

Create a dispatch I/O channel associated with a file descriptor. The system takes control of the 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 specified cleanup handler will be enqueued and control over the file descriptor relinquished.

While a file descriptor is under the control of a dispatch I/O channel, file descriptor flags such as 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 additional channels associated with that file descriptor.

dispatch_io_create_with_io

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED  dispatch_io_t dispatch_io_create_with_io(
    dispatch_io_type_t type, 
    dispatch_io_t io, 
    dispatch_queue_t queue, 
    void (^cleanup_handler)(
        int error));

Parameters

type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).
io: The existing channel to create the new I/O channel from.
queue: The dispatch queue to which the handler should be submitted.
cleanup_handler: The handler to enqueue when the system relinquishes control over the file descriptor (resp. closes the file at path) associated with the existing channel. param error An errno condition if control is relinquished because channel creation failed, zero otherwise.

Return Value

The newly created dispatch I/O channel or NULL if an error occurred (invalid type specified).

Discussion

Create a new dispatch I/O channel from an existing dispatch I/O channel. The new channel inherits the file descriptor or path name associated with the existing channel, but not its channel type or policies.

If the existing channel is associated with a file descriptor, control by the system over that file descriptor is extended until the new channel is also closed, an error occurs on the file descriptor, or all references to both channels are released. At that time the specified cleanup handler will be enqueued and control over the file descriptor relinquished.

dispatch_io_create_with_path

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED  dispatch_io_t dispatch_io_create_with_path(
    dispatch_io_type_t type, 
    const char *path,
    int oflag,
    mode_t mode, 
    dispatch_queue_t queue, 
    void (^cleanup_handler)(
        int error));

Parameters

type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).
path: The absolute path to associate with the I/O channel.
oflag: The flags to pass to open(2) when opening the file at path.
mode: The mode to pass to open(2) when creating the file at path (i.e. with flag O_CREAT), zero otherwise.
queue: The dispatch queue to which the handler should be submitted.
cleanup_handler: The handler to enqueue when the system has closed the file at path. param error An errno condition if control is relinquished because channel creation or opening of the specified file failed, zero otherwise.

Return Value

The newly created dispatch I/O channel or NULL if an error occurred (invalid type or non-absolute path specified).

Discussion

Create a dispatch I/O channel associated with a path name. The specified path, oflag and mode parameters will be passed to open(2) when the first I/O operation on the channel is ready to execute and the resulting file descriptor will remain open and under the control of the system until the channel is closed, an error occurs on the file descriptor or all references to the channel are released. At that time the file descriptor will be closed and the specified cleanup handler will be enqueued.

dispatch_io_get_descriptor

Parameters

channel: The dispatch I/O channel to query.

Return Value

Discussion

Will return -1 for a channel closed with dispatch_io_close() and for a channel associated with a path name that has not yet been open(2)ed.

If called from a barrier block scheduled on a channel associated with a path name that has not yet been open(2)ed, this will trigger the channel open(2) operation and return the resulting file descriptor.

dispatch_io_read

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL5  void dispatch_io_read(
    dispatch_io_t channel, 
    off_t offset, 
    size_t length, 
    dispatch_queue_t queue, 
    dispatch_io_handler_t io_handler);

Parameters

channel: The dispatch I/O channel from which to read the data.
offset: The offset relative to the channel position from which to start reading (only for DISPATCH_IO_RANDOM).
length: The length of data to read from the I/O channel, or SIZE_MAX to indicate that data should be read until EOF is reached.
queue: The dispatch queue to which the I/O handler should be submitted.
io_handler: The I/O handler to enqueue when data is ready to be delivered. param done A flag indicating whether the operation is complete. param data An object with the data most recently read from the I/O channel as part of this read operation, or NULL. param error An errno condition for the read operation or zero if the read was successful.

Discussion

Schedule a read operation for asynchronous execution on the specified I/O channel. The I/O handler is enqueued one or more times depending on the general load of the system and the policy specified on the I/O channel.

Any data read from the channel is described by the dispatch data object passed to the I/O handler. This object will be automatically released by the system when the I/O handler returns. It is the responsibility of the application to retain, concatenate or copy the data object if it is needed after the I/O handler returns.

Dispatch I/O handlers are not reentrant. The system will ensure that no new I/O handler instance is invoked until the previously enqueued handler block has returned.

An invocation of the I/O handler with the done flag set indicates that the read operation is complete and that the handler will not be enqueued again.

If an unrecoverable error occurs on the I/O channel's underlying file descriptor, the I/O handler will be enqueued with the done flag set, the appropriate error code and a NULL data object.

An invocation of the I/O handler with the done flag set, an error code of zero and an empty data object indicates that EOF was reached.

dispatch_io_set_high_water

Parameters

channel: The dispatch I/O channel on which to set the policy.
high_water: The number of bytes to use as a high water mark.

Discussion

The system will make a best effort to enqueue I/O handlers with partial results as soon the number of bytes processed by an operation (i.e. read or written) reaches the high water mark.

The size of data objects passed to I/O handlers for this channel will never exceed the specified high water mark.

dispatch_io_set_interval

Parameters

channel: The dispatch I/O channel on which to set the policy.
interval: The interval in nanoseconds at which delivery of the I/O handler is desired.
flags: Flags indicating desired data delivery behavior at interval time.

Discussion

Set a nanosecond interval at which I/O handlers are to be enqueued on the I/O channel for all operations.

This allows an application to receive periodic feedback on the progress of read and write operations, e.g. for the purposes of displaying progress bars.

If the amount of data ready to be delivered to an I/O handler at the interval is inferior to the channel low water mark, the handler will only be enqueued if the DISPATCH_IO_STRICT_INTERVAL flag is set.

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.

dispatch_io_set_low_water

Parameters

channel: The dispatch I/O channel on which to set the policy.
low_water: The number of bytes to use as a low water mark.

Discussion

The system will process (i.e. read or write) at least the low water mark number of bytes for an operation before enqueueing I/O handlers with partial results.

The size of data objects passed to intermediate I/O handler invocations for this channel (i.e. excluding the final invocation) will never be smaller than the specified low water mark, except if the channel has an interval with the DISPATCH_IO_STRICT_INTERVAL flag set or if EOF or an error was encountered.

I/O handlers should be prepared to receive amounts of data significantly larger than the low water mark in general. If an I/O handler requires intermediate results of fixed size, set both the low and and the high water mark to that size.

The default value for the low water mark is unspecified, but must be assumed to be such that intermediate handler invocations may occur. If I/O handler invocations with partial results are not desired, set the low water mark to SIZE_MAX.

dispatch_io_write

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4 DISPATCH_NONNULL5  void dispatch_io_write(
    dispatch_io_t channel, 
    off_t offset, 
    dispatch_data_t data, 
    dispatch_queue_t queue, 
    dispatch_io_handler_t io_handler);

Parameters

channel: The dispatch I/O channel on which to write the data.
offset: The offset relative to the channel position from which to start writing (only for DISPATCH_IO_RANDOM).
data: The data to write to the I/O channel. The data object will be retained by the system until the write operation is complete.
queue: The dispatch queue to which the I/O handler should be submitted.
io_handler: The I/O handler to enqueue when data has been delivered. param done A flag indicating whether the operation is complete. param data An object of the data remaining to be written to the I/O channel as part of this write operation, or NULL. param error An errno condition for the write operation or zero if the write was successful.

Discussion

Schedule a write operation for asynchronous execution on the specified I/O channel. The I/O handler is enqueued one or more times depending on the general load of the system and the policy specified on the I/O channel.

Any data remaining to be written to the I/O channel is described by the dispatch data object passed to the I/O handler. This object will be automatically released by the system when the I/O handler returns. It is the responsibility of the application to retain, concatenate or copy the data object if it is needed after the I/O handler returns.

Dispatch I/O handlers are not reentrant. The system will ensure that no new I/O handler instance is invoked until the previously enqueued handler block has returned.

An invocation of the I/O handler with the done flag set indicates that the write operation is complete and that the handler will not be enqueued again.

If an unrecoverable error occurs on the I/O channel's underlying file descriptor, the I/O handler will be enqueued with the done flag set, the appropriate error code and an object containing the data that could not be written.

An invocation of the I/O handler with the done flag set and an error code of zero indicates that the data was fully written to the channel.

dispatch_read

Parameters

fd: The file descriptor from which to read the data.
length: The length of data to read from the file descriptor, or SIZE_MAX to indicate that all of the data currently available from the file descriptor should be read.
queue: The dispatch queue to which the handler should be submitted.
handler: The handler to enqueue when data is ready to be delivered. param data The data read from the file descriptor. param error An errno condition for the read operation or zero if the read was successful.

Discussion

Schedule a read operation for asynchronous execution on the specified file descriptor. The specified handler is enqueued with the data read from the file descriptor when the operation has completed or an error occurs.

The data object passed to the handler will be automatically released by the system when the handler returns. It is the responsibility of the application to retain, concatenate or copy the data object if it is needed after the handler returns.

The data object passed to the handler will only contain as much data as is currently available from the file descriptor (up to the specified length).

If an unrecoverable error occurs on the file descriptor, the handler will be enqueued with the appropriate error code along with a data object of any data that could be read successfully.

An invocation of the handler with an error code of zero and an empty data object indicates that EOF was reached.

The system takes control of the file descriptor until the handler is enqueued, and during this time file descriptor flags such as 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 the system, but it may create additional dispatch I/O convenience operations or dispatch I/O channels associated with that file descriptor.

dispatch_write

(
    macos(
        10.7),
    ios(
        5.0)) DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL4  void dispatch_write(
    dispatch_fd_t fd, 
    dispatch_data_t data, 
    dispatch_queue_t queue, 
    void (^handler)(
        dispatch_data_t _Nullable data,
        int error));

Parameters

fd: The file descriptor to which to write the data.
data: The data object to write to the file descriptor.
queue: The dispatch queue to which the handler should be submitted.
handler: The handler to enqueue when the data has been written. param data The data that could not be written to the I/O channel, or NULL. param error An errno condition for the write operation or zero if the write was successful.

Discussion

Schedule a write operation for asynchronous execution on the specified file descriptor. The specified handler is enqueued when the operation has completed or an error occurs.

If an unrecoverable error occurs on the file descriptor, the handler will be enqueued with the appropriate error code along with the data that could not be successfully written.

An invocation of the handler with an error code of zero indicates that the data was fully written to the channel.

Typedefs

dispatch_fd_t

Discussion

dispatch_io_close_flags_t

Constants

DISPATCH_IO_STOP: Stop outstanding operations on a channel when the channel is closed.

Discussion

dispatch_io_handler_t

Parameters

done: A flag indicating whether the operation is complete.
data: The data object to be handled.
error: An errno condition for the operation.

Discussion

dispatch_io_interval_flags_t

Constants

DISPATCH_IO_STRICT_INTERVAL: Enqueue I/O handlers at a channel's interval setting even if the amount of data ready to be delivered is inferior to the low water mark (or zero).

Discussion

dispatch_io_t

Discussion

A dispatch I/O channel represents the asynchronous I/O policy applied to a file descriptor. I/O channels are first class dispatch objects and may be retained and released, suspended and resumed, etc.

dispatch_io_type_t

Constants

DISPATCH_IO_STREAM: A dispatch I/O channel representing a stream of bytes. Read and write operations on a channel of this type are performed serially (in order of creation) and read/write data at the file pointer position that is current at the time the operation starts executing. Operations of different type (read vs. write) may be performed simultaneously. Offsets passed to operations on a channel of this type are ignored.
DISPATCH_IO_RANDOM: A dispatch I/O channel representing a random access file. Read and write operations on a channel of this type may be performed concurrently and read/write data at the specified offset. Offsets are interpreted relative to the file pointer position current at the time the I/O channel is created. Attempting to create a channel of this type for a file descriptor that is not seekable will result in an error.

Introduction

Groups

Dispatch I/O Channel API

Group members:

Dispatch I/O Convenience API

Group members:

Functions

Parameters

Discussion

Parameters

Discussion

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

Parameters

Discussion

Parameters

Discussion

Parameters

Discussion

Parameters

Discussion

Parameters

Discussion

Parameters

Discussion

Parameters

Discussion

Typedefs

Discussion

Constants

Discussion

Parameters

Discussion

Constants

Discussion

Discussion

Constants

Discussion

Macro Definitions

Discussion

Discussion

Discussion

Discussion