1 |
root |
1.1 |
NAME |
2 |
|
|
BDB::AIO - Asynchronous Berkeley DB access |
3 |
|
|
|
4 |
|
|
SYNOPSIS |
5 |
|
|
use BDB::AIO; |
6 |
|
|
|
7 |
|
|
DESCRIPTION |
8 |
|
|
EXAMPLE |
9 |
|
|
REQUEST ANATOMY AND LIFETIME |
10 |
|
|
Every request method creates a request. which is a C data structure not |
11 |
|
|
directly visible to Perl. |
12 |
|
|
|
13 |
|
|
During their existance, bdb requests travel through the following |
14 |
|
|
states, in order: |
15 |
|
|
|
16 |
|
|
ready |
17 |
|
|
Immediately after a request is created it is put into the ready |
18 |
|
|
state, waiting for a thread to execute it. |
19 |
|
|
|
20 |
|
|
execute |
21 |
|
|
A thread has accepted the request for processing and is currently |
22 |
|
|
executing it (e.g. blocking in read). |
23 |
|
|
|
24 |
|
|
pending |
25 |
|
|
The request has been executed and is waiting for result processing. |
26 |
|
|
|
27 |
|
|
While request submission and execution is fully asynchronous, result |
28 |
|
|
processing is not and relies on the perl interpreter calling |
29 |
|
|
"poll_cb" (or another function with the same effect). |
30 |
|
|
|
31 |
|
|
result |
32 |
|
|
The request results are processed synchronously by "poll_cb". |
33 |
|
|
|
34 |
|
|
The "poll_cb" function will process all outstanding aio requests by |
35 |
|
|
calling their callbacks, freeing memory associated with them and |
36 |
|
|
managing any groups they are contained in. |
37 |
|
|
|
38 |
|
|
done |
39 |
|
|
Request has reached the end of its lifetime and holds no resources |
40 |
|
|
anymore (except possibly for the Perl object, but its connection to |
41 |
|
|
the actual aio request is severed and calling its methods will |
42 |
|
|
either do nothing or result in a runtime error). |
43 |
|
|
|
44 |
|
|
SUPPORT FUNCTIONS |
45 |
|
|
EVENT PROCESSING AND EVENT LOOP INTEGRATION |
46 |
|
|
$fileno = BDB::AIO::poll_fileno |
47 |
|
|
Return the *request result pipe file descriptor*. This filehandle |
48 |
|
|
must be polled for reading by some mechanism outside this module |
49 |
|
|
(e.g. Event or select, see below or the SYNOPSIS). If the pipe |
50 |
|
|
becomes readable you have to call "poll_cb" to check the results. |
51 |
|
|
|
52 |
|
|
See "poll_cb" for an example. |
53 |
|
|
|
54 |
|
|
BDB::AIO::poll_cb |
55 |
|
|
Process some outstanding events on the result pipe. You have to call |
56 |
|
|
this regularly. Returns the number of events processed. Returns |
57 |
|
|
immediately when no events are outstanding. The amount of events |
58 |
|
|
processed depends on the settings of "BDB::AIO::max_poll_req" and |
59 |
|
|
"BDB::AIO::max_poll_time". |
60 |
|
|
|
61 |
|
|
If not all requests were processed for whatever reason, the |
62 |
|
|
filehandle will still be ready when "poll_cb" returns. |
63 |
|
|
|
64 |
|
|
Example: Install an Event watcher that automatically calls |
65 |
|
|
BDB::AIO::poll_cb with high priority: |
66 |
|
|
|
67 |
|
|
Event->io (fd => BDB::AIO::poll_fileno, |
68 |
|
|
poll => 'r', async => 1, |
69 |
|
|
cb => \&BDB::AIO::poll_cb); |
70 |
|
|
|
71 |
|
|
BDB::AIO::max_poll_reqs $nreqs |
72 |
|
|
BDB::AIO::max_poll_time $seconds |
73 |
|
|
These set the maximum number of requests (default 0, meaning |
74 |
|
|
infinity) that are being processed by "BDB::AIO::poll_cb" in one |
75 |
|
|
call, respectively the maximum amount of time (default 0, meaning |
76 |
|
|
infinity) spent in "BDB::AIO::poll_cb" to process requests (more |
77 |
|
|
correctly the mininum amount of time "poll_cb" is allowed to use). |
78 |
|
|
|
79 |
|
|
Setting "max_poll_time" to a non-zero value creates an overhead of |
80 |
|
|
one syscall per request processed, which is not normally a problem |
81 |
|
|
unless your callbacks are really really fast or your OS is really |
82 |
|
|
really slow (I am not mentioning Solaris here). Using |
83 |
|
|
"max_poll_reqs" incurs no overhead. |
84 |
|
|
|
85 |
|
|
Setting these is useful if you want to ensure some level of |
86 |
|
|
interactiveness when perl is not fast enough to process all requests |
87 |
|
|
in time. |
88 |
|
|
|
89 |
|
|
For interactive programs, values such as 0.01 to 0.1 should be fine. |
90 |
|
|
|
91 |
|
|
Example: Install an Event watcher that automatically calls |
92 |
|
|
BDB::AIO::poll_cb with low priority, to ensure that other parts of |
93 |
|
|
the program get the CPU sometimes even under high AIO load. |
94 |
|
|
|
95 |
|
|
# try not to spend much more than 0.1s in poll_cb |
96 |
|
|
BDB::AIO::max_poll_time 0.1; |
97 |
|
|
|
98 |
|
|
# use a low priority so other tasks have priority |
99 |
|
|
Event->io (fd => BDB::AIO::poll_fileno, |
100 |
|
|
poll => 'r', nice => 1, |
101 |
|
|
cb => &BDB::AIO::poll_cb); |
102 |
|
|
|
103 |
|
|
BDB::AIO::poll_wait |
104 |
|
|
If there are any outstanding requests and none of them in the result |
105 |
|
|
phase, wait till the result filehandle becomes ready for reading |
106 |
|
|
(simply does a "select" on the filehandle. This is useful if you |
107 |
|
|
want to synchronously wait for some requests to finish). |
108 |
|
|
|
109 |
|
|
See "nreqs" for an example. |
110 |
|
|
|
111 |
|
|
BDB::AIO::poll |
112 |
|
|
Waits until some requests have been handled. |
113 |
|
|
|
114 |
|
|
Returns the number of requests processed, but is otherwise strictly |
115 |
|
|
equivalent to: |
116 |
|
|
|
117 |
|
|
BDB::AIO::poll_wait, BDB::AIO::poll_cb |
118 |
|
|
|
119 |
|
|
BDB::AIO::flush |
120 |
|
|
Wait till all outstanding AIO requests have been handled. |
121 |
|
|
|
122 |
|
|
Strictly equivalent to: |
123 |
|
|
|
124 |
|
|
BDB::AIO::poll_wait, BDB::AIO::poll_cb |
125 |
|
|
while BDB::AIO::nreqs; |
126 |
|
|
|
127 |
|
|
CONTROLLING THE NUMBER OF THREADS |
128 |
|
|
BDB::AIO::min_parallel $nthreads |
129 |
|
|
Set the minimum number of AIO threads to $nthreads. The current |
130 |
|
|
default is 8, which means eight asynchronous operations can execute |
131 |
|
|
concurrently at any one time (the number of outstanding requests, |
132 |
|
|
however, is unlimited). |
133 |
|
|
|
134 |
|
|
BDB::AIO starts threads only on demand, when an AIO request is |
135 |
|
|
queued and no free thread exists. Please note that queueing up a |
136 |
|
|
hundred requests can create demand for a hundred threads, even if it |
137 |
|
|
turns out that everything is in the cache and could have been |
138 |
|
|
processed faster by a single thread. |
139 |
|
|
|
140 |
|
|
It is recommended to keep the number of threads relatively low, as |
141 |
|
|
some Linux kernel versions will scale negatively with the number of |
142 |
|
|
threads (higher parallelity => MUCH higher latency). With current |
143 |
|
|
Linux 2.6 versions, 4-32 threads should be fine. |
144 |
|
|
|
145 |
|
|
Under most circumstances you don't need to call this function, as |
146 |
|
|
the module selects a default that is suitable for low to moderate |
147 |
|
|
load. |
148 |
|
|
|
149 |
|
|
BDB::AIO::max_parallel $nthreads |
150 |
|
|
Sets the maximum number of AIO threads to $nthreads. If more than |
151 |
|
|
the specified number of threads are currently running, this function |
152 |
|
|
kills them. This function blocks until the limit is reached. |
153 |
|
|
|
154 |
|
|
While $nthreads are zero, aio requests get queued but not executed |
155 |
|
|
until the number of threads has been increased again. |
156 |
|
|
|
157 |
|
|
This module automatically runs "max_parallel 0" at program end, to |
158 |
|
|
ensure that all threads are killed and that there are no outstanding |
159 |
|
|
requests. |
160 |
|
|
|
161 |
|
|
Under normal circumstances you don't need to call this function. |
162 |
|
|
|
163 |
|
|
BDB::AIO::max_idle $nthreads |
164 |
|
|
Limit the number of threads (default: 4) that are allowed to idle |
165 |
|
|
(i.e., threads that did not get a request to process within 10 |
166 |
|
|
seconds). That means if a thread becomes idle while $nthreads other |
167 |
|
|
threads are also idle, it will free its resources and exit. |
168 |
|
|
|
169 |
|
|
This is useful when you allow a large number of threads (e.g. 100 or |
170 |
|
|
1000) to allow for extremely high load situations, but want to free |
171 |
|
|
resources under normal circumstances (1000 threads can easily |
172 |
|
|
consume 30MB of RAM). |
173 |
|
|
|
174 |
|
|
The default is probably ok in most situations, especially if thread |
175 |
|
|
creation is fast. If thread creation is very slow on your system you |
176 |
|
|
might want to use larger values. |
177 |
|
|
|
178 |
|
|
$oldmaxreqs = BDB::AIO::max_outstanding $maxreqs |
179 |
|
|
This is a very bad function to use in interactive programs because |
180 |
|
|
it blocks, and a bad way to reduce concurrency because it is |
181 |
|
|
inexact: Better use an "aio_group" together with a feed callback. |
182 |
|
|
|
183 |
|
|
Sets the maximum number of outstanding requests to $nreqs. If you to |
184 |
|
|
queue up more than this number of requests, the next call to the |
185 |
|
|
"poll_cb" (and "poll_some" and other functions calling "poll_cb") |
186 |
|
|
function will block until the limit is no longer exceeded. |
187 |
|
|
|
188 |
|
|
The default value is very large, so there is no practical limit on |
189 |
|
|
the number of outstanding requests. |
190 |
|
|
|
191 |
|
|
You can still queue as many requests as you want. Therefore, |
192 |
|
|
"max_oustsanding" is mainly useful in simple scripts (with low |
193 |
|
|
values) or as a stop gap to shield against fatal memory overflow |
194 |
|
|
(with large values). |
195 |
|
|
|
196 |
|
|
STATISTICAL INFORMATION |
197 |
|
|
BDB::AIO::nreqs |
198 |
|
|
Returns the number of requests currently in the ready, execute or |
199 |
|
|
pending states (i.e. for which their callback has not been invoked |
200 |
|
|
yet). |
201 |
|
|
|
202 |
|
|
Example: wait till there are no outstanding requests anymore: |
203 |
|
|
|
204 |
|
|
BDB::AIO::poll_wait, BDB::AIO::poll_cb |
205 |
|
|
while BDB::AIO::nreqs; |
206 |
|
|
|
207 |
|
|
BDB::AIO::nready |
208 |
|
|
Returns the number of requests currently in the ready state (not yet |
209 |
|
|
executed). |
210 |
|
|
|
211 |
|
|
BDB::AIO::npending |
212 |
|
|
Returns the number of requests currently in the pending state |
213 |
|
|
(executed, but not yet processed by poll_cb). |
214 |
|
|
|
215 |
|
|
FORK BEHAVIOUR |
216 |
|
|
This module should do "the right thing" when the process using it forks: |
217 |
|
|
|
218 |
|
|
Before the fork, IO::AIO enters a quiescent state where no requests can |
219 |
|
|
be added in other threads and no results will be processed. After the |
220 |
|
|
fork the parent simply leaves the quiescent state and continues |
221 |
|
|
request/result processing, while the child frees the request/result |
222 |
|
|
queue (so that the requests started before the fork will only be handled |
223 |
|
|
in the parent). Threads will be started on demand until the limit set in |
224 |
|
|
the parent process has been reached again. |
225 |
|
|
|
226 |
|
|
In short: the parent will, after a short pause, continue as if fork had |
227 |
|
|
not been called, while the child will act as if IO::AIO has not been |
228 |
|
|
used yet. |
229 |
|
|
|
230 |
|
|
MEMORY USAGE |
231 |
|
|
Per-request usage: |
232 |
|
|
|
233 |
|
|
Each aio request uses - depending on your architecture - around 100-200 |
234 |
|
|
bytes of memory. In addition, stat requests need a stat buffer (possibly |
235 |
|
|
a few hundred bytes), readdir requires a result buffer and so on. Perl |
236 |
|
|
scalars and other data passed into aio requests will also be locked and |
237 |
|
|
will consume memory till the request has entered the done state. |
238 |
|
|
|
239 |
|
|
This is now awfully much, so queuing lots of requests is not usually a |
240 |
|
|
problem. |
241 |
|
|
|
242 |
|
|
Per-thread usage: |
243 |
|
|
|
244 |
|
|
In the execution phase, some aio requests require more memory for |
245 |
|
|
temporary buffers, and each thread requires a stack and other data |
246 |
|
|
structures (usually around 16k-128k, depending on the OS). |
247 |
|
|
|
248 |
|
|
KNOWN BUGS |
249 |
|
|
Known bugs will be fixed in the next release. |
250 |
|
|
|
251 |
|
|
SEE ALSO |
252 |
|
|
Coro::AIO. |
253 |
|
|
|
254 |
|
|
AUTHOR |
255 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
256 |
|
|
http://home.schmorp.de/ |
257 |
|
|
|