-.\" Copyright (c) 2010 Apple Inc. All rights reserved.
+.\" Copyright (c) 2010-2013 Apple Inc. All rights reserved.
.Dd December 1, 2010
.Dt dispatch_io_create 3
.Os Darwin
.Nm dispatch_io_close ,
.Nm dispatch_io_set_high_water ,
.Nm dispatch_io_set_low_water ,
-.Nm dispatch_io_set_interval
+.Nm dispatch_io_set_interval ,
+.Nm dispatch_io_barrier
.Nd open, close and configure dispatch I/O channels
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Fa "uint64_t interval"
.Fa "dispatch_io_interval_flags_t flags"
.Fc
+.Ft void
+.Fo dispatch_io_barrier
+.Fa "dispatch_io_t channel"
+.Fa "void (^barrier)(void)"
+.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
.Fa type
from a file descriptor
.Fa fd
-or a pathname, respectively. They can be thought of as
-analogous to the
+or an absolute 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
+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
+when the first I/O operation on the channel is ready to execute.
+.Pp
+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
+when all I/O operations on the channel have completed and it 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
+parameter with the POSIX error encountered. If an invalid
+.Fa type
+or a non-absolute
+.Fa path
+argument is specified, these functions will return NULL and the
+.Fa cleanup_handler
+will not be invoked. After successfully 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"
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.
+.Pp
+.Sh BARRIER OPERATIONS
+The
+.Fn dispatch_io_barrier
+function schedules a barrier operation on an I/O channel. The specified barrier
+block will be run once, after all current I/O operations (such as
+.Xr read 2 or
+.Xr write 2 )
+on the underlying
+file descriptor have finished. No new I/O operations will start until the
+barrier block finishes.
+.Pp
+The barrier block may operate on the underlying file descriptor with functions
+like
+.Xr fsync 2
+or
+.Xr lseek 2 .
+As discussed in the
+.Sx FILEDESCRIPTOR OWNERSHIP
+section, the barrier block must not
+.Xr close 2
+the file descriptor, and if it changes any flags on the file descriptor, it
+must restore them before finishing.
+.Pp
+There is no synchronization between a barrier block and any
+.Xr dispatch_io_read 3
+or
+.Xr dispatch_io_write 3
+handler blocks; they may be running at the same time. The barrier block itself
+is responsible for any required synchronization.
.Sh MEMORY MODEL
Dispatch I/O channel objects are retained and released via calls to
.Fn dispatch_retain
projects / apple / libdispatch.git / blobdiff