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