1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<table class="head">
<tr>
<td class="head-ltitle">AIO(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">AIO(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">aio</code> — <span class="Nd">asynchronous
I/O</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">aio</code> facility provides system calls for
asynchronous I/O. Asynchronous I/O operations are not completed
synchronously by the calling thread. Instead, the calling thread invokes one
system call to request an asynchronous I/O operation. The status of a
completed request is retrieved later via a separate system call.</p>
<p class="Pp">Asynchronous I/O operations on some file descriptor types may
block an AIO daemon indefinitely resulting in process and/or system hangs.
Operations on these file descriptor types are considered
“unsafe” and disabled by default. They can be enabled by
setting the <var class="Va">vfs.aio.enable_unsafe</var> sysctl node to a
non-zero value.</p>
<p class="Pp">Asynchronous I/O operations on sockets, raw disk devices, and
regular files on local filesystems do not block indefinitely and are always
enabled.</p>
<p class="Pp">The <code class="Nm">aio</code> facility uses kernel processes
(also known as AIO daemons) to service most asynchronous I/O requests. These
processes are grouped into pools containing a variable number of processes.
Each pool will add or remove processes to the pool based on load. Pools can
be configured by sysctl nodes that define the minimum and maximum number of
processes as well as the amount of time an idle process will wait before
exiting.</p>
<p class="Pp">One pool of AIO daemons is used to service asynchronous I/O
requests for sockets. These processes are named
“soaiod<N>”. The following sysctl nodes are used with
this pool:</p>
<dl class="Bl-tag">
<dt id="kern.ipc.aio.num_procs"><var class="Va">kern.ipc.aio.num_procs</var></dt>
<dd>The current number of processes in the pool.</dd>
<dt id="kern.ipc.aio.target_procs"><var class="Va">kern.ipc.aio.target_procs</var></dt>
<dd>The minimum number of processes that should be present in the pool.</dd>
<dt id="kern.ipc.aio.max_procs"><var class="Va">kern.ipc.aio.max_procs</var></dt>
<dd>The maximum number of processes permitted in the pool.</dd>
<dt id="kern.ipc.aio.lifetime"><var class="Va">kern.ipc.aio.lifetime</var></dt>
<dd>The amount of time a process is permitted to idle in clock ticks. If a
process is idle for this amount of time and there are more processes in
the pool than the target minimum, the process will exit.</dd>
</dl>
<p class="Pp">A second pool of AIO daemons is used to service all other
asynchronous I/O requests except for I/O requests to raw disks. These
processes are named “aiod<N>”. The following sysctl
nodes are used with this pool:</p>
<dl class="Bl-tag">
<dt id="vfs.aio.num_aio_procs"><var class="Va">vfs.aio.num_aio_procs</var></dt>
<dd>The current number of processes in the pool.</dd>
<dt id="vfs.aio.target_aio_procs"><var class="Va">vfs.aio.target_aio_procs</var></dt>
<dd>The minimum number of processes that should be present in the pool.</dd>
<dt id="vfs.aio.max_aio_procs"><var class="Va">vfs.aio.max_aio_procs</var></dt>
<dd>The maximum number of processes permitted in the pool.</dd>
<dt id="vfs.aio.aiod_lifetime"><var class="Va">vfs.aio.aiod_lifetime</var></dt>
<dd>The amount of time a process is permitted to idle in clock ticks. If a
process is idle for this amount of time and there are more processes in
the pool than the target minimum, the process will exit.</dd>
</dl>
<p class="Pp">Asynchronous I/O requests for raw disks are queued directly to the
disk device layer after temporarily wiring the user pages associated with
the request. These requests are not serviced by any of the AIO daemon
pools.</p>
<p class="Pp">Several limits on the number of asynchronous I/O requests are
imposed both system-wide and per-process. These limits are configured via
the following sysctls:</p>
<dl class="Bl-tag">
<dt id="vfs.aio.max_buf_aio"><var class="Va">vfs.aio.max_buf_aio</var></dt>
<dd>The maximum number of queued asynchronous I/O requests for raw disks
permitted for a single process. Asynchronous I/O requests that have
completed but whose status has not been retrieved via
<a class="Xr">aio_return(2)</a> or <a class="Xr">aio_waitcomplete(2)</a>
are not counted against this limit.</dd>
<dt id="vfs.aio.num_buf_aio"><var class="Va">vfs.aio.num_buf_aio</var></dt>
<dd>The number of queued asynchronous I/O requests for raw disks
system-wide.</dd>
<dt id="vfs.aio.max_aio_queue_per_proc"><var class="Va">vfs.aio.max_aio_queue_per_proc</var></dt>
<dd>The maximum number of asynchronous I/O requests for a single process
serviced concurrently by the default AIO daemon pool.</dd>
<dt id="vfs.aio.max_aio_per_proc"><var class="Va">vfs.aio.max_aio_per_proc</var></dt>
<dd>The maximum number of outstanding asynchronous I/O requests permitted for
a single process. This includes requests that have not been serviced,
requests currently being serviced, and requests that have completed but
whose status has not been retrieved via <a class="Xr">aio_return(2)</a> or
<a class="Xr">aio_waitcomplete(2)</a>.</dd>
<dt id="vfs.aio.num_queue_count"><var class="Va">vfs.aio.num_queue_count</var></dt>
<dd>The number of outstanding asynchronous I/O requests system-wide.</dd>
<dt id="vfs.aio.max_aio_queue"><var class="Va">vfs.aio.max_aio_queue</var></dt>
<dd>The maximum number of outstanding asynchronous I/O requests permitted
system-wide.</dd>
</dl>
<p class="Pp">Asynchronous I/O control buffers should be zeroed before
initializing individual fields. This ensures all fields are initialized.</p>
<p class="Pp">All asynchronous I/O control buffers contain a
<var class="Vt">sigevent</var> structure in the
<var class="Va">aio_sigevent</var> field which can be used to request
notification when an operation completes.</p>
<p class="Pp">For <code class="Dv">SIGEV_KEVENT</code> notifications, the
<var class="Va">sigevent</var>'s <var class="Va">sigev_notify_kqueue</var>
field should contain the descriptor of the kqueue that the event should be
attached to, its <var class="Va">sigev_notify_kevent_flags</var> field may
contain <code class="Dv">EV_ONESHOT</code>,
<code class="Dv">EV_CLEAR</code>, <code class="Dv">and/or</code>
<code class="Dv">EV_DISPATCH</code>, <code class="Dv">and its</code>
<var class="Va">sigev_notify</var> field should be set to
<code class="Dv">SIGEV_KEVENT</code>. The posted kevent will contain:</p>
<table class="Bl-column">
<tr id="Member">
<td><a class="permalink" href="#Member"><b class="Sy">Member</b></a></td>
<td><a class="permalink" href="#Value"><b class="Sy" id="Value">Value</b></a></td>
</tr>
<tr id="ident">
<td><var class="Va">ident</var></td>
<td>asynchronous I/O control buffer pointer</td>
</tr>
<tr id="filter">
<td><var class="Va">filter</var></td>
<td><a class="permalink" href="#EVFILT_AIO"><code class="Dv" id="EVFILT_AIO">EVFILT_AIO</code></a></td>
</tr>
<tr id="flags">
<td><var class="Va">flags</var></td>
<td><a class="permalink" href="#EV_EOF"><code class="Dv" id="EV_EOF">EV_EOF</code></a></td>
</tr>
<tr id="udata">
<td><var class="Va">udata</var></td>
<td>value stored in <var class="Va">aio_sigevent.sigev_value</var></td>
</tr>
</table>
<p class="Pp">For <code class="Dv">SIGEV_SIGNO</code> and
<code class="Dv">SIGEV_THREAD_ID</code> notifications, the information for
the queued signal will include <code class="Dv">SI_ASYNCIO</code> in the
<var class="Va">si_code</var> field and the value stored in
<var class="Va">sigevent.sigev_value</var> in the
<var class="Va">si_value</var> field.</p>
<p class="Pp">For <code class="Dv">SIGEV_THREAD</code> notifications, the value
stored in <var class="Va">aio_sigevent.sigev_value</var> is passed to the
<var class="Va">aio_sigevent.sigev_notify_function</var> as described in
<a class="Xr">sigevent(3)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">aio_cancel(2)</a>, <a class="Xr">aio_error(2)</a>,
<a class="Xr">aio_read(2)</a>, <a class="Xr">aio_readv(2)</a>,
<a class="Xr">aio_return(2)</a>, <a class="Xr">aio_suspend(2)</a>,
<a class="Xr">aio_waitcomplete(2)</a>, <a class="Xr">aio_write(2)</a>,
<a class="Xr">aio_writev(2)</a>, <a class="Xr">lio_listio(2)</a>,
<a class="Xr">sigevent(3)</a>, <a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">aio</code> facility appeared as a kernel
option in <span class="Ux">FreeBSD 3.0</span>. The
<code class="Nm">aio</code> kernel module appeared in
<span class="Ux">FreeBSD 5.0</span>. The <code class="Nm">aio</code>
facility was integrated into all kernels in <span class="Ux">FreeBSD
11.0</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 2, 2021</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
