BDB/BDB.pm

=head1 NAME

BDB::AIO - Asynchronous Berkeley DB access

=head1 SYNOPSIS

 use BDB::AIO;

=head1 DESCRIPTION

=head2 EXAMPLE

=head1 REQUEST ANATOMY AND LIFETIME

Every request method creates a request. which is a C data structure not
directly visible to Perl.

During their existance, bdb requests travel through the following states,
in order:

=over 4

=item ready

Immediately after a request is created it is put into the ready state,
waiting for a thread to execute it.

=item execute

A thread has accepted the request for processing and is currently
executing it (e.g. blocking in read).

=item pending

The request has been executed and is waiting for result processing.

While request submission and execution is fully asynchronous, result
processing is not and relies on the perl interpreter calling C<poll_cb>
(or another function with the same effect).

=item result

The request results are processed synchronously by C<poll_cb>.

The C<poll_cb> function will process all outstanding aio requests by
calling their callbacks, freeing memory associated with them and managing
any groups they are contained in.

=item done

Request has reached the end of its lifetime and holds no resources anymore
(except possibly for the Perl object, but its connection to the actual
aio request is severed and calling its methods will either do nothing or
result in a runtime error).

=back

=cut

package BDB::AIO;

no warnings;
use strict 'vars';

use base 'Exporter';

BEGIN {
   our $VERSION = '0.1';

   our @BDB_REQ = qw();
   our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                       min_parallel max_parallel max_idle
                       nreqs nready npending nthreads
                       max_poll_time max_poll_reqs);

   require XSLoader;
   XSLoader::load ("BDB::AIO", $VERSION);
}

=head2 SUPPORT FUNCTIONS

=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION

=over 4

=item $fileno = BDB::AIO::poll_fileno

Return the I<request result pipe file descriptor>. This filehandle must be
polled for reading by some mechanism outside this module (e.g. Event or
select, see below or the SYNOPSIS). If the pipe becomes readable you have
to call C<poll_cb> to check the results.

See C<poll_cb> for an example.

=item BDB::AIO::poll_cb

Process some outstanding events on the result pipe. You have to call this
regularly. Returns the number of events processed. Returns immediately
when no events are outstanding. The amount of events processed depends on
the settings of C<BDB::AIO::max_poll_req> and C<BDB::AIO::max_poll_time>.

If not all requests were processed for whatever reason, the filehandle
will still be ready when C<poll_cb> returns.

Example: Install an Event watcher that automatically calls
BDB::AIO::poll_cb with high priority:

   Event->io (fd => BDB::AIO::poll_fileno,
              poll => 'r', async => 1,
              cb => \&BDB::AIO::poll_cb);

=item BDB::AIO::max_poll_reqs $nreqs

=item BDB::AIO::max_poll_time $seconds

These set the maximum number of requests (default C<0>, meaning infinity)
that are being processed by C<BDB::AIO::poll_cb> in one call, respectively
the maximum amount of time (default C<0>, meaning infinity) spent in
C<BDB::AIO::poll_cb> to process requests (more correctly the mininum amount
of time C<poll_cb> is allowed to use).

Setting C<max_poll_time> to a non-zero value creates an overhead of one
syscall per request processed, which is not normally a problem unless your
callbacks are really really fast or your OS is really really slow (I am
not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.

Setting these is useful if you want to ensure some level of
interactiveness when perl is not fast enough to process all requests in
time.

For interactive programs, values such as C<0.01> to C<0.1> should be fine.

Example: Install an Event watcher that automatically calls
BDB::AIO::poll_cb with low priority, to ensure that other parts of the
program get the CPU sometimes even under high AIO load.

   # try not to spend much more than 0.1s in poll_cb
   BDB::AIO::max_poll_time 0.1;

   # use a low priority so other tasks have priority
   Event->io (fd => BDB::AIO::poll_fileno,
              poll => 'r', nice => 1,
              cb => &BDB::AIO::poll_cb);

=item BDB::AIO::poll_wait

If there are any outstanding requests and none of them in the result
phase, wait till the result filehandle becomes ready for reading (simply
does a C<select> on the filehandle. This is useful if you want to
synchronously wait for some requests to finish).

See C<nreqs> for an example.

=item BDB::AIO::poll

Waits until some requests have been handled.

Returns the number of requests processed, but is otherwise strictly
equivalent to:

   BDB::AIO::poll_wait, BDB::AIO::poll_cb

=item BDB::AIO::flush

Wait till all outstanding AIO requests have been handled.

Strictly equivalent to:

   BDB::AIO::poll_wait, BDB::AIO::poll_cb
      while BDB::AIO::nreqs;

=head3 CONTROLLING THE NUMBER OF THREADS

=item BDB::AIO::min_parallel $nthreads

Set the minimum number of AIO threads to C<$nthreads>. The current
default is C<8>, which means eight asynchronous operations can execute
concurrently at any one time (the number of outstanding requests,
however, is unlimited).

BDB::AIO starts threads only on demand, when an AIO request is queued and
no free thread exists. Please note that queueing up a hundred requests can
create demand for a hundred threads, even if it turns out that everything
is in the cache and could have been processed faster by a single thread.

It is recommended to keep the number of threads relatively low, as some
Linux kernel versions will scale negatively with the number of threads
(higher parallelity => MUCH higher latency). With current Linux 2.6
versions, 4-32 threads should be fine.

Under most circumstances you don't need to call this function, as the
module selects a default that is suitable for low to moderate load.

=item BDB::AIO::max_parallel $nthreads

Sets the maximum number of AIO threads to C<$nthreads>. If more than the
specified number of threads are currently running, this function kills
them. This function blocks until the limit is reached.

While C<$nthreads> are zero, aio requests get queued but not executed
until the number of threads has been increased again.

This module automatically runs C<max_parallel 0> at program end, to ensure
that all threads are killed and that there are no outstanding requests.

Under normal circumstances you don't need to call this function.

=item BDB::AIO::max_idle $nthreads

Limit the number of threads (default: 4) that are allowed to idle (i.e.,
threads that did not get a request to process within 10 seconds). That
means if a thread becomes idle while C<$nthreads> other threads are also
idle, it will free its resources and exit.

This is useful when you allow a large number of threads (e.g. 100 or 1000)
to allow for extremely high load situations, but want to free resources
under normal circumstances (1000 threads can easily consume 30MB of RAM).

The default is probably ok in most situations, especially if thread
creation is fast. If thread creation is very slow on your system you might
want to use larger values.

=item $oldmaxreqs = BDB::AIO::max_outstanding $maxreqs

This is a very bad function to use in interactive programs because it
blocks, and a bad way to reduce concurrency because it is inexact: Better
use an C<aio_group> together with a feed callback.

Sets the maximum number of outstanding requests to C<$nreqs>. If you
to queue up more than this number of requests, the next call to the
C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
function will block until the limit is no longer exceeded.

The default value is very large, so there is no practical limit on the
number of outstanding requests.

You can still queue as many requests as you want. Therefore,
C<max_oustsanding> is mainly useful in simple scripts (with low values) or
as a stop gap to shield against fatal memory overflow (with large values).

=head3 STATISTICAL INFORMATION

=item BDB::AIO::nreqs

Returns the number of requests currently in the ready, execute or pending
states (i.e. for which their callback has not been invoked yet).

Example: wait till there are no outstanding requests anymore:

   BDB::AIO::poll_wait, BDB::AIO::poll_cb
      while BDB::AIO::nreqs;

=item BDB::AIO::nready

Returns the number of requests currently in the ready state (not yet
executed).

=item BDB::AIO::npending

Returns the number of requests currently in the pending state (executed,
but not yet processed by poll_cb).

=back

=cut

# support function to convert a fd into a perl filehandle
sub _fd2fh {
   return undef if $_[0] < 0;

   # try to generate nice filehandles
   my $sym = "BDB::AIO::fd#$_[0]";
   local *$sym;

   open *$sym, "+<&=$_[0]"      # usually works under any unix
      or open *$sym, "<&=$_[0]" # cygwin needs this
      or open *$sym, ">&=$_[0]" # or this
      or return undef;

   *$sym
}

min_parallel 8;

END { flush }

1;

=head2 FORK BEHAVIOUR

This module should do "the right thing" when the process using it forks:

Before the fork, IO::AIO enters a quiescent state where no requests
can be added in other threads and no results will be processed. After
the fork the parent simply leaves the quiescent state and continues
request/result processing, while the child frees the request/result queue
(so that the requests started before the fork will only be handled in the
parent). Threads will be started on demand until the limit set in the
parent process has been reached again.

In short: the parent will, after a short pause, continue as if fork had
not been called, while the child will act as if IO::AIO has not been used
yet.

=head2 MEMORY USAGE

Per-request usage:

Each aio request uses - depending on your architecture - around 100-200
bytes of memory. In addition, stat requests need a stat buffer (possibly
a few hundred bytes), readdir requires a result buffer and so on. Perl
scalars and other data passed into aio requests will also be locked and
will consume memory till the request has entered the done state.

This is now awfully much, so queuing lots of requests is not usually a
problem.

Per-thread usage:

In the execution phase, some aio requests require more memory for
temporary buffers, and each thread requires a stack and other data
structures (usually around 16k-128k, depending on the OS).

=head1 KNOWN BUGS

Known bugs will be fixed in the next release.

=head1 SEE ALSO

L<Coro::AIO>.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

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