BDB/BDB.pm

=head1 NAME

BDB - Asynchronous Berkeley DB access

=head1 SYNOPSIS

 use BDB;

=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;

no warnings;
use strict 'vars';

use base 'Exporter';

BEGIN {
   our $VERSION = '0.1';

   our @BDB_REQ = qw(
      db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
      db_env_memp_sync db_env_memp_trickle
      db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range
      db_txn_commit db_txn_abort
      db_c_close db_c_count db_c_put db_c_get db_c_pget db_c_del
      db_sequence_open db_sequence_close
      db_sequence_get db_sequence_remove
   );
   our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create));
   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", $VERSION);
}

=head2 SUPPORT FUNCTIONS

=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION

=over 4

=item $fileno = BDB::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::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::max_poll_req> and C<BDB::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::poll_cb with high priority:

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

=item BDB::max_poll_reqs $nreqs

=item BDB::max_poll_time $seconds

These set the maximum number of requests (default C<0>, meaning infinity)
that are being processed by C<BDB::poll_cb> in one call, respectively
the maximum amount of time (default C<0>, meaning infinity) spent in
C<BDB::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::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::max_poll_time 0.1;

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

=item BDB::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::poll

Waits until some requests have been handled.

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

   BDB::poll_wait, BDB::poll_cb

=item BDB::flush

Wait till all outstanding AIO requests have been handled.

Strictly equivalent to:

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

=head3 CONTROLLING THE NUMBER OF THREADS

=item BDB::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 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::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::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::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).

=item BDB::set_sync_prepare $cb

Sets a callback that is called whenever a request is created without an
explicit callback. It has to return two code references. The first is used
as the request callback, and the second is called to wait until the first
callback has been called. The default implementation works like this:

   sub {
      my $status;
      (
         sub { $status = $! },
         sub { BDB::poll while !defined $status; $! = $status },
      )
   }

=back

=head3 STATISTICAL INFORMATION

=over 4

=item BDB::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::poll_wait, BDB::poll_cb
      while BDB::nreqs;

=item BDB::nready

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

=item BDB::npending

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

=back

=cut

set_sync_prepare {
   my $status;
   (
      sub {
         $status = $!;
      },
      sub {
         BDB::poll while !defined $status;
         $! = $status;
      },
   )
};

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.6
Committed:	Sun Feb 11 22:07:23 2007 UTC (17 years, 3 months ago) by root
Branch:	MAIN
Changes since 1.5:	+12 -7 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	BDB - Asynchronous Berkeley DB access
4
5	=head1 SYNOPSIS
6
7	use BDB;
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;
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	db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
72	db_env_memp_sync db_env_memp_trickle
73	db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range
74	db_txn_commit db_txn_abort
75	db_c_close db_c_count db_c_put db_c_get db_c_pget db_c_del
76	db_sequence_open db_sequence_close
77	db_sequence_get db_sequence_remove
78	);
79	our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create));
80	our @EXPORT_OK = qw(
81	poll_fileno poll_cb poll_wait flush
82	min_parallel max_parallel max_idle
83	nreqs nready npending nthreads
84	max_poll_time max_poll_reqs
85	);
86
87	require XSLoader;
88	XSLoader::load ("BDB", $VERSION);
89	}
90
91	=head2 SUPPORT FUNCTIONS
92
93	=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
94
95	=over 4
96
97	=item $fileno = BDB::poll_fileno
98
99	Return the I<request result pipe file descriptor>. This filehandle must be
100	polled for reading by some mechanism outside this module (e.g. Event or
101	select, see below or the SYNOPSIS). If the pipe becomes readable you have
102	to call C<poll_cb> to check the results.
103
104	See C<poll_cb> for an example.
105
106	=item BDB::poll_cb
107
108	Process some outstanding events on the result pipe. You have to call this
109	regularly. Returns the number of events processed. Returns immediately
110	when no events are outstanding. The amount of events processed depends on
111	the settings of C<BDB::max_poll_req> and C<BDB::max_poll_time>.
112
113	If not all requests were processed for whatever reason, the filehandle
114	will still be ready when C<poll_cb> returns.
115
116	Example: Install an Event watcher that automatically calls
117	BDB::poll_cb with high priority:
118
119	Event->io (fd => BDB::poll_fileno,
120	poll => 'r', async => 1,
121	cb => \&BDB::poll_cb);
122
123	=item BDB::max_poll_reqs $nreqs
124
125	=item BDB::max_poll_time $seconds
126
127	These set the maximum number of requests (default C<0>, meaning infinity)
128	that are being processed by C<BDB::poll_cb> in one call, respectively
129	the maximum amount of time (default C<0>, meaning infinity) spent in
130	C<BDB::poll_cb> to process requests (more correctly the mininum amount
131	of time C<poll_cb> is allowed to use).
132
133	Setting C<max_poll_time> to a non-zero value creates an overhead of one
134	syscall per request processed, which is not normally a problem unless your
135	callbacks are really really fast or your OS is really really slow (I am
136	not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
137
138	Setting these is useful if you want to ensure some level of
139	interactiveness when perl is not fast enough to process all requests in
140	time.
141
142	For interactive programs, values such as C<0.01> to C<0.1> should be fine.
143
144	Example: Install an Event watcher that automatically calls
145	BDB::poll_cb with low priority, to ensure that other parts of the
146	program get the CPU sometimes even under high AIO load.
147
148	# try not to spend much more than 0.1s in poll_cb
149	BDB::max_poll_time 0.1;
150
151	# use a low priority so other tasks have priority
152	Event->io (fd => BDB::poll_fileno,
153	poll => 'r', nice => 1,
154	cb => &BDB::poll_cb);
155
156	=item BDB::poll_wait
157
158	If there are any outstanding requests and none of them in the result
159	phase, wait till the result filehandle becomes ready for reading (simply
160	does a C<select> on the filehandle. This is useful if you want to
161	synchronously wait for some requests to finish).
162
163	See C<nreqs> for an example.
164
165	=item BDB::poll
166
167	Waits until some requests have been handled.
168
169	Returns the number of requests processed, but is otherwise strictly
170	equivalent to:
171
172	BDB::poll_wait, BDB::poll_cb
173
174	=item BDB::flush
175
176	Wait till all outstanding AIO requests have been handled.
177
178	Strictly equivalent to:
179
180	BDB::poll_wait, BDB::poll_cb
181	while BDB::nreqs;
182
183	=head3 CONTROLLING THE NUMBER OF THREADS
184
185	=item BDB::min_parallel $nthreads
186
187	Set the minimum number of AIO threads to C<$nthreads>. The current
188	default is C<8>, which means eight asynchronous operations can execute
189	concurrently at any one time (the number of outstanding requests,
190	however, is unlimited).
191
192	BDB starts threads only on demand, when an AIO request is queued and
193	no free thread exists. Please note that queueing up a hundred requests can
194	create demand for a hundred threads, even if it turns out that everything
195	is in the cache and could have been processed faster by a single thread.
196
197	It is recommended to keep the number of threads relatively low, as some
198	Linux kernel versions will scale negatively with the number of threads
199	(higher parallelity => MUCH higher latency). With current Linux 2.6
200	versions, 4-32 threads should be fine.
201
202	Under most circumstances you don't need to call this function, as the
203	module selects a default that is suitable for low to moderate load.
204
205	=item BDB::max_parallel $nthreads
206
207	Sets the maximum number of AIO threads to C<$nthreads>. If more than the
208	specified number of threads are currently running, this function kills
209	them. This function blocks until the limit is reached.
210
211	While C<$nthreads> are zero, aio requests get queued but not executed
212	until the number of threads has been increased again.
213
214	This module automatically runs C<max_parallel 0> at program end, to ensure
215	that all threads are killed and that there are no outstanding requests.
216
217	Under normal circumstances you don't need to call this function.
218
219	=item BDB::max_idle $nthreads
220
221	Limit the number of threads (default: 4) that are allowed to idle (i.e.,
222	threads that did not get a request to process within 10 seconds). That
223	means if a thread becomes idle while C<$nthreads> other threads are also
224	idle, it will free its resources and exit.
225
226	This is useful when you allow a large number of threads (e.g. 100 or 1000)
227	to allow for extremely high load situations, but want to free resources
228	under normal circumstances (1000 threads can easily consume 30MB of RAM).
229
230	The default is probably ok in most situations, especially if thread
231	creation is fast. If thread creation is very slow on your system you might
232	want to use larger values.
233
234	=item $oldmaxreqs = BDB::max_outstanding $maxreqs
235
236	This is a very bad function to use in interactive programs because it
237	blocks, and a bad way to reduce concurrency because it is inexact: Better
238	use an C<aio_group> together with a feed callback.
239
240	Sets the maximum number of outstanding requests to C<$nreqs>. If you
241	to queue up more than this number of requests, the next call to the
242	C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
243	function will block until the limit is no longer exceeded.
244
245	The default value is very large, so there is no practical limit on the
246	number of outstanding requests.
247
248	You can still queue as many requests as you want. Therefore,
249	C<max_oustsanding> is mainly useful in simple scripts (with low values) or
250	as a stop gap to shield against fatal memory overflow (with large values).
251
252	=item BDB::set_sync_prepare $cb
253
254	Sets a callback that is called whenever a request is created without an
255	explicit callback. It has to return two code references. The first is used
256	as the request callback, and the second is called to wait until the first
257	callback has been called. The default implementation works like this:
258
259	sub {
260	my $status;
261	(
262	sub { $status = $! },
263	sub { BDB::poll while !defined $status; $! = $status },
264	)
265	}
266
267	=back
268
269	=head3 STATISTICAL INFORMATION
270
271	=over 4
272
273	=item BDB::nreqs
274
275	Returns the number of requests currently in the ready, execute or pending
276	states (i.e. for which their callback has not been invoked yet).
277
278	Example: wait till there are no outstanding requests anymore:
279
280	BDB::poll_wait, BDB::poll_cb
281	while BDB::nreqs;
282
283	=item BDB::nready
284
285	Returns the number of requests currently in the ready state (not yet
286	executed).
287
288	=item BDB::npending
289
290	Returns the number of requests currently in the pending state (executed,
291	but not yet processed by poll_cb).
292
293	=back
294
295	=cut
296
297	set_sync_prepare {
298	my $status;
299	(
300	sub {
301	$status = $!;
302	},
303	sub {
304	BDB::poll while !defined $status;
305	$! = $status;
306	},
307	)
308	};
309
310	min_parallel 8;
311
312	END { flush }
313
314	1;
315
316	=head2 FORK BEHAVIOUR
317
318	This module should do "the right thing" when the process using it forks:
319
320	Before the fork, IO::AIO enters a quiescent state where no requests
321	can be added in other threads and no results will be processed. After
322	the fork the parent simply leaves the quiescent state and continues
323	request/result processing, while the child frees the request/result queue
324	(so that the requests started before the fork will only be handled in the
325	parent). Threads will be started on demand until the limit set in the
326	parent process has been reached again.
327
328	In short: the parent will, after a short pause, continue as if fork had
329	not been called, while the child will act as if IO::AIO has not been used
330	yet.
331
332	=head2 MEMORY USAGE
333
334	Per-request usage:
335
336	Each aio request uses - depending on your architecture - around 100-200
337	bytes of memory. In addition, stat requests need a stat buffer (possibly
338	a few hundred bytes), readdir requires a result buffer and so on. Perl
339	scalars and other data passed into aio requests will also be locked and
340	will consume memory till the request has entered the done state.
341
342	This is now awfully much, so queuing lots of requests is not usually a
343	problem.
344
345	Per-thread usage:
346
347	In the execution phase, some aio requests require more memory for
348	temporary buffers, and each thread requires a stack and other data
349	structures (usually around 16k-128k, depending on the OS).
350
351	=head1 KNOWN BUGS
352
353	Known bugs will be fixed in the next release.
354
355	=head1 SEE ALSO
356
357	L<Coro::AIO>.
358
359	=head1 AUTHOR
360
361	Marc Lehmann <schmorp@schmorp.de>
362	http://home.schmorp.de/
363
364	=cut
365