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