man/dispatch_io_create.3

   1 .\" Copyright (c) 2010-2013 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 an absolute pathname, respectively. They can be thought of as analogous to
 106 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 pathname, the
 111 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.
 119 .Pp
 120 The provided
 121 .Fa cleanup_handler
 122 block will be submitted to the specified
 123 .Fa queue
 124 when all I/O operations on the channel have completed and it is closed or
 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
 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
 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.
 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.
 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