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 March 1, 2016
  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 However, asynchronous I/O operations are only enabled for certain file
  41 types by default.
  42 Asynchronous I/O operations for other file types may block an AIO daemon
  43 indefinitely resulting in process and/or system hangs.
  44 Asynchronous I/O operations can be enabled for all file types by setting
  45 the
  46 .Va vfs.aio.enable_unsafe
  47 sysctl node to a non-zero value.
  48 .Pp
  49 Asynchronous I/O operations on sockets and raw disk devices do not block
  50 indefinitely and are enabled by default.
  51 .Pp
  52 The
  53 .Nm
  54 facility uses kernel processes
  55 (also known as AIO daemons)
  56 to service most asynchronous I/O requests.
  57 These processes are grouped into pools containing a variable number of
  58 processes.
  59 Each pool will add or remove processes to the pool based on load.
  60 Pools can be configured by sysctl nodes that define the minimum
  61 and maximum number of processes as well as the amount of time an idle
  62 process will wait before exiting.
  63 .Pp
  64 One pool of AIO daemons is used to service asynchronous I/O requests for
  65 sockets.
  66 These processes are named
  67 .Dq soaiod<N> .
  68 The following sysctl nodes are used with this pool:
  69 .Bl -tag -width indent
  70 .It Va kern.ipc.aio.num_procs
  71 The current number of processes in the pool.
  72 .It Va kern.ipc.aio.target_procs
  73 The minimum number of processes that should be present in the pool.
  74 .It Va kern.ipc.aio.max_procs
  75 The maximum number of processes permitted in the pool.
  76 .It Va kern.ipc.aio.lifetime
  77 The amount of time a process is permitted to idle in clock ticks.
  78 If a process is idle for this amount of time and there are more processes
  79 in the pool than the target minimum,
  80 the process will exit.
  81 .El
  82 .Pp
  83 A second pool of AIO daemons is used to service all other asynchronous I/O
  84 requests except for I/O requests to raw disks.
  85 These processes are named
  86 .Dq aiod<N> .
  87 The following sysctl nodes are used with this pool:
  88 .Bl -tag -width indent
  89 .It Va vfs.aio.num_aio_procs
  90 The current number of processes in the pool.
  91 .It Va vfs.aio.target_aio_procs
  92 The minimum number of processes that should be present in the pool.
  93 .It Va vfs.aio.max_aio_procs
  94 The maximum number of processes permitted in the pool.
  95 .It Va vfs.aio.aiod_lifetime
  96 The amount of time a process is permitted to idle in clock ticks.
  97 If a process is idle for this amount of time and there are more processes
  98 in the pool than the target minimum,
  99 the process will exit.
 100 .El
 101 .Pp
 102 Asynchronous I/O requests for raw disks are queued directly to the disk
 103 device layer after temporarily wiring the user pages associated with the
 104 request.
 105 These requests are not serviced by any of the AIO daemon pools.
 106 .Pp
 107 Several limits on the number of asynchronous I/O requests are imposed both
 108 system-wide and per-process.
 109 These limits are configured via the following sysctls:
 110 .Bl -tag -width indent
 111 .It Va vfs.aio.max_buf_aio
 112 The maximum number of queued asynchronous I/O requests for raw disks permitted
 113 for a single process.
 114 Asynchronous I/O requests that have completed but whose status has not been
 115 retrieved via
 116 .Xr aio_return 2
 117 or
 118 .Xr aio_waitcomplete 2
 119 are not counted against this limit.
 120 .It Va vfs.aio.num_buf_aio
 121 The number of queued asynchronous I/O requests for raw disks system-wide.
 122 .It Va vfs.aio.max_aio_queue_per_proc
 123 The maximum number of asynchronous I/O requests for a single process
 124 serviced concurrently by the default AIO daemon pool.
 125 .It Va vfs.aio.max_aio_per_proc
 126 The maximum number of outstanding asynchronous I/O requests permitted for a
 127 single process.
 128 This includes requests that have not been serviced,
 129 requests currently being serviced,
 130 and requests that have completed but whose status has not been retrieved via
 131 .Xr aio_return 2
 132 or
 133 .Xr aio_waitcomplete 2 .
 134 .It Va vfs.aio.num_queue_count
 135 The number of outstanding asynchronous I/O requests system-wide.
 136 .It Va vfs.aio.max_aio_queue
 137 The maximum number of outstanding asynchronous I/O requests permitted
 138 system-wide.
 139 .El
 140 .Sh SEE ALSO
 141 .Xr aio_cancel 2 ,
 142 .Xr aio_error 2 ,
 143 .Xr aio_read 2 ,
 144 .Xr aio_return 2 ,
 145 .Xr aio_suspend 2 ,
 146 .Xr aio_waitcomplete 2 ,
 147 .Xr aio_write 2 ,
 148 .Xr lio_listio 2 ,
 149 .Xr sysctl 8
 150 .Sh HISTORY
 151 The
 152 .Nm
 153 facility appeared as a kernel option in
 154 .Fx 3.0 .
 155 The
 156 .Nm
 157 kernel module appeared in
 158 .Fx 5.0 .
 159 The
 160 .Nm
 161 facility was integrated into all kernels in
 162 .Fx 11.0 .