2 .\" Copyright (c) 2002 Dag-Erling Coïdan Smørgrav
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
39 facility provides system calls for asynchronous I/O.
40 Asynchronous I/O operations are not completed synchronously by the
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
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
51 and disabled by default.
52 They can be enabled by setting
54 .Va vfs.aio.enable_unsafe
55 sysctl node to a non-zero value.
57 Asynchronous I/O operations on sockets,
59 and regular files on local filesystems do not block
60 indefinitely and are always enabled.
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
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.
74 One pool of AIO daemons is used to service asynchronous I/O requests for
76 These processes are named
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.
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
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.
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
115 These requests are not serviced by any of the AIO daemon pools.
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
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
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
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
151 Asynchronous I/O control buffers should be zeroed before initializing
153 This ensures all fields are initialized.
155 All asynchronous I/O control buffers contain a
159 field which can be used to request notification when an operation completes.
168 .Va sigev_notify_kqueue
169 field should contain the descriptor of the kqueue that the event should be attached
171 .Va sigev_notify_kevent_flags
174 .Dv EV_CLEAR , and/or
175 .Dv EV_DISPATCH , and its
177 field should be set to
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
187 .Va aio_sigevent.sigev_value
195 the information for the queued signal will include
199 field and the value stored in
200 .Va sigevent.sigev_value
209 .Va aio_sigevent.sigev_value
211 .Va aio_sigevent.sigev_notify_function
220 .Xr aio_waitcomplete 2 ,
228 facility appeared as a kernel option in
232 kernel module appeared in
236 facility was integrated into all kernels in