--- BDB/BDB.pm 2007/02/05 18:40:55 1.1 +++ BDB/BDB.pm 2007/02/05 20:21:38 1.2 @@ -1,10 +1,10 @@ =head1 NAME -BDB::AIO - Asynchronous Berkeley DB access +BDB - Asynchronous Berkeley DB access =head1 SYNOPSIS - use BDB::AIO; + use BDB; =head1 DESCRIPTION @@ -57,7 +57,7 @@ =cut -package BDB::AIO; +package BDB; no warnings; use strict 'vars'; @@ -74,7 +74,7 @@ max_poll_time max_poll_reqs); require XSLoader; - XSLoader::load ("BDB::AIO", $VERSION); + XSLoader::load ("BDB", $VERSION); } =head2 SUPPORT FUNCTIONS @@ -83,7 +83,7 @@ =over 4 -=item $fileno = BDB::AIO::poll_fileno +=item $fileno = BDB::poll_fileno Return the I. This filehandle must be polled for reading by some mechanism outside this module (e.g. Event or @@ -92,31 +92,31 @@ See C for an example. -=item BDB::AIO::poll_cb +=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 and C. +the settings of C and C. If not all requests were processed for whatever reason, the filehandle will still be ready when C returns. Example: Install an Event watcher that automatically calls -BDB::AIO::poll_cb with high priority: +BDB::poll_cb with high priority: - Event->io (fd => BDB::AIO::poll_fileno, + Event->io (fd => BDB::poll_fileno, poll => 'r', async => 1, - cb => \&BDB::AIO::poll_cb); + cb => \&BDB::poll_cb); -=item BDB::AIO::max_poll_reqs $nreqs +=item BDB::max_poll_reqs $nreqs -=item BDB::AIO::max_poll_time $seconds +=item BDB::max_poll_time $seconds These set the maximum number of requests (default C<0>, meaning infinity) -that are being processed by C in one call, respectively +that are being processed by C in one call, respectively the maximum amount of time (default C<0>, meaning infinity) spent in -C to process requests (more correctly the mininum amount +C to process requests (more correctly the mininum amount of time C is allowed to use). Setting C to a non-zero value creates an overhead of one @@ -131,18 +131,18 @@ 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 +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::AIO::max_poll_time 0.1; + BDB::max_poll_time 0.1; # use a low priority so other tasks have priority - Event->io (fd => BDB::AIO::poll_fileno, + Event->io (fd => BDB::poll_fileno, poll => 'r', nice => 1, - cb => &BDB::AIO::poll_cb); + cb => &BDB::poll_cb); -=item BDB::AIO::poll_wait +=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 @@ -151,34 +151,34 @@ See C for an example. -=item BDB::AIO::poll +=item BDB::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 + BDB::poll_wait, BDB::poll_cb -=item BDB::AIO::flush +=item BDB::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; + BDB::poll_wait, BDB::poll_cb + while BDB::nreqs; =head3 CONTROLLING THE NUMBER OF THREADS -=item BDB::AIO::min_parallel $nthreads +=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::AIO starts threads only on demand, when an AIO request is queued and +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. @@ -191,7 +191,7 @@ 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 +=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 @@ -205,7 +205,7 @@ Under normal circumstances you don't need to call this function. -=item BDB::AIO::max_idle $nthreads +=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 @@ -220,7 +220,7 @@ 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 +=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 @@ -240,22 +240,22 @@ =head3 STATISTICAL INFORMATION -=item BDB::AIO::nreqs +=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::AIO::poll_wait, BDB::AIO::poll_cb - while BDB::AIO::nreqs; + BDB::poll_wait, BDB::poll_cb + while BDB::nreqs; -=item BDB::AIO::nready +=item BDB::nready Returns the number of requests currently in the ready state (not yet executed). -=item BDB::AIO::npending +=item BDB::npending Returns the number of requests currently in the pending state (executed, but not yet processed by poll_cb). @@ -264,22 +264,6 @@ =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 }