]>
Commit | Line | Data |
---|---|---|
517da941 | 1 | .\" Copyright (c) 2010-2013 Apple Inc. All rights reserved. |
e85f4437 A |
2 | .Dd December 1, 2010 |
3 | .Dt dispatch_io_create 3 | |
4 | .Os Darwin | |
5 | .Sh NAME | |
6 | .Nm dispatch_io_create , | |
7 | .Nm dispatch_io_create_with_path , | |
8 | .Nm dispatch_io_close , | |
9 | .Nm dispatch_io_set_high_water , | |
10 | .Nm dispatch_io_set_low_water , | |
c093abd6 A |
11 | .Nm dispatch_io_set_interval , |
12 | .Nm dispatch_io_barrier | |
e85f4437 A |
13 | .Nd open, close and configure dispatch I/O channels |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <dispatch/dispatch.h> | |
16 | .Ft dispatch_io_t | |
17 | .Fo dispatch_io_create | |
18 | .Fa "dispatch_io_type_t type" | |
19 | .Fa "int fd" | |
20 | .Fa "dispatch_queue_t queue" | |
21 | .Fa "void (^cleanup_handler)(int error)" | |
22 | .Fc | |
23 | .Ft dispatch_io_t | |
24 | .Fo dispatch_io_create_with_path | |
25 | .Fa "dispatch_io_type_t type" | |
26 | .Fa "const char *path" | |
27 | .Fa "int oflag" | |
28 | .Fa "mode_t mode" | |
29 | .Fa "dispatch_queue_t queue" | |
30 | .Fa "void (^cleanup_handler)(int error)" | |
31 | .Fc | |
32 | .Ft void | |
33 | .Fo dispatch_io_close | |
34 | .Fa "dispatch_io_t channel" | |
35 | .Fa "dispatch_io_close_flags_t flags" | |
36 | .Fc | |
37 | .Ft void | |
38 | .Fo dispatch_io_set_high_water | |
39 | .Fa "dispatch_io_t channel" | |
40 | .Fa "size_t high_water" | |
41 | .Fc | |
42 | .Ft void | |
43 | .Fo dispatch_io_set_low_water | |
44 | .Fa "dispatch_io_t channel" | |
45 | .Fa "size_t low_water" | |
46 | .Fc | |
47 | .Ft void | |
48 | .Fo dispatch_io_set_interval | |
49 | .Fa "dispatch_io_t channel" | |
50 | .Fa "uint64_t interval" | |
51 | .Fa "dispatch_io_interval_flags_t flags" | |
52 | .Fc | |
c093abd6 A |
53 | .Ft void |
54 | .Fo dispatch_io_barrier | |
55 | .Fa "dispatch_io_t channel" | |
56 | .Fa "void (^barrier)(void)" | |
57 | .Fc | |
e85f4437 A |
58 | .Sh DESCRIPTION |
59 | The dispatch I/O framework is an API for asynchronous read and write I/O | |
60 | operations. It is an application of the ideas and idioms present in the | |
61 | .Xr dispatch 3 | |
62 | framework to device I/O. Dispatch I/O enables an application to more easily | |
63 | avoid blocking I/O operations and allows it to more directly express its I/O | |
64 | requirements than by using the raw POSIX file API. Dispatch I/O will make a | |
65 | best effort to optimize how and when asynchronous I/O operations are performed | |
66 | based on the capabilities of the targeted device. | |
67 | .Pp | |
68 | This page provides details on how to create and configure dispatch I/O | |
69 | channels. Reading from and writing to these channels is covered in the | |
70 | .Xr dispatch_io_read 3 | |
71 | page. The dispatch I/O framework also provides the convenience functions | |
72 | .Xr dispatch_read 3 | |
73 | and | |
74 | .Xr dispatch_write 3 | |
75 | for uses that do not require the full functionality provided by I/O channels. | |
76 | .Sh FUNDAMENTALS | |
77 | A dispatch I/O channel represents the asynchronous I/O policy applied to a file | |
78 | descriptor and encapsulates it for the purposes of ownership tracking while | |
79 | I/O operations are ongoing. | |
80 | .Sh CHANNEL TYPES | |
81 | Dispatch I/O channels can have one of the following types: | |
82 | .Bl -tag -width DISPATCH_IO_STREAM -compact -offset indent | |
83 | .It DISPATCH_IO_STREAM | |
84 | channels that represent a stream of bytes and do not support reads and writes | |
85 | at arbitrary offsets, such as pipes or sockets. Channels of this type perform | |
86 | read and write operations sequentially at the current file pointer position and | |
87 | ignore any offset specified. Depending on the underlying file descriptor, read | |
88 | operations may be performed simultaneously with write operations. | |
89 | .It DISPATCH_IO_RANDOM | |
90 | channels that represent random access files on disk. Only supported for | |
91 | seekable file descriptors and paths. Channels of this type may perform | |
92 | submitted read and write operations concurrently at the specified offset | |
93 | (interpreted relative to the position of the file pointer when the channel was | |
94 | created). | |
95 | .El | |
96 | .Sh CHANNEL OPENING AND CLOSING | |
97 | The | |
98 | .Fn dispatch_io_create | |
99 | and | |
100 | .Fn dispatch_io_create_with_path | |
101 | functions create a dispatch I/O channel of provided | |
102 | .Fa type | |
103 | from a file descriptor | |
104 | .Fa fd | |
517da941 A |
105 | or an absolute pathname, respectively. They can be thought of as analogous to |
106 | the | |
e85f4437 A |
107 | .Xr fdopen 3 |
108 | POSIX function and the | |
109 | .Xr fopen 3 | |
517da941 A |
110 | function in the standard C library. For a channel created from a pathname, the |
111 | provided | |
e85f4437 A |
112 | .Fa path , |
113 | .Fa oflag | |
114 | and | |
115 | .Fa mode | |
116 | parameters will be passed to | |
117 | .Xr open 2 | |
517da941 A |
118 | when the first I/O operation on the channel is ready to execute. |
119 | .Pp | |
120 | The provided | |
e85f4437 A |
121 | .Fa cleanup_handler |
122 | block will be submitted to the specified | |
123 | .Fa queue | |
517da941 | 124 | when all I/O operations on the channel have completed and it is closed or |
e85f4437 A |
125 | reaches the end of its lifecycle. If an error occurs during channel creation, |
126 | the | |
127 | .Fa cleanup_handler | |
128 | block will be submitted immediately and passed an | |
129 | .Fa error | |
517da941 A |
130 | parameter with the POSIX error encountered. If an invalid |
131 | .Fa type | |
132 | or a non-absolute | |
133 | .Fa path | |
134 | argument is specified, these functions will return NULL and the | |
135 | .Fa cleanup_handler | |
136 | will not be invoked. After successfully creating a dispatch I/O channel from a | |
137 | file descriptor, the application must take care not to modify that file | |
138 | descriptor until the associated | |
e85f4437 A |
139 | .Fa cleanup_handler |
140 | is invoked, see | |
141 | .Sx "FILEDESCRIPTOR OWNERSHIP" | |
142 | for details. | |
143 | .Pp | |
144 | The | |
145 | .Fn dispatch_io_close | |
146 | function closes a dispatch I/O channel to new submissions of I/O operations. If | |
147 | .Dv DISPATCH_IO_STOP | |
148 | is passed in the | |
149 | .Fa flags | |
150 | parameter, the system will in addition not perform the I/O operations already | |
151 | submitted to the channel that are still pending and will make a best effort to | |
152 | interrupt any ongoing operations. Handlers for operations so affected will be | |
153 | passed the | |
154 | .Er ECANCELED | |
155 | error code, along with any partial results. | |
156 | .Sh CHANNEL CONFIGURATION | |
157 | Dispatch I/O channels have high-water mark, low-water mark and interval | |
158 | configuration settings that determine if and when partial results from I/O | |
159 | operations are delivered via their associated I/O handlers. | |
160 | .Pp | |
161 | The | |
162 | .Fn dispatch_io_set_high_water | |
163 | and | |
164 | .Fn dispatch_io_set_low_water | |
165 | functions configure the water mark settings of a | |
166 | .Fa channel . | |
167 | The system will read | |
168 | or write at least the number of bytes specified by | |
169 | .Fa low_water | |
170 | before submitting an I/O handler with partial results, and will make a best | |
171 | effort to submit an I/O handler as soon as the number of bytes read or written | |
172 | reaches | |
173 | .Fa high_water . | |
174 | .Pp | |
175 | The | |
176 | .Fn dispatch_io_set_interval | |
177 | function configures the time | |
178 | .Fa interval | |
179 | at which I/O handlers are submitted (measured in nanoseconds). If | |
180 | .Dv DISPATCH_IO_STRICT_INTERVAL | |
181 | is passed in the | |
182 | .Fa flags | |
183 | parameter, the interval will be strictly observed even if there is an | |
184 | insufficient amount of data to deliver; otherwise delivery will be skipped for | |
185 | intervals where the amount of available data is inferior to the channel's | |
186 | low-water mark. Note that the system may defer enqueueing interval I/O handlers | |
187 | by a small unspecified amount of leeway in order to align with other system | |
188 | activity for improved system performance or power consumption. | |
189 | .Pp | |
190 | .Sh DATA DELIVERY | |
191 | The size of data objects passed to I/O handlers for a channel will never be | |
192 | larger than the high-water mark set on the channel; it will also never be | |
193 | smaller than the low-water mark, except in the following cases: | |
194 | .Bl -dash -offset indent -compact | |
195 | .It | |
196 | the final handler invocation for an I/O operation | |
197 | .It | |
198 | EOF was encountered | |
199 | .It | |
200 | the channel has an interval with the | |
201 | .Dv DISPATCH_IO_STRICT_INTERVAL | |
202 | flag set | |
203 | .El | |
204 | Bear in mind that dispatch I/O channels will typically deliver amounts of data | |
205 | significantly higher than the low-water mark. The default value for the | |
206 | low-water mark is unspecified, but must be assumed to allow intermediate | |
207 | handler invocations. The default value for the high-water mark is | |
208 | unlimited (i.e.\& | |
209 | .Dv SIZE_MAX ) . | |
210 | Channels that require intermediate results of fixed size should have both the | |
211 | low-water and the high-water mark set to that size. Channels that do not wish | |
212 | to receive any intermediate results should have the low-water mark set to | |
213 | .Dv SIZE_MAX . | |
214 | .Pp | |
215 | .Sh FILEDESCRIPTOR OWNERSHIP | |
216 | When an application creates a dispatch I/O channel from a file descriptor with | |
217 | the | |
218 | .Fn dispatch_io_create | |
219 | function, the system takes control of that file descriptor until the channel is | |
220 | closed, an error occurs on the file descriptor or all references to the channel | |
221 | are released. At that time the channel's cleanup handler will be enqueued and | |
222 | control over the file descriptor relinquished, making it safe for the | |
223 | application to | |
224 | .Xr close 2 | |
225 | the file descriptor. While a file descriptor is under the control of a dispatch | |
226 | I/O channel, file descriptor flags such as | |
227 | .Dv O_NONBLOCK | |
228 | will be modified by the system on behalf of the application. It is an error for | |
229 | the application to modify a file descriptor directly while it is under the | |
230 | control of a dispatch I/O channel, but it may create further I/O channels | |
231 | from that file descriptor or use the | |
232 | .Xr dispatch_read 3 | |
233 | and | |
234 | .Xr dispatch_write 3 | |
235 | convenience functions with that file descriptor. If multiple I/O channels have | |
236 | been created from the same file descriptor, all the associated cleanup handlers | |
237 | will be submitted together once the last channel has been closed resp.\& all | |
238 | references to those channels have been released. If convenience functions have | |
239 | also been used on that file descriptor, submission of their handlers will be | |
240 | tied to the submission of the channel cleanup handlers as well. | |
c093abd6 A |
241 | .Pp |
242 | .Sh BARRIER OPERATIONS | |
243 | The | |
244 | .Fn dispatch_io_barrier | |
245 | function schedules a barrier operation on an I/O channel. The specified barrier | |
246 | block will be run once, after all current I/O operations (such as | |
247 | .Xr read 2 or | |
248 | .Xr write 2 ) | |
249 | on the underlying | |
250 | file descriptor have finished. No new I/O operations will start until the | |
251 | barrier block finishes. | |
252 | .Pp | |
253 | The barrier block may operate on the underlying file descriptor with functions | |
254 | like | |
255 | .Xr fsync 2 | |
256 | or | |
257 | .Xr lseek 2 . | |
258 | As discussed in the | |
259 | .Sx FILEDESCRIPTOR OWNERSHIP | |
260 | section, the barrier block must not | |
261 | .Xr close 2 | |
262 | the file descriptor, and if it changes any flags on the file descriptor, it | |
263 | must restore them before finishing. | |
264 | .Pp | |
265 | There is no synchronization between a barrier block and any | |
266 | .Xr dispatch_io_read 3 | |
267 | or | |
268 | .Xr dispatch_io_write 3 | |
269 | handler blocks; they may be running at the same time. The barrier block itself | |
270 | is responsible for any required synchronization. | |
e85f4437 A |
271 | .Sh MEMORY MODEL |
272 | Dispatch I/O channel objects are retained and released via calls to | |
273 | .Fn dispatch_retain | |
274 | and | |
275 | .Fn dispatch_release . | |
276 | .Sh SEE ALSO | |
277 | .Xr dispatch 3 , | |
278 | .Xr dispatch_io_read 3 , | |
279 | .Xr dispatch_object 3 , | |
280 | .Xr dispatch_read 3 , | |
281 | .Xr fopen 3 , | |
282 | .Xr open 2 |