1dispatch_io_create(3)    BSD Library Functions Manual    dispatch_io_create(3)
2

NAME

4     dispatch_io_create, dispatch_io_create_with_path, dispatch_io_close,
5     dispatch_io_set_high_water, dispatch_io_set_low_water,
6     dispatch_io_set_interval, dispatch_io_barrier — open, close and configure
7     dispatch I/O channels
8

SYNOPSIS

10     #include <dispatch/dispatch.h>
11
12     dispatch_io_t
13     dispatch_io_create(dispatch_io_type_t type, int fd,
14         dispatch_queue_t queue, void (^cleanup_handler)(int error));
15
16     dispatch_io_t
17     dispatch_io_create_with_path(dispatch_io_type_t type, const char *path,
18         int oflag, mode_t mode, dispatch_queue_t queue,
19         void (^cleanup_handler)(int error));
20
21     void
22     dispatch_io_close(dispatch_io_t channel,
23         dispatch_io_close_flags_t flags);
24
25     void
26     dispatch_io_set_high_water(dispatch_io_t channel, size_t high_water);
27
28     void
29     dispatch_io_set_low_water(dispatch_io_t channel, size_t low_water);
30
31     void
32     dispatch_io_set_interval(dispatch_io_t channel, uint64_t interval,
33         dispatch_io_interval_flags_t flags);
34
35     void
36     dispatch_io_barrier(dispatch_io_t channel, void (^barrier)(void));
37

DESCRIPTION

39     The dispatch I/O framework is an API for asynchronous read and write I/O
40     operations. It is an application of the ideas and idioms present in the
41     dispatch(3) framework to device I/O. Dispatch I/O enables an application
42     to more easily avoid blocking I/O operations and allows it to more
43     directly express its I/O requirements than by using the raw POSIX file
44     API. Dispatch I/O will make a best effort to optimize how and when asyn‐
45     chronous I/O operations are performed based on the capabilities of the
46     targeted device.
47
48     This page provides details on how to create and configure dispatch I/O
49     channels. Reading from and writing to these channels is covered in the
50     dispatch_io_read(3) page. The dispatch I/O framework also provides the
51     convenience functions dispatch_read(3) and dispatch_write(3) for uses
52     that do not require the full functionality provided by I/O channels.
53

FUNDAMENTALS

55     A dispatch I/O channel represents the asynchronous I/O policy applied to
56     a file descriptor and encapsulates it for the purposes of ownership
57     tracking while I/O operations are ongoing.
58

CHANNEL TYPES

60     Dispatch I/O channels can have one of the following types:
61           DISPATCH_IO_STREAM  channels that represent a stream of bytes and
62                               do not support reads and writes at arbitrary
63                               offsets, such as pipes or sockets. Channels of
64                               this type perform read and write operations
65                               sequentially at the current file pointer posi‐
66                               tion and ignore any offset specified. Depending
67                               on the underlying file descriptor, read opera‐
68                               tions may be performed simultaneously with
69                               write operations.
70           DISPATCH_IO_RANDOM  channels that represent random access files on
71                               disk. Only supported for seekable file descrip‐
72                               tors and paths. Channels of this type may per‐
73                               form submitted read and write operations con‐
74                               currently at the specified offset (interpreted
75                               relative to the position of the file pointer
76                               when the channel was created).
77

CHANNEL OPENING AND CLOSING

79     The dispatch_io_create() and dispatch_io_create_with_path() functions
80     create a dispatch I/O channel of provided type from a file descriptor fd
81     or an absolute pathname, respectively. They can be thought of as analo‐
82     gous to the fdopen(3) POSIX function and the fopen(3) function in the
83     standard C library. For a channel created from a pathname, the provided
84     path, oflag and mode parameters will be passed to open(2) when the first
85     I/O operation on the channel is ready to execute.
86
87     The provided cleanup_handler block will be submitted to the specified
88     queue when all I/O operations on the channel have completed and it is
89     closed or reaches the end of its lifecycle. If an error occurs during
90     channel creation, the cleanup_handler block will be submitted immediately
91     and passed an error parameter with the POSIX error encountered. If an
92     invalid type or a non-absolute path argument is specified, these func‐
93     tions will return NULL and the cleanup_handler will not be invoked. After
94     successfully creating a dispatch I/O channel from a file descriptor, the
95     application must take care not to modify that file descriptor until the
96     associated cleanup_handler is invoked, see FILEDESCRIPTOR OWNERSHIP for
97     details.
98
99     The dispatch_io_close() function closes a dispatch I/O channel to new
100     submissions of I/O operations. If DISPATCH_IO_STOP is passed in the flags
101     parameter, the system will in addition not perform the I/O operations
102     already submitted to the channel that are still pending and will make a
103     best effort to interrupt any ongoing operations. Handlers for operations
104     so affected will be passed the ECANCELED error code, along with any par‐
105     tial results.
106

CHANNEL CONFIGURATION

108     Dispatch I/O channels have high-water mark, low-water mark and interval
109     configuration settings that determine if and when partial results from
110     I/O operations are delivered via their associated I/O handlers.
111
112     The dispatch_io_set_high_water() and dispatch_io_set_low_water() func‐
113     tions configure the water mark settings of a channel.  The system will
114     read or write at least the number of bytes specified by low_water before
115     submitting an I/O handler with partial results, and will make a best
116     effort to submit an I/O handler as soon as the number of bytes read or
117     written reaches high_water.
118
119     The dispatch_io_set_interval() function configures the time interval at
120     which I/O handlers are submitted (measured in nanoseconds). If
121     DISPATCH_IO_STRICT_INTERVAL is passed in the flags parameter, the inter‐
122     val will be strictly observed even if there is an insufficient amount of
123     data to deliver; otherwise delivery will be skipped for intervals where
124     the amount of available data is inferior to the channel's low-water mark.
125     Note that the system may defer enqueueing interval I/O handlers by a
126     small unspecified amount of leeway in order to align with other system
127     activity for improved system performance or power consumption.
128

DATA DELIVERY

130     The size of data objects passed to I/O handlers for a channel will never
131     be larger than the high-water mark set on the channel; it will also never
132     be smaller than the low-water mark, except in the following cases:
133           -   the final handler invocation for an I/O operation
134           -   EOF was encountered
135           -   the channel has an interval with the
136               DISPATCH_IO_STRICT_INTERVAL flag set
137     Bear in mind that dispatch I/O channels will typically deliver amounts of
138     data significantly higher than the low-water mark. The default value for
139     the low-water mark is unspecified, but must be assumed to allow interme‐
140     diate handler invocations. The default value for the high-water mark is
141     unlimited (i.e. SIZE_MAX).  Channels that require intermediate results of
142     fixed size should have both the low-water and the high-water mark set to
143     that size. Channels that do not wish to receive any intermediate results
144     should have the low-water mark set to SIZE_MAX.
145

FILEDESCRIPTOR OWNERSHIP

147     When an application creates a dispatch I/O channel from a file descriptor
148     with the dispatch_io_create() function, the system takes control of that
149     file descriptor until the channel is closed, an error occurs on the file
150     descriptor or all references to the channel are released. At that time
151     the channel's cleanup handler will be enqueued and control over the file
152     descriptor relinquished, making it safe for the application to close(2)
153     the file descriptor. While a file descriptor is under the control of a
154     dispatch I/O channel, file descriptor flags such as O_NONBLOCK will be
155     modified by the system on behalf of the application. It is an error for
156     the application to modify a file descriptor directly while it is under
157     the control of a dispatch I/O channel, but it may create further I/O
158     channels from that file descriptor or use the dispatch_read(3) and
159     dispatch_write(3) convenience functions with that file descriptor. If
160     multiple I/O channels have been created from the same file descriptor,
161     all the associated cleanup handlers will be submitted together once the
162     last channel has been closed resp. all references to those channels have
163     been released. If convenience functions have also been used on that file
164     descriptor, submission of their handlers will be tied to the submission
165     of the channel cleanup handlers as well.
166

BARRIER OPERATIONS

168     The dispatch_io_barrier() function schedules a barrier operation on an
169     I/O channel. The specified barrier block will be run once, after all cur‐
170     rent I/O operations (such as read(2) or write(2)) on the underlying file
171     descriptor have finished. No new I/O operations will start until the bar‐
172     rier block finishes.
173
174     The barrier block may operate on the underlying file descriptor with
175     functions like fsync(2) or lseek(2).  As discussed in the FILEDESCRIPTOR
176     OWNERSHIP section, the barrier block must not close(2) the file descrip‐
177     tor, and if it changes any flags on the file descriptor, it must restore
178     them before finishing.
179
180     There is no synchronization between a barrier block and any
181     dispatch_io_read(3) or dispatch_io_write(3) handler blocks; they may be
182     running at the same time. The barrier block itself is responsible for any
183     required synchronization.
184

MEMORY MODEL

186     Dispatch I/O channel objects are retained and released via calls to
187     dispatch_retain() and dispatch_release().
188

SEE ALSO

190     dispatch(3), dispatch_io_read(3), dispatch_object(3), dispatch_read(3),
191     fopen(3), open(2)
192
193Darwin                         December 1, 2010                         Darwin
Impressum