--- /dev/null
+.\" 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 dispatch"
+.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 appriate 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
projects / apple / libdispatch.git / blobdiff