share/man/man4/aio.4

   1 .\"-
   2 .\" Copyright (c) 2002 Dag-Erling Coïdan Smørgrav
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd June 22, 2017
  31 .Dt AIO 4
  32 .Os
  33 .Sh NAME
  34 .Nm aio
  35 .Nd asynchronous I/O
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 facility provides system calls for asynchronous I/O.
  40 Asynchronous I/O operations are not completed synchronously by the
  41 calling thread.
  42 Instead, the calling thread invokes one system call to request an
  43 asynchronous I/O operation.
  44 The status of a completed request is retrieved later via a separate
  45 system call.
  46 .Pp
  47 Asynchronous I/O operations on some file descriptor types may block an
  48 AIO daemon indefinitely resulting in process and/or system hangs.
  49 Operations on these file descriptor types are considered
  50 .Dq unsafe
  51 and disabled by default.
  52 They can be enabled by setting
  53 the
  54 .Va vfs.aio.enable_unsafe
  55 sysctl node to a non-zero value.
  56 .Pp
  57 Asynchronous I/O operations on sockets,
  58 raw disk devices,
  59 and regular files on local filesystems do not block
  60 indefinitely and are always enabled.
  61 .Pp
  62 The
  63 .Nm
  64 facility uses kernel processes
  65 (also known as AIO daemons)
  66 to service most asynchronous I/O requests.
  67 These processes are grouped into pools containing a variable number of
  68 processes.
  69 Each pool will add or remove processes to the pool based on load.
  70 Pools can be configured by sysctl nodes that define the minimum
  71 and maximum number of processes as well as the amount of time an idle
  72 process will wait before exiting.
  73 .Pp
  74 One pool of AIO daemons is used to service asynchronous I/O requests for
  75 sockets.
  76 These processes are named
  77 .Dq soaiod<N> .
  78 The following sysctl nodes are used with this pool:
  79 .Bl -tag -width indent
  80 .It Va kern.ipc.aio.num_procs
  81 The current number of processes in the pool.
  82 .It Va kern.ipc.aio.target_procs
  83 The minimum number of processes that should be present in the pool.
  84 .It Va kern.ipc.aio.max_procs
  85 The maximum number of processes permitted in the pool.
  86 .It Va kern.ipc.aio.lifetime
  87 The amount of time a process is permitted to idle in clock ticks.
  88 If a process is idle for this amount of time and there are more processes
  89 in the pool than the target minimum,
  90 the process will exit.
  91 .El
  92 .Pp
  93 A second pool of AIO daemons is used to service all other asynchronous I/O
  94 requests except for I/O requests to raw disks.
  95 These processes are named
  96 .Dq aiod<N> .
  97 The following sysctl nodes are used with this pool:
  98 .Bl -tag -width indent
  99 .It Va vfs.aio.num_aio_procs
 100 The current number of processes in the pool.
 101 .It Va vfs.aio.target_aio_procs
 102 The minimum number of processes that should be present in the pool.
 103 .It Va vfs.aio.max_aio_procs
 104 The maximum number of processes permitted in the pool.
 105 .It Va vfs.aio.aiod_lifetime
 106 The amount of time a process is permitted to idle in clock ticks.
 107 If a process is idle for this amount of time and there are more processes
 108 in the pool than the target minimum,
 109 the process will exit.
 110 .El
 111 .Pp
 112 Asynchronous I/O requests for raw disks are queued directly to the disk
 113 device layer after temporarily wiring the user pages associated with the
 114 request.
 115 These requests are not serviced by any of the AIO daemon pools.
 116 .Pp
 117 Several limits on the number of asynchronous I/O requests are imposed both
 118 system-wide and per-process.
 119 These limits are configured via the following sysctls:
 120 .Bl -tag -width indent
 121 .It Va vfs.aio.max_buf_aio
 122 The maximum number of queued asynchronous I/O requests for raw disks permitted
 123 for a single process.
 124 Asynchronous I/O requests that have completed but whose status has not been
 125 retrieved via
 126 .Xr aio_return 2
 127 or
 128 .Xr aio_waitcomplete 2
 129 are not counted against this limit.
 130 .It Va vfs.aio.num_buf_aio
 131 The number of queued asynchronous I/O requests for raw disks system-wide.
 132 .It Va vfs.aio.max_aio_queue_per_proc
 133 The maximum number of asynchronous I/O requests for a single process
 134 serviced concurrently by the default AIO daemon pool.
 135 .It Va vfs.aio.max_aio_per_proc
 136 The maximum number of outstanding asynchronous I/O requests permitted for a
 137 single process.
 138 This includes requests that have not been serviced,
 139 requests currently being serviced,
 140 and requests that have completed but whose status has not been retrieved via
 141 .Xr aio_return 2
 142 or
 143 .Xr aio_waitcomplete 2 .
 144 .It Va vfs.aio.num_queue_count
 145 The number of outstanding asynchronous I/O requests system-wide.
 146 .It Va vfs.aio.max_aio_queue
 147 The maximum number of outstanding asynchronous I/O requests permitted
 148 system-wide.
 149 .El
 150 .Pp
 151 Asynchronous I/O control buffers should be zeroed before initializing
 152 individual fields.
 153 This ensures all fields are initialized.
 154 .Pp
 155 All asynchronous I/O control buffers contain a
 156 .Vt sigevent
 157 structure in the
 158 .Va aio_sigevent
 159 field which can be used to request notification when an operation completes.
 160 .Pp
 161 For
 162 .Dv SIGEV_KEVENT
 163 notifications,
 164 the
 165 .Va sigevent
 166 .Ap
 167 s
 168 .Va sigev_notify_kqueue
 169 field should contain the descriptor of the kqueue that the event should be attached
 170 to, its
 171 .Va sigev_notify_kevent_flags
 172 field may contain
 173 .Dv EV_ONESHOT ,
 174 .Dv EV_CLEAR , and/or
 175 .Dv EV_DISPATCH , and its
 176 .Va sigev_notify
 177 field should be set to
 178 .Dv SIGEV_KEVENT .
 179 The posted kevent will contain:
 180 .Bl -column ".Va filter"
 181 .It Sy Member Ta Sy Value
 182 .It Va ident Ta asynchronous I/O control buffer pointer
 183 .It Va filter Ta Dv EVFILT_AIO
 184 .It Va flags Ta Dv EV_EOF
 185 .It Va udata Ta
 186 value stored in
 187 .Va aio_sigevent.sigev_value
 188 .El
 189 .Pp
 190 For
 191 .Dv SIGEV_SIGNO
 192 and
 193 .Dv SIGEV_THREAD_ID
 194 notifications,
 195 the information for the queued signal will include
 196 .Dv SI_ASYNCIO
 197 in the
 198 .Va si_code
 199 field and the value stored in
 200 .Va sigevent.sigev_value
 201 in the
 202 .Va si_value
 203 field.
 204 .Pp
 205 For
 206 .Dv SIGEV_THREAD
 207 notifications,
 208 the value stored in
 209 .Va aio_sigevent.sigev_value
 210 is passed to the
 211 .Va aio_sigevent.sigev_notify_function
 212 as described in
 213 .Xr sigevent 3 .
 214 .Sh SEE ALSO
 215 .Xr aio_cancel 2 ,
 216 .Xr aio_error 2 ,
 217 .Xr aio_read 2 ,
 218 .Xr aio_return 2 ,
 219 .Xr aio_suspend 2 ,
 220 .Xr aio_waitcomplete 2 ,
 221 .Xr aio_write 2 ,
 222 .Xr lio_listio 2 ,
 223 .Xr sigevent 3 ,
 224 .Xr sysctl 8
 225 .Sh HISTORY
 226 The
 227 .Nm
 228 facility appeared as a kernel option in
 229 .Fx 3.0 .
 230 The
 231 .Nm
 232 kernel module appeared in
 233 .Fx 5.0 .
 234 The
 235 .Nm
 236 facility was integrated into all kernels in
 237 .Fx 11.0 .