man/dispatch_io_read.3

   1 .\" Copyright (c) 2010 Apple Inc. All rights reserved.
   2 .Dd December 1, 2010
   3 .Dt dispatch_io_read 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_io_read ,
   7 .Nm dispatch_io_write
   8 .Nd submit read and write operations to dispatch I/O channels
   9 .Sh SYNOPSIS
  10 .Fd #include <dispatch/dispatch.h>
  11 .Ft void
  12 .Fo dispatch_io_read
  13 .Fa "dispatch_io_t channel"
  14 .Fa "off_t offset"
  15 .Fa "size_t length"
  16 .Fa "dispatch_queue_t queue"
  17 .Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
  18 .Fc
  19 .Ft void
  20 .Fo dispatch_io_write
  21 .Fa "dispatch_io_t channel"
  22 .Fa "off_t offset"
  23 .Fa "dispatch_data_t dispatch"
  24 .Fa "dispatch_queue_t queue"
  25 .Fa "void (^handler)(bool done, dispatch_data_t data, int error)"
  26 .Fc
  27 .Sh DESCRIPTION
  28 The dispatch I/O framework is an API for asynchronous read and write I/O
  29 operations. It is an application of the ideas and idioms present in the
  30 .Xr dispatch 3
  31 framework to device I/O. Dispatch I/O enables an application to more easily
  32 avoid blocking I/O operations and allows it to more directly express its I/O
  33 requirements than by using the raw POSIX file API. Dispatch I/O will make a
  34 best effort to optimize how and when asynchronous I/O operations are performed
  35 based on the capabilities of the targeted device.
  36 .Pp
  37 This page provides details on how to read from and write to dispatch I/O
  38 channels. Creation and configuration of these channels is covered in the
  39 .Xr dispatch_io_create 3
  40 page. The dispatch I/O framework also provides the convenience functions
  41 .Xr dispatch_read 3
  42 and
  43 .Xr dispatch_write 3
  44 for uses that do not require the full functionality provided by I/O channels.
  45 .Pp
  46 .Sh FUNDAMENTALS
  47 The
  48 .Fn dispatch_io_read
  49 and
  50 .Fn dispatch_io_write
  51 functions are used to perform asynchronous read and write operations on
  52 dispatch I/O channels. They can be thought of as asynchronous versions of the
  53 .Xr fread 3
  54 and
  55 .Xr fwrite 3
  56 functions in the standard C library.
  57 .Sh READ OPERATIONS
  58 The
  59 .Fn dispatch_io_read
  60 function schedules an I/O read operation on the specified dispatch I/O
  61 .Va channel .
  62 As results from the read operation become available, the provided
  63 .Va handler
  64 block will be submitted to the specified
  65 .Va queue .
  66 The block will be passed a dispatch data object representing the data that has
  67 been read since the handler's previous invocation.
  68 .Pp
  69 The
  70 .Va offset
  71 parameter indicates where the read operation should begin. For a channel of
  72 .Dv DISPATCH_IO_RANDOM
  73 type it is interpreted relative to the position of the file pointer when the
  74 channel was created, for a channel of
  75 .Dv DISPATCH_IO_STREAM
  76 type it is ignored and the read operation will begin at the current file
  77 pointer position.
  78 .Pp
  79 The
  80 .Va length
  81 parameter indicates the number of bytes that should be read from the I/O
  82 channel. Pass
  83 .Dv SIZE_MAX
  84 to keep reading until EOF is encountered (for a channel created from a
  85 disk-based file this happens when reading past the end of the physical file).
  86 .Sh WRITE OPERATIONS
  87 The
  88 .Fn dispatch_io_write
  89 function schedules an I/O write operation on the specified dispatch I/O
  90 .Va channel .
  91 As the write operation progresses, the provided
  92 .Va handler
  93 block will be submitted to the specified
  94 .Va queue .
  95 The block will be passed a dispatch data object representing the data that
  96 remains to be written as part of this I/O operation.
  97 .Pp
  98 The
  99 .Va offset
 100 parameter indicates where the write operation should begin. It is interpreted
 101 as for read operations above.
 102 .Pp
 103 The
 104 .Va data
 105 parameter specifies the location and amount of data to be written, encapsulated
 106 as a dispatch data object. The object is retained by the system until the write
 107 operation is complete.
 108 .Sh I/O HANDLER BLOCKS
 109 Dispatch I/O handler blocks submitted to a channel via the
 110 .Fn dispatch_io_read
 111 or
 112 .Fn dispatch_io_write
 113 functions will be executed one or more times depending on system load and the
 114 channel's configuration settings (see
 115 .Xr dispatch_io_create 3
 116 for details). The handler block need not be reentrant safe,
 117 no new I/O handler instance is submitted until the previously enqueued handler
 118 block has returned.
 119 .Pp
 120 The dispatch
 121 .Va data
 122 object passed to an I/O handler block will be released by the system when the
 123 block returns, if access to the memory buffer it represents is needed outside
 124 of the handler, the handler block must retain the data object or create a new
 125 (e.g.\& concatenated) data object from it (see
 126 .Xr dispatch_data_create 3
 127 for details).
 128 .Pp
 129 Once an I/O handler block is invoked with the
 130 .Va done
 131 flag set, the associated I/O operation is complete and that handler block will
 132 not be run again. If an unrecoverable error occurs while performing the I/O
 133 operation, the handler block will be submitted with the
 134 .Va done
 135 flag set and the appriate POSIX error code in the
 136 .Va error
 137 parameter. An invocation of a handler block with the
 138 .Va done
 139 flag set, zero
 140 .Va error
 141 and
 142 .Va data
 143 set to
 144 .Vt dispatch_data_empty
 145 indicates that the I/O operation has encountered EOF.
 146 .Sh SEE ALSO
 147 .Xr dispatch 3 ,
 148 .Xr dispatch_data_create 3 ,
 149 .Xr dispatch_io_create 3 ,
 150 .Xr dispatch_read 3 ,
 151 .Xr fread 3