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