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