view release on metacpan or  search on metacpan

README  view on Meta::CPAN

     db_put $db, undef, "key", "data", 0, sub {
        db_del $db, undef, "key";
     };
     db_sync $db;

     # when you also use Coro, management is easy:
     use Coro::BDB;

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

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:

    ready
        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
    value.

    Most "SV *" types are generic perl scalars (for input and output of data
    values).

    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)

README  view on Meta::CPAN

               if (seq)
                 seq->close (seq, 0);

       $int = $seq->initial_value (db_seq_t value)
       $int = $seq->set_cachesize (U32 size)
       $int = $seq->set_flags (U32 flags)
          flags: SEQ_DEC SEQ_INC SEQ_WRAP
       $int = $seq->set_range (db_seq_t min, db_seq_t max)

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

SUPPORT FUNCTIONS
  EVENT PROCESSING AND EVENT LOOP INTEGRATION
    $msg = BDB::strerror [$errno]
        Returns the string corresponding to the given errno value. If no
        argument is given, use $!.

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

    $fileno = BDB::poll_fileno
        Return the *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 "poll_cb" to check the results.

        See "poll_cb" for an example.

    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 "BDB::max_poll_req" and
        "BDB::max_poll_time".

        If not all requests were processed for whatever reason, the
        filehandle will still be ready when "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);

    BDB::max_poll_reqs $nreqs
    BDB::max_poll_time $seconds
        These set the maximum number of requests (default 0, meaning
        infinity) that are being processed by "BDB::poll_cb" in one call,
        respectively the maximum amount of time (default 0, meaning
        infinity) spent in "BDB::poll_cb" to process requests (more
        correctly the mininum amount of time "poll_cb" is allowed to use).

        Setting "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
        "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 0.01 to 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);

    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

    BDB::flush
        Wait till all outstanding BDB requests have been handled.

        Strictly equivalent to:

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

  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;

    BDB::VERSION
        The "BDB::VERSION" function, when called without arguments, returns
        the Berkeley DB version as a v-string (usually with 3 components).
        You should use "lt" and "ge" operators exclusively to make
        comparisons.