view release on metacpan or  search on metacpan

BDB.pm  view on Meta::CPAN

 # automatic event loop integration with AnyEvent:
 use AnyEvent::BDB;

 # automatic result processing with EV:
 my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;

 # with Glib:
 add_watch Glib::IO BDB::poll_fileno,
           in => sub { BDB::poll_cb; 1 };

 # or simply flush manually
 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.

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;

use common::sense;

use base 'Exporter';

our $VERSION;

BEGIN {
   $VERSION = '1.92';

   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_env_dbrename db_env_dbremove
      db_env_log_archive db_env_lsn_reset db_env_fileid_reset
      db_open db_close db_compact db_sync db_verify db_upgrade
      db_put db_exists db_get db_pget db_del db_key_range
      db_txn_commit db_txn_abort db_txn_finish
      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);
}

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

BDB.pm  view on Meta::CPAN

=head3 Example:

   my $seq = $db->sequence;
      
   db_sequence_open $seq, undef, "seq", BDB::CREATE;
   db_sequence_get $seq, undef, 1, my $value;


=head1 SUPPORT FUNCTIONS

=head2 EVENT PROCESSING AND EVENT LOOP INTEGRATION

=over 4

=item $msg = BDB::strerror [$errno]

Returns the string corresponding to the given errno value. If no argument
is given, use C<$!>.

Note that the BDB module also patches the C<$!> variable directly, so you
should be able to get a bdb error string by simply stringifying C<$!>.

=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 EV 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 load.

   # 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:

   BDB::poll_wait, BDB::poll_cb

=item BDB::flush

Wait till all outstanding BDB requests have been handled.

Strictly equivalent to:

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

=back

=head2 VERSION CHECKING

BerkeleyDB comes in various versions, many of them have minor
incompatibilities. This means that traditional "at least version x.x"
checks are often not sufficient.

Example: set the log_autoremove option in a way compatible with <v4.7 and
v4.7. Note the use of & on the constants to avoid triggering a compiletime
bug when the symbol isn't available.

   $DB_ENV->set_flags      (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
   $DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;

=over 4