Struct DispatchIO

Source

#[repr(C)]
pub struct DispatchIO { /* private fields */ }

Expand description

Dispatch IO.

Implementations§

Source §

impl DispatchIO

Source

pub unsafe fn new( type: DispatchIOStreamType, fd: dispatch_fd_t, queue: &DispatchQueue, cleanup_handler: &DynBlock<dyn Fn(c_int)>, ) -> DispatchRetained<DispatchIO> ⓘ

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.

Parameter type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).

Parameter fd: The file descriptor to associate with the I/O channel.

Parameter queue: The dispatch queue to which the handler should be submitted.

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

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

Source

pub unsafe fn with_path( type: DispatchIOStreamType, path: NonNull<c_char>, oflag: c_int, mode: mode_t, queue: &DispatchQueue, cleanup_handler: &DynBlock<dyn Fn(c_int)>, ) -> DispatchRetained<DispatchIO> ⓘ

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.

Parameter type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).

Parameter path: The absolute path to associate with the I/O channel.

Parameter oflag: The flags to pass to open(2) when opening the file at path.

Parameter mode: The mode to pass to open(2) when creating the file at path (i.e. with flag O_CREAT), zero otherwise.

Parameter queue: The dispatch queue to which the handler should be submitted.

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

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

Source

pub fn with_io( type: DispatchIOStreamType, io: &DispatchIO, queue: &DispatchQueue, cleanup_handler: &DynBlock<dyn Fn(c_int)>, ) -> DispatchRetained<DispatchIO> ⓘ

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.

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.

Parameter type: The desired type of I/O channel (DISPATCH_IO_STREAM or DISPATCH_IO_RANDOM).

Parameter io: The existing channel to create the new I/O channel from.

Parameter queue: The dispatch queue to which the handler should be submitted.

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

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

Source §

impl DispatchIO

Source

pub unsafe fn read( self: &DispatchIO, offset: off_t, length: usize, queue: &DispatchQueue, io_handler: dispatch_io_handler_t, )

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.

Parameter channel: The dispatch I/O channel from which to read the data.

Parameter offset: The offset relative to the channel position from which to start reading (only for DISPATCH_IO_RANDOM).

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

Parameter queue: The dispatch queue to which the I/O handler should be submitted.

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

Source

pub unsafe fn write( self: &DispatchIO, offset: off_t, data: &DispatchData, queue: &DispatchQueue, io_handler: dispatch_io_handler_t, )

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.

Parameter channel: The dispatch I/O channel on which to write the data.

Parameter offset: The offset relative to the channel position from which to start writing (only for DISPATCH_IO_RANDOM).

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

Parameter queue: The dispatch queue to which the I/O handler should be submitted.

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

Source

pub fn close(self: &DispatchIO, flags: DispatchIOCloseFlags)

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.

Parameter channel: The dispatch I/O channel to close.

Parameter flags: The flags for the close operation.

Source

pub unsafe fn barrier(self: &DispatchIO, barrier: dispatch_block_t)

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

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

Parameter barrier: The barrier block.

Source

pub fn descriptor(self: &DispatchIO) -> dispatch_fd_t

Returns the file descriptor underlying a dispatch I/O channel.

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.

Parameter channel: The dispatch I/O channel to query.

Returns: The file descriptor underlying the channel, or -1.

Source

pub fn set_high_water(self: &DispatchIO, high_water: usize)

Set a high water mark on the I/O channel for all operations.

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.

The default value for the high water mark is unlimited (i.e. SIZE_MAX).

Parameter channel: The dispatch I/O channel on which to set the policy.

Parameter high_water: The number of bytes to use as a high water mark.

Source

pub fn set_low_water(self: &DispatchIO, low_water: usize)

Set a low water mark on the I/O channel for all operations.

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.

Parameter channel: The dispatch I/O channel on which to set the policy.

Parameter low_water: The number of bytes to use as a low water mark.

Source

pub fn set_interval( self: &DispatchIO, interval: u64, flags: DispatchIOIntervalFlags, )

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.

Parameter channel: The dispatch I/O channel on which to set the policy.

Parameter interval: The interval in nanoseconds at which delivery of the I/O handler is desired.

Parameter flags: Flags indicating desired data delivery behavior at interval time.