--- /dev/null
+.\" Copyright (c) 2010 Apple Inc. All rights reserved.
+.Dd December 1, 2010
+.Dt dispatch_io_create 3
+.Os Darwin
+.Sh NAME
+.Nm dispatch_io_create ,
+.Nm dispatch_io_create_with_path ,
+.Nm dispatch_io_close ,
+.Nm dispatch_io_set_high_water ,
+.Nm dispatch_io_set_low_water ,
+.Nm dispatch_io_set_interval
+.Nd open, close and configure dispatch I/O channels
+.Sh SYNOPSIS
+.Fd #include <dispatch/dispatch.h>
+.Ft dispatch_io_t
+.Fo dispatch_io_create
+.Fa "dispatch_io_type_t type"
+.Fa "int fd"
+.Fa "dispatch_queue_t queue"
+.Fa "void (^cleanup_handler)(int error)"
+.Fc
+.Ft dispatch_io_t
+.Fo dispatch_io_create_with_path
+.Fa "dispatch_io_type_t type"
+.Fa "const char *path"
+.Fa "int oflag"
+.Fa "mode_t mode"
+.Fa "dispatch_queue_t queue"
+.Fa "void (^cleanup_handler)(int error)"
+.Fc
+.Ft void
+.Fo dispatch_io_close
+.Fa "dispatch_io_t channel"
+.Fa "dispatch_io_close_flags_t flags"
+.Fc
+.Ft void
+.Fo dispatch_io_set_high_water
+.Fa "dispatch_io_t channel"
+.Fa "size_t high_water"
+.Fc
+.Ft void
+.Fo dispatch_io_set_low_water
+.Fa "dispatch_io_t channel"
+.Fa "size_t low_water"
+.Fc
+.Ft void
+.Fo dispatch_io_set_interval
+.Fa "dispatch_io_t channel"
+.Fa "uint64_t interval"
+.Fa "dispatch_io_interval_flags_t flags"
+.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 create and configure dispatch I/O
+channels. Reading from and writing to these channels is covered in the
+.Xr dispatch_io_read 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.
+.Sh FUNDAMENTALS
+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.
+.Sh CHANNEL TYPES
+Dispatch I/O channels can have one of the following types:
+.Bl -tag -width DISPATCH_IO_STREAM -compact -offset indent
+.It DISPATCH_IO_STREAM
+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.
+.It DISPATCH_IO_RANDOM
+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).
+.El
+.Sh CHANNEL OPENING AND CLOSING
+The
+.Fn dispatch_io_create
+and
+.Fn dispatch_io_create_with_path
+functions create a dispatch I/O channel of provided
+.Fa type
+from a file descriptor
+.Fa fd
+or a pathname, respectively. They can be thought of as
+analogous to the
+.Xr fdopen 3
+POSIX function and the
+.Xr fopen 3
+function in the standard C library. For a channel created from a
+pathname, the provided
+.Fa path ,
+.Fa oflag
+and
+.Fa mode
+parameters will be passed to
+.Xr open 2
+when the first I/O operation on the channel is ready to execute. The provided
+.Fa cleanup_handler
+block will be submitted to the specified
+.Fa queue
+when all I/O operations on the channel have completed and is is closed or
+reaches the end of its lifecycle. If an error occurs during channel creation,
+the
+.Fa cleanup_handler
+block will be submitted immediately and passed an
+.Fa error
+parameter with the POSIX error encountered. After creating a dispatch I/O
+channel from a file descriptor, the application must take care not to modify
+that file descriptor until the associated
+.Fa cleanup_handler
+is invoked, see
+.Sx "FILEDESCRIPTOR OWNERSHIP"
+for details.
+.Pp
+The
+.Fn dispatch_io_close
+function closes a dispatch I/O channel to new submissions of I/O operations. If
+.Dv DISPATCH_IO_STOP
+is passed in the
+.Fa flags
+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
+.Er ECANCELED
+error code, along with any partial results.
+.Sh CHANNEL CONFIGURATION
+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.
+.Pp
+The
+.Fn dispatch_io_set_high_water
+and
+.Fn dispatch_io_set_low_water
+functions configure the water mark settings of a
+.Fa channel .
+The system will read
+or write at least the number of bytes specified by
+.Fa low_water
+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
+.Fa high_water .
+.Pp
+The
+.Fn dispatch_io_set_interval
+function configures the time
+.Fa interval
+at which I/O handlers are submitted (measured in nanoseconds). If
+.Dv DISPATCH_IO_STRICT_INTERVAL
+is passed in the
+.Fa flags
+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.
+.Pp
+.Sh DATA DELIVERY
+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:
+.Bl -dash -offset indent -compact
+.It
+the final handler invocation for an I/O operation
+.It
+EOF was encountered
+.It
+the channel has an interval with the
+.Dv DISPATCH_IO_STRICT_INTERVAL
+flag set
+.El
+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.\&
+.Dv SIZE_MAX ) .
+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
+.Dv SIZE_MAX .
+.Pp
+.Sh FILEDESCRIPTOR OWNERSHIP
+When an application creates a dispatch I/O channel from a file descriptor with
+the
+.Fn dispatch_io_create
+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
+.Xr close 2
+the file descriptor. While a file descriptor is under the control of a dispatch
+I/O channel, file descriptor flags such as
+.Dv 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 further I/O channels
+from that file descriptor or use the
+.Xr dispatch_read 3
+and
+.Xr dispatch_write 3
+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.
+.Sh MEMORY MODEL
+Dispatch I/O channel objects are retained and released via calls to
+.Fn dispatch_retain
+and
+.Fn dispatch_release .
+.Sh SEE ALSO
+.Xr dispatch 3 ,
+.Xr dispatch_io_read 3 ,
+.Xr dispatch_object 3 ,
+.Xr dispatch_read 3 ,
+.Xr fopen 3 ,
+.Xr open 2
projects / apple / libdispatch.git / blobdiff