afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
152 lines
4.9 KiB
Groff
152 lines
4.9 KiB
Groff
.\" Copyright (c) 2010 Apple Inc. All rights reserved.
|
|
.Dd December 1, 2010
|
|
.Dt dispatch_io_read 3
|
|
.Os Darwin
|
|
.Sh NAME
|
|
.Nm dispatch_io_read ,
|
|
.Nm dispatch_io_write
|
|
.Nd submit read and write operations to dispatch I/O channels
|
|
.Sh SYNOPSIS
|
|
.Fd #include <dispatch/dispatch.h>
|
|
.Ft void
|
|
.Fo dispatch_io_read
|
|
.Fa "dispatch_io_t channel"
|
|
.Fa "off_t offset"
|
|
.Fa "size_t length"
|
|
.Fa "dispatch_queue_t queue"
|
|
.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_io_write
|
|
.Fa "dispatch_io_t channel"
|
|
.Fa "off_t offset"
|
|
.Fa "dispatch_data_t data"
|
|
.Fa "dispatch_queue_t queue"
|
|
.Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
|
|
.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 read from and write to dispatch I/O
|
|
channels. Creation and configuration of these channels is covered in the
|
|
.Xr dispatch_io_create 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.
|
|
.Pp
|
|
.Sh FUNDAMENTALS
|
|
The
|
|
.Fn dispatch_io_read
|
|
and
|
|
.Fn dispatch_io_write
|
|
functions are used to perform asynchronous read and write operations on
|
|
dispatch I/O channels. They can be thought of as asynchronous versions of the
|
|
.Xr fread 3
|
|
and
|
|
.Xr fwrite 3
|
|
functions in the standard C library.
|
|
.Sh READ OPERATIONS
|
|
The
|
|
.Fn dispatch_io_read
|
|
function schedules an I/O read operation on the specified dispatch I/O
|
|
.Va channel .
|
|
As results from the read operation become available, the provided
|
|
.Va handler
|
|
block will be submitted to the specified
|
|
.Va queue .
|
|
The block will be passed a dispatch data object representing the data that has
|
|
been read since the handler's previous invocation.
|
|
.Pp
|
|
The
|
|
.Va offset
|
|
parameter indicates where the read operation should begin. For a channel of
|
|
.Dv DISPATCH_IO_RANDOM
|
|
type it is interpreted relative to the position of the file pointer when the
|
|
channel was created, for a channel of
|
|
.Dv DISPATCH_IO_STREAM
|
|
type it is ignored and the read operation will begin at the current file
|
|
pointer position.
|
|
.Pp
|
|
The
|
|
.Va length
|
|
parameter indicates the number of bytes that should be read from the I/O
|
|
channel. Pass
|
|
.Dv SIZE_MAX
|
|
to keep reading until EOF is encountered (for a channel created from a
|
|
disk-based file this happens when reading past the end of the physical file).
|
|
.Sh WRITE OPERATIONS
|
|
The
|
|
.Fn dispatch_io_write
|
|
function schedules an I/O write operation on the specified dispatch I/O
|
|
.Va channel .
|
|
As the write operation progresses, the provided
|
|
.Va handler
|
|
block will be submitted to the specified
|
|
.Va queue .
|
|
The block will be passed a dispatch data object representing the data that
|
|
remains to be written as part of this I/O operation.
|
|
.Pp
|
|
The
|
|
.Va offset
|
|
parameter indicates where the write operation should begin. It is interpreted
|
|
as for read operations above.
|
|
.Pp
|
|
The
|
|
.Va data
|
|
parameter specifies the location and amount of data to be written, encapsulated
|
|
as a dispatch data object. The object is retained by the system until the write
|
|
operation is complete.
|
|
.Sh I/O HANDLER BLOCKS
|
|
Dispatch I/O handler blocks submitted to a channel via the
|
|
.Fn dispatch_io_read
|
|
or
|
|
.Fn dispatch_io_write
|
|
functions will be executed one or more times depending on system load and the
|
|
channel's configuration settings (see
|
|
.Xr dispatch_io_create 3
|
|
for details). The handler block need not be reentrant safe,
|
|
no new I/O handler instance is submitted until the previously enqueued handler
|
|
block has returned.
|
|
.Pp
|
|
The dispatch
|
|
.Va data
|
|
object passed to an I/O handler block will be released by the system when the
|
|
block returns, if access to the memory buffer it represents is needed outside
|
|
of the handler, the handler block must retain the data object or create a new
|
|
(e.g.\& concatenated) data object from it (see
|
|
.Xr dispatch_data_create 3
|
|
for details).
|
|
.Pp
|
|
Once an I/O handler block is invoked with the
|
|
.Va done
|
|
flag set, the associated I/O operation is complete and that handler block will
|
|
not be run again. If an unrecoverable error occurs while performing the I/O
|
|
operation, the handler block will be submitted with the
|
|
.Va done
|
|
flag set and the appropriate POSIX error code in the
|
|
.Va error
|
|
parameter. An invocation of a handler block with the
|
|
.Va done
|
|
flag set, zero
|
|
.Va error
|
|
and
|
|
.Va data
|
|
set to
|
|
.Vt dispatch_data_empty
|
|
indicates that the I/O operation has encountered EOF.
|
|
.Sh SEE ALSO
|
|
.Xr dispatch 3 ,
|
|
.Xr dispatch_data_create 3 ,
|
|
.Xr dispatch_io_create 3 ,
|
|
.Xr dispatch_read 3 ,
|
|
.Xr fread 3
|