X-Git-Url: https://git.saurik.com/apple/libdispatch.git/blobdiff_plain/00abc8588ccfc6d910a4ae103bbb45112e917d4c..e85f44377864e428703fb21503e29f422c11288f:/dispatch/io.h

diff --git a/dispatch/io.h b/dispatch/io.h
new file mode 100644
index 0000000..f8fb2ff
--- /dev/null
+++ b/dispatch/io.h
@@ -0,0 +1,586 @@
+/*
+ * Copyright (c) 2009-2010 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_IO__
+#define __DISPATCH_IO__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+__BEGIN_DECLS
+
+/*! @header
+ * 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 managment 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.
+ */
+
+/*!
+ * @typedef dispatch_fd_t
+ * Native file descriptor type for the platform.
+ */
+typedef int dispatch_fd_t;
+
+#ifdef __BLOCKS__
+
+/*!
+ * @functiongroup 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.
+ */
+
+/*!
+ * @function dispatch_read
+ * 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.
+ *
+ * @param fd		The file descriptor from which to read the data.
+ * @param 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.
+ * @param queue		The dispatch queue to which the handler should be
+ *			submitted.
+ * @param 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.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NONNULL4 DISPATCH_NOTHROW
+void
+dispatch_read(dispatch_fd_t fd,
+	size_t length,
+	dispatch_queue_t queue,
+	void (^handler)(dispatch_data_t data, int error));
+
+/*!
+ * @function dispatch_write
+ * 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.
+ *
+ * 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.
+ *
+ * @param fd		The file descriptor to which to write the data.
+ * @param data		The data object to write to the file descriptor.
+ * @param queue		The dispatch queue to which the handler should be
+ *			submitted.
+ * @param 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.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NONNULL4
+DISPATCH_NOTHROW
+void
+dispatch_write(dispatch_fd_t fd,
+	dispatch_data_t data,
+	dispatch_queue_t queue,
+	void (^handler)(dispatch_data_t data, int error));
+
+/*!
+ * @functiongroup Dispatch I/O Channel API
+ */
+
+/*!
+ * @typedef dispatch_io_t
+ * 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_DECL(dispatch_io);
+
+/*!
+ * @typedef dispatch_io_handler_t
+ * The prototype of I/O handler blocks for dispatch I/O operations.
+ *
+ * @param done		A flag indicating whether the operation is complete.
+ * @param data		The data object to be handled.
+ * @param error		An errno condition for the operation.
+ */
+typedef void (^dispatch_io_handler_t)(bool done, dispatch_data_t data,
+		int error);
+
+/*!
+ * @typedef dispatch_io_type_t
+ * The type of a dispatch I/O channel:
+ *
+ * @const 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 perfomed simultaneously.
+ * Offsets passed to operations on a channel of this type are ignored.
+ *
+ * @const 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.
+ */
+#define DISPATCH_IO_STREAM 0
+#define DISPATCH_IO_RANDOM 1
+
+typedef unsigned long dispatch_io_type_t;
+
+/*!
+ * @function dispatch_io_create
+ * 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.
+ *
+ * @param type	The desired type of I/O channel (DISPATCH_IO_STREAM
+ *		or DISPATCH_IO_RANDOM).
+ * @param fd	The file descriptor to associate with the I/O channel.
+ * @param queue	The dispatch queue to which the handler should be submitted.
+ * @param 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.
+ * @result	The newly created dispatch I/O channel or NULL if an error
+ *		occurred.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+dispatch_io_t
+dispatch_io_create(dispatch_io_type_t type,
+	dispatch_fd_t fd,
+	dispatch_queue_t queue,
+	void (^cleanup_handler)(int error));
+
+/*!
+* @function dispatch_io_create_with_path
+* 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.
+*
+* @param type	The desired type of I/O channel (DISPATCH_IO_STREAM
+*		or DISPATCH_IO_RANDOM).
+* @param path	The path to associate with the I/O channel.
+* @param oflag	The flags to pass to open(2) when opening the file at
+*		path.
+* @param mode	The mode to pass to open(2) when creating the file at
+*		path (i.e. with flag O_CREAT), zero otherwise.
+* @param queue	The dispatch queue to which the handler should be
+*		submitted.
+* @param 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.
+* @result	The newly created dispatch I/O channel or NULL if an error
+*		occurred.
+*/
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_NONNULL2 DISPATCH_WARN_RESULT
+DISPATCH_NOTHROW
+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));
+
+/*!
+ * @function dispatch_io_create_with_io
+ * 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.
+ *
+ * @param type	The desired type of I/O channel (DISPATCH_IO_STREAM
+ *		or DISPATCH_IO_RANDOM).
+ * @param io	The existing channel to create the new I/O channel from.
+ * @param queue	The dispatch queue to which the handler should be submitted.
+ * @param 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.
+ * @result	The newly created dispatch I/O channel or NULL if an error
+ *		occurred.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_MALLOC DISPATCH_WARN_RESULT
+DISPATCH_NOTHROW
+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));
+
+/*!
+ * @function dispatch_io_read
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel from which to read the data.
+ * @param offset	The offset relative to the channel position from which
+ *			to start reading (only for DISPATCH_IO_RANDOM).
+ * @param 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.
+ * @param queue		The dispatch queue to which the I/O handler should be
+ *			submitted.
+ * @param 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.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL4 DISPATCH_NONNULL5
+DISPATCH_NOTHROW
+void
+dispatch_io_read(dispatch_io_t channel,
+	off_t offset,
+	size_t length,
+	dispatch_queue_t queue,
+	dispatch_io_handler_t io_handler);
+
+/*!
+ * @function dispatch_io_write
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel on which to write the data.
+ * @param offset	The offset relative to the channel position from which
+ *			to start writing (only for DISPATCH_IO_RANDOM).
+ * @param 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.
+ * @param queue		The dispatch queue to which the I/O handler should be
+ *			submitted.
+ * @param 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.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NONNULL4
+DISPATCH_NONNULL5 DISPATCH_NOTHROW
+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);
+
+/*!
+ * @typedef dispatch_io_close_flags_t
+ * The type of flags you can set on a dispatch_io_close() call
+ *
+ * @const DISPATCH_IO_STOP	Stop outstanding operations on a channel when
+ *				the channel is closed.
+ */
+#define DISPATCH_IO_STOP 0x1
+
+typedef unsigned long dispatch_io_close_flags_t;
+
+/*!
+ * @function dispatch_io_close
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel to close.
+ * @param flags		The flags for the close operation.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_io_close(dispatch_io_t channel, dispatch_io_close_flags_t flags);
+
+/*!
+ * @function dispatch_io_barrier
+ * 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)).
+ *
+ * @param channel	The dispatch I/O channel to close.
+ * @param barrier	The flags for the close operation.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_io_barrier(dispatch_io_t channel, dispatch_block_t barrier);
+
+/*!
+ * @function dispatch_io_get_descriptor
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel to query.
+ * @result		The file descriptor underlying the channel, or -1.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+dispatch_fd_t
+dispatch_io_get_descriptor(dispatch_io_t channel);
+
+/*!
+ * @function dispatch_io_set_high_water
+ * 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).
+ *
+ * @param channel	The dispatch I/O channel on which to set the policy.
+ * @param high_water	The number of bytes to use as a high water mark.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_io_set_high_water(dispatch_io_t channel, size_t high_water);
+
+/*!
+ * @function dispatch_io_set_low_water
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel on which to set the policy.
+ * @param low_water	The number of bytes to use as a low water mark.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_io_set_low_water(dispatch_io_t channel, size_t low_water);
+
+/*!
+ * @typedef dispatch_io_interval_flags_t
+ * Type of flags to set on dispatch_io_set_interval()
+ *
+ * @const 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).
+ */
+#define DISPATCH_IO_STRICT_INTERVAL 0x1
+
+typedef unsigned long dispatch_io_interval_flags_t;
+
+/*!
+ * @function dispatch_io_set_interval
+ * 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.
+ *
+ * @param channel	The dispatch I/O channel on which to set the policy.
+ * @param interval	The interval in nanoseconds at which delivery of the I/O
+ *					handler is desired.
+ * @param flags		Flags indicating desired data delivery behavior at
+ *					interval time.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
+DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_io_set_interval(dispatch_io_t channel,
+	uint64_t interval,
+	dispatch_io_interval_flags_t flags);
+
+#endif /* __BLOCKS__ */
+
+__END_DECLS
+
+#endif /* __DISPATCH_IO__ */