man/dispatch_io_create.3

   1 .\" Copyright (c) 2010 Apple Inc. All rights reserved.
   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 ,
  11 .Nm dispatch_io_set_interval ,
  12 .Nm dispatch_io_barrier
  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
  53 .Ft void
  54 .Fo dispatch_io_barrier
  55 .Fa "dispatch_io_t channel"
  56 .Fa "void (^barrier)(void)"
  57 .Fc
  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
 105 or a pathname, respectively. They can be thought of as
 106 analogous to the
 107 .Xr fdopen 3
 108 POSIX function and the
 109 .Xr fopen 3
 110 function in the standard C library. For a channel created from a
 111 pathname, the provided
 112 .Fa path ,
 113 .Fa oflag
 114 and
 115 .Fa mode
 116 parameters will be passed to
 117 .Xr open 2
 118 when the first I/O operation on the channel is ready to execute. The provided
 119 .Fa cleanup_handler
 120 block will be submitted to the specified
 121 .Fa queue
 122 when all I/O operations on the channel have completed and is is closed or
 123 reaches the end of its lifecycle. If an error occurs during channel creation,
 124 the
 125 .Fa cleanup_handler
 126 block will be submitted immediately and passed an
 127 .Fa error
 128 parameter with the POSIX error encountered. After creating a dispatch I/O
 129 channel from a file descriptor, the application must take care not to modify
 130 that file descriptor until the associated
 131 .Fa cleanup_handler
 132 is invoked, see
 133 .Sx "FILEDESCRIPTOR OWNERSHIP"
 134 for details.
 135 .Pp
 136 The
 137 .Fn dispatch_io_close
 138 function closes a dispatch I/O channel to new submissions of I/O operations. If
 139 .Dv DISPATCH_IO_STOP
 140 is passed in the
 141 .Fa flags
 142 parameter, the system will in addition not perform the I/O operations already
 143 submitted to the channel that are still pending and will make a best effort to
 144 interrupt any ongoing operations. Handlers for operations so affected will be
 145 passed the
 146 .Er ECANCELED
 147 error code, along with any partial results.
 148 .Sh CHANNEL CONFIGURATION
 149 Dispatch I/O channels have high-water mark, low-water mark and interval
 150 configuration settings that determine if and when partial results from I/O
 151 operations are delivered via their associated I/O handlers.
 152 .Pp
 153 The
 154 .Fn dispatch_io_set_high_water
 155 and
 156 .Fn dispatch_io_set_low_water
 157 functions configure the water mark settings of a
 158 .Fa channel .
 159 The system will read
 160 or write at least the number of bytes specified by
 161 .Fa low_water
 162 before submitting an I/O handler with partial results, and will make a best
 163 effort to submit an I/O handler as soon as the number of bytes read or written
 164 reaches
 165 .Fa high_water .
 166 .Pp
 167 The
 168 .Fn dispatch_io_set_interval
 169 function configures the time
 170 .Fa interval
 171 at which I/O handlers are submitted (measured in nanoseconds). If
 172 .Dv DISPATCH_IO_STRICT_INTERVAL
 173 is passed in the
 174 .Fa flags
 175 parameter, the interval will be strictly observed even if there is an
 176 insufficient amount of data to deliver; otherwise delivery will be skipped for
 177 intervals where the amount of available data is inferior to the channel's
 178 low-water mark. Note that the system may defer enqueueing interval I/O handlers
 179 by a small unspecified amount of leeway in order to align with other system
 180 activity for improved system performance or power consumption.
 181 .Pp
 182 .Sh DATA DELIVERY
 183 The size of data objects passed to I/O handlers for a channel will never be
 184 larger than the high-water mark set on the channel; it will also never be
 185 smaller than the low-water mark, except in the following cases:
 186 .Bl -dash -offset indent -compact
 187 .It
 188 the final handler invocation for an I/O operation
 189 .It
 190 EOF was encountered
 191 .It
 192 the channel has an interval with the
 193 .Dv DISPATCH_IO_STRICT_INTERVAL
 194 flag set
 195 .El
 196 Bear in mind that dispatch I/O channels will typically deliver amounts of data
 197 significantly higher than the low-water mark. The default value for the
 198 low-water mark is unspecified, but must be assumed to allow intermediate
 199 handler invocations. The default value for the high-water mark is
 200 unlimited (i.e.\&
 201 .Dv SIZE_MAX ) .
 202 Channels that require intermediate results of fixed size should have both the
 203 low-water and the high-water mark set to that size. Channels that do not wish
 204 to receive any intermediate results should have the low-water mark set to
 205 .Dv SIZE_MAX .
 206 .Pp
 207 .Sh FILEDESCRIPTOR OWNERSHIP
 208 When an application creates a dispatch I/O channel from a file descriptor with
 209 the
 210 .Fn dispatch_io_create
 211 function, the system takes control of that file descriptor until the channel is
 212 closed, an error occurs on the file descriptor or all references to the channel
 213 are released. At that time the channel's cleanup handler will be enqueued and
 214 control over the file descriptor relinquished, making it safe for the
 215 application to
 216 .Xr close 2
 217 the file descriptor. While a file descriptor is under the control of a dispatch
 218 I/O channel, file descriptor flags such as
 219 .Dv O_NONBLOCK
 220 will be modified by the system on behalf of the application. It is an error for
 221 the application to modify a file descriptor directly while it is under the
 222 control of a dispatch I/O channel, but it may create further I/O channels
 223 from that file descriptor or use the
 224 .Xr dispatch_read 3
 225 and
 226 .Xr dispatch_write 3
 227 convenience functions with that file descriptor. If multiple I/O channels have
 228 been created from the same file descriptor, all the associated cleanup handlers
 229 will be submitted together once the last channel has been closed resp.\& all
 230 references to those channels have been released. If convenience functions have
 231 also been used on that file descriptor, submission of their handlers will be
 232 tied to the submission of the channel cleanup handlers as well.
 233 .Pp
 234 .Sh BARRIER OPERATIONS
 235 The
 236 .Fn dispatch_io_barrier
 237 function schedules a barrier operation on an I/O channel. The specified barrier
 238 block will be run once, after all current I/O operations (such as
 239 .Xr read 2 or
 240 .Xr write 2 )
 241 on the underlying
 242 file descriptor have finished. No new I/O operations will start until the
 243 barrier block finishes.
 244 .Pp
 245 The barrier block may operate on the underlying file descriptor with functions
 246 like
 247 .Xr fsync 2
 248 or
 249 .Xr lseek 2 .
 250 As discussed in the
 251 .Sx FILEDESCRIPTOR OWNERSHIP
 252 section, the barrier block must not
 253 .Xr close 2
 254 the file descriptor, and if it changes any flags on the file descriptor, it
 255 must restore them before finishing.
 256 .Pp
 257 There is no synchronization between a barrier block and any
 258 .Xr dispatch_io_read 3
 259 or
 260 .Xr dispatch_io_write 3
 261 handler blocks; they may be running at the same time. The barrier block itself
 262 is responsible for any required synchronization.
 263 .Sh MEMORY MODEL
 264 Dispatch I/O channel objects are retained and released via calls to
 265 .Fn dispatch_retain
 266 and
 267 .Fn dispatch_release .
 268 .Sh SEE ALSO
 269 .Xr dispatch 3 ,
 270 .Xr dispatch_io_read 3 ,
 271 .Xr dispatch_object 3 ,
 272 .Xr dispatch_read 3 ,
 273 .Xr fopen 3 ,
 274 .Xr open 2