1.\"- 2.\" Copyright (c) 2002 Dag-Erling 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.Dd January 2, 2021 29.Dt AIO 4 30.Os 31.Sh NAME 32.Nm aio 33.Nd asynchronous I/O 34.Sh DESCRIPTION 35The 36.Nm 37facility provides system calls for asynchronous I/O. 38Asynchronous I/O operations are not completed synchronously by the 39calling thread. 40Instead, the calling thread invokes one system call to request an 41asynchronous I/O operation. 42The status of a completed request is retrieved later via a separate 43system call. 44.Pp 45Asynchronous I/O operations on some file descriptor types may block an 46AIO daemon indefinitely resulting in process and/or system hangs. 47Operations on these file descriptor types are considered 48.Dq unsafe 49and disabled by default. 50They can be enabled by setting 51the 52.Va vfs.aio.enable_unsafe 53sysctl node to a non-zero value. 54.Pp 55Asynchronous I/O operations on sockets, 56raw disk devices, 57and regular files on local filesystems do not block 58indefinitely and are always enabled. 59.Pp 60The 61.Nm 62facility uses kernel processes 63(also known as AIO daemons) 64to service most asynchronous I/O requests. 65These processes are grouped into pools containing a variable number of 66processes. 67Each pool will add or remove processes to the pool based on load. 68Pools can be configured by sysctl nodes that define the minimum 69and maximum number of processes as well as the amount of time an idle 70process will wait before exiting. 71.Pp 72One pool of AIO daemons is used to service asynchronous I/O requests for 73sockets. 74These processes are named 75.Dq soaiod<N> . 76The following sysctl nodes are used with this pool: 77.Bl -tag -width indent 78.It Va kern.ipc.aio.num_procs 79The current number of processes in the pool. 80.It Va kern.ipc.aio.target_procs 81The minimum number of processes that should be present in the pool. 82.It Va kern.ipc.aio.max_procs 83The maximum number of processes permitted in the pool. 84.It Va kern.ipc.aio.lifetime 85The amount of time a process is permitted to idle in clock ticks. 86If a process is idle for this amount of time and there are more processes 87in the pool than the target minimum, 88the process will exit. 89.El 90.Pp 91A second pool of AIO daemons is used to service all other asynchronous I/O 92requests except for I/O requests to raw disks. 93These processes are named 94.Dq aiod<N> . 95The following sysctl nodes are used with this pool: 96.Bl -tag -width indent 97.It Va vfs.aio.num_aio_procs 98The current number of processes in the pool. 99.It Va vfs.aio.target_aio_procs 100The minimum number of processes that should be present in the pool. 101.It Va vfs.aio.max_aio_procs 102The maximum number of processes permitted in the pool. 103.It Va vfs.aio.aiod_lifetime 104The amount of time a process is permitted to idle in clock ticks. 105If a process is idle for this amount of time and there are more processes 106in the pool than the target minimum, 107the process will exit. 108.El 109.Pp 110Asynchronous I/O requests for raw disks are queued directly to the disk 111device layer after temporarily wiring the user pages associated with the 112request. 113These requests are not serviced by any of the AIO daemon pools. 114.Pp 115Several limits on the number of asynchronous I/O requests are imposed both 116system-wide and per-process. 117These limits are configured via the following sysctls: 118.Bl -tag -width indent 119.It Va vfs.aio.max_buf_aio 120The maximum number of queued asynchronous I/O requests for raw disks permitted 121for a single process. 122Asynchronous I/O requests that have completed but whose status has not been 123retrieved via 124.Xr aio_return 2 125or 126.Xr aio_waitcomplete 2 127are not counted against this limit. 128.It Va vfs.aio.num_buf_aio 129The number of queued asynchronous I/O requests for raw disks system-wide. 130.It Va vfs.aio.max_aio_queue_per_proc 131The maximum number of asynchronous I/O requests for a single process 132serviced concurrently by the default AIO daemon pool. 133.It Va vfs.aio.max_aio_per_proc 134The maximum number of outstanding asynchronous I/O requests permitted for a 135single process. 136This includes requests that have not been serviced, 137requests currently being serviced, 138and requests that have completed but whose status has not been retrieved via 139.Xr aio_return 2 140or 141.Xr aio_waitcomplete 2 . 142.It Va vfs.aio.num_queue_count 143The number of outstanding asynchronous I/O requests system-wide. 144.It Va vfs.aio.max_aio_queue 145The maximum number of outstanding asynchronous I/O requests permitted 146system-wide. 147.El 148.Pp 149Asynchronous I/O control buffers should be zeroed before initializing 150individual fields. 151This ensures all fields are initialized. 152.Pp 153All asynchronous I/O control buffers contain a 154.Vt sigevent 155structure in the 156.Va aio_sigevent 157field which can be used to request notification when an operation completes. 158.Pp 159For 160.Dv SIGEV_KEVENT 161notifications, 162the 163.Va sigevent 164.Ap 165s 166.Va sigev_notify_kqueue 167field should contain the descriptor of the kqueue that the event should be attached 168to, its 169.Va sigev_notify_kevent_flags 170field may contain 171.Dv EV_ONESHOT , 172.Dv EV_CLEAR , and/or 173.Dv EV_DISPATCH , and its 174.Va sigev_notify 175field should be set to 176.Dv SIGEV_KEVENT . 177The posted kevent will contain: 178.Bl -column ".Va filter" 179.It Sy Member Ta Sy Value 180.It Va ident Ta asynchronous I/O control buffer pointer 181.It Va filter Ta Dv EVFILT_AIO 182.It Va flags Ta Dv EV_EOF 183.It Va udata Ta 184value stored in 185.Va aio_sigevent.sigev_value 186.El 187.Pp 188For 189.Dv SIGEV_SIGNO 190and 191.Dv SIGEV_THREAD_ID 192notifications, 193the information for the queued signal will include 194.Dv SI_ASYNCIO 195in the 196.Va si_code 197field and the value stored in 198.Va sigevent.sigev_value 199in the 200.Va si_value 201field. 202.Pp 203For 204.Dv SIGEV_THREAD 205notifications, 206the value stored in 207.Va aio_sigevent.sigev_value 208is passed to the 209.Va aio_sigevent.sigev_notify_function 210as described in 211.Xr sigevent 3 . 212.Sh SEE ALSO 213.Xr aio_cancel 2 , 214.Xr aio_error 2 , 215.Xr aio_read 2 , 216.Xr aio_readv 2 , 217.Xr aio_return 2 , 218.Xr aio_suspend 2 , 219.Xr aio_waitcomplete 2 , 220.Xr aio_write 2 , 221.Xr aio_writev 2 , 222.Xr lio_listio 2 , 223.Xr sigevent 3 , 224.Xr sysctl 8 225.Sh HISTORY 226The 227.Nm 228facility appeared as a kernel option in 229.Fx 3.0 . 230The 231.Nm 232kernel module appeared in 233.Fx 5.0 . 234The 235.Nm 236facility was integrated into all kernels in 237.Fx 11.0 . 238