BDB
view release on metacpan or search on metacpan
=head1 NAME
BDB - Asynchronous Berkeley DB access
=head1 SYNOPSIS
use BDB;
my $env = db_env_create;
mkdir "bdtest", 0700;
db_env_open
$env,
BDB::flush;
=head1 DESCRIPTION
See the BerkeleyDB documentation (L<http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>).
The BDB API is very similar to the C API (the translation has been very faithful).
See also the example sections in the document below and possibly the eg/
subdirectory of the BDB distribution. Last not least see the IO::AIO
documentation, as that module uses almost the same asynchronous request
model as this module.
I know this is woefully inadequate documentation. Send a patch!
=head1 REQUEST ANATOMY AND LIFETIME
Every request method creates a request. which is a C data structure not
directly visible to Perl.
=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
require XSLoader;
XSLoader::load ("BDB", $VERSION);
}
=head1 BERKELEYDB FUNCTIONS
All of these are functions. The create functions simply return a new
object and never block. All the remaining functions take an optional
callback as last argument. If it is missing, then the function will be
executed synchronously. In both cases, C<$!> will reflect the return value
of the function.
BDB functions that cannot block (mostly functions that manipulate
settings) are method calls on the relevant objects, so the rule of thumb
is: if it's a method, it's not blocking, if it's a function, it takes a
callback as last argument.
In the following, C<$int> signifies an integer return value,
C<bdb_filename> is a "filename" (octets on unix, madness on windows),
C<U32> is an unsigned 32 bit integer, C<int> is some integer, C<NV> is a
The various C<DB_ENV> etc. arguments are handles return by
C<db_env_create>, C<db_create>, C<txn_begin> and so on. If they have an
appended C<_ornull> this means they are optional and you can pass C<undef>
for them, resulting a NULL pointer on the C level.
The C<SV *callback> is the optional callback function to call when the
request is completed. This last callback argument is special: the callback
is simply the last argument passed. If there are "optional" arguments
before the callback they can be left out. The callback itself can be left
out or specified as C<undef>, in which case the function will be executed
synchronously.
For example, C<db_env_txn_checkpoint> usually is called with all integer
arguments zero. These can be left out, so all of these specify a call
to C<< DB_ENV->txn_checkpoint >>, to be executed asynchronously with a
callback to be called:
db_env_txn_checkpoint $db_env, 0, 0, 0, sub { };
db_env_txn_checkpoint $db_env, 0, 0, sub { };
db_env_txn_checkpoint $db_env, sub { };
While these all specify a call to C<< DB_ENV->txn_checkpoint >> to be
executed synchronously:
db_env_txn_checkpoint $db_env, 0, 0, 0, undef;
db_env_txn_checkpoint $db_env, 0, 0, 0;
db_env_txn_checkpoint $db_env, 0;
=head2 BDB functions
Functions in the BDB namespace, exported by default:
$env = db_env_create (U32 env_flags = 0)
# try not to spend much more than 0.1s in poll_cb
BDB::max_poll_time 0.1;
my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&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:
}
}
=head2 CONTROLLING THE NUMBER OF THREADS
=over 4
=item BDB::min_parallel $nthreads
Set the minimum number of BDB 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 BDB 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
sub {
my $status;
(
sub { $status = $! },
sub { BDB::poll while !defined $status; $! = $status },
)
}
It works by polling for results till the request has finished and then
sets C<$!> to the return value. This means that if you don't use a
callback, BDB would simply fall back to synchronous operations.
By default, or if the sync prepare function is set to C<undef>, is to
execute callback-less BDB requests in the foreground thread, setting C<$!>
to the return value, without polling for other events.
=back
=head2 STATISTICAL INFORMATION
=over 4
SPAGAIN;
if (count != 2)
croak ("sync prepare callback must return exactly two values\n");
wait_callback = POPs;
req->callback = SvREFCNT_inc (POPs);
}
else
{
// execute request synchronously
bdb_request (req);
req_invoke (req);
req_free (req);
return;
}
}
++nreqs;
X_LOCK (reqlock);
NAME
BDB - Asynchronous Berkeley DB access
SYNOPSIS
use BDB;
my $env = db_env_create;
mkdir "bdtest", 0700;
db_env_open
$env,
"bdtest",
BDB::flush;
DESCRIPTION
See the BerkeleyDB documentation
(<http://www.oracle.com/technology/documentation/berkeley-db/db/index.ht
ml>). The BDB API is very similar to the C API (the translation has been
very faithful).
See also the example sections in the document below and possibly the eg/
subdirectory of the BDB distribution. Last not least see the IO::AIO
documentation, as that module uses almost the same asynchronous request
model as this module.
I know this is woefully inadequate documentation. Send a patch!
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:
Immediately after a request is created it is put into the ready
state, waiting for a thread to execute it.
execute
A thread has accepted the request for processing and is currently
executing it (e.g. blocking in read).
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
"poll_cb" (or another function with the same effect).
result
The request results are processed synchronously by "poll_cb".
The "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.
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).
BERKELEYDB FUNCTIONS
All of these are functions. The create functions simply return a new
object and never block. All the remaining functions take an optional
callback as last argument. If it is missing, then the function will be
executed synchronously. In both cases, $! will reflect the return value
of the function.
BDB functions that cannot block (mostly functions that manipulate
settings) are method calls on the relevant objects, so the rule of thumb
is: if it's a method, it's not blocking, if it's a function, it takes a
callback as last argument.
In the following, $int signifies an integer return value, "bdb_filename"
is a "filename" (octets on unix, madness on windows), "U32" is an
unsigned 32 bit integer, "int" is some integer, "NV" is a floating point
The various "DB_ENV" etc. arguments are handles return by
"db_env_create", "db_create", "txn_begin" and so on. If they have an
appended "_ornull" this means they are optional and you can pass "undef"
for them, resulting a NULL pointer on the C level.
The "SV *callback" is the optional callback function to call when the
request is completed. This last callback argument is special: the
callback is simply the last argument passed. If there are "optional"
arguments before the callback they can be left out. The callback itself
can be left out or specified as "undef", in which case the function will
be executed synchronously.
For example, "db_env_txn_checkpoint" usually is called with all integer
arguments zero. These can be left out, so all of these specify a call to
"DB_ENV->txn_checkpoint", to be executed asynchronously with a callback
to be called:
db_env_txn_checkpoint $db_env, 0, 0, 0, sub { };
db_env_txn_checkpoint $db_env, 0, 0, sub { };
db_env_txn_checkpoint $db_env, sub { };
While these all specify a call to "DB_ENV->txn_checkpoint" to be
executed synchronously:
db_env_txn_checkpoint $db_env, 0, 0, 0, undef;
db_env_txn_checkpoint $db_env, 0, 0, 0;
db_env_txn_checkpoint $db_env, 0;
BDB functions
Functions in the BDB namespace, exported by default:
$env = db_env_create (U32 env_flags = 0)
flags: RPCCLIENT
# try not to spend much more than 0.1s in poll_cb
BDB::max_poll_time 0.1;
my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
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 "select" on the filehandle. This is useful if you
want to synchronously wait for some requests to finish).
See "nreqs" for an example.
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
"max-version".
Example: check wether version is strictly less then v4.7.
BDB::VERSION v0, v4.7
or die "version 4.7 is not yet supported";
CONTROLLING THE NUMBER OF THREADS
BDB::min_parallel $nthreads
Set the minimum number of BDB threads to $nthreads. The current
default is 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 BDB 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
sub {
my $status;
(
sub { $status = $! },
sub { BDB::poll while !defined $status; $! = $status },
)
}
It works by polling for results till the request has finished and
then sets $! to the return value. This means that if you don't use a
callback, BDB would simply fall back to synchronous operations.
By default, or if the sync prepare function is set to "undef", is to
execute callback-less BDB requests in the foreground thread, setting
$! to the return value, without polling for other events.
STATISTICAL INFORMATION
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).
( run in 0.254 second using v1.01-cache-2.11-cpan-0d8aa00de5b )