[ViewVC] Diff of: cvs/BDB/README

Comparing BDB/README (file contents):
Revision 1.3 by root, Tue Dec 4 10:14:34 2007 UTC vs.
Revision 1.9 by root, Sat May 10 20:23:19 2008 UTC

 NAME
     BDB - Asynchronous Berkeley DB access
 SYNOPSIS
      use BDB;
+     my $env = db_env_create;
+     mkdir "bdtest", 0700;
+     db_env_open
+        $env,
+        "bdtest",
+        BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL
+        | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE,
+        0600;
+     $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
+     my $db = db_create $env;
+     db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE
+                                         | BDB::READ_UNCOMMITTED, 0600;
+     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 intergration 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
         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).
+  WIN32 FILENAMES/DATABASE NAME MESS
+    Perl on Win32 supports only ASCII filenames (the reason is that it
+    abuses an internal flag to store wether a filename is Unicode or ANSI,
+    but that flag is used for somethign else in the perl core, so there is
+    no way to detect wether a filename is ANSI or Unicode-encoded). The BDB
+    module tries to work around this issue by assuming that the filename is
+    an ANSI filename and BDB was built for unicode support.
   BERKELEYDB FUNCTIONS
     All of these are functions. The create functions simply return a new
-    object and never block. All the remaining functions all take an optional
+    object and never block. All the remaining functions take an optional
-    callback as last argument. If it is missing, then the fucntion will be
+    callback as last argument. If it is missing, then the function will be
-    executed synchronously.
+    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 its a method, its not blocking, if its a function, it takes a
+    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, "octetstring"
     is a "binary string" (i.e. a perl string with no character indices
     >255), "U32" is an unsigned 32 bit integer, "int" is some integer, "NV"
        db_open (DB *db, DB_TXN_ornull *txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef)
           flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
        db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
           flags: DB_NOSYNC
+       db_upgrade (DB *db, octetstring file, U32 flags = 0, SV *callback = &PL_sv_undef)
        db_compact (DB *db, DB_TXN_ornull *txn = 0, SV *start = 0, SV *stop = 0, SV *unused1 = 0, U32 flags = DB_FREE_SPACE, SV *unused2 = 0, SV *callback = &PL_sv_undef)
           flags: FREELIST_ONLY FREE_SPACE
        db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
        db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef)
        db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
        $int = $env->set_lk_max_lockers (U32 max)
        $int = $env->set_lk_max_locks (U32 max)
        $int = $env->set_lk_max_objects (U32 max)
        $int = $env->set_lg_bsize (U32 max)
        $int = $env->set_lg_max (U32 max)
+       $int = $env->mutex_set_increment (U32 increment)
+       $int = $env->mutex_set_tas_spins (U32 tas_spins)
+       $int = $env->mutex_set_max (U32 max)
+       $int = $env->mutex_set_align (U32 align)
        $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
           flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
    Example:
        DESTROY (DBC_ornull *dbc)
                CODE:
                if (dbc)
                  dbc->c_close (dbc);
+       $int = $cursor->set_priority ($priority = PRIORITY_*)
    Example:
        my $c = $db->cursor;
        for (;;) {
           db_c_get $c, my $key, my $data, BDB::NEXT;
           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_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.
         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 Event watcher that automatically calls
+        Example: Install an EV watcher that automatically calls BDB::poll_cb
-        BDB::poll_cb with low priority, to ensure that other parts of the
+        with low priority, to ensure that other parts of the program get the
-        program get the CPU sometimes even under high AIO load.
+        CPU sometimes even under high 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
+           my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
-           Event->io (fd => BDB::poll_fileno,
-                      poll => 'r', nice => 1,
-                      cb => &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
         equivalent to:
            BDB::poll_wait, BDB::poll_cb
     BDB::flush
-        Wait till all outstanding AIO requests have been handled.
+        Wait till all outstanding BDB requests have been handled.
         Strictly equivalent to:
            BDB::poll_wait, BDB::poll_cb
               while BDB::nreqs;
    CONTROLLING THE NUMBER OF THREADS
     BDB::min_parallel $nthreads
-        Set the minimum number of AIO threads to $nthreads. The current
+        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 AIO request is queued and
+        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.
         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.
     BDB::max_parallel $nthreads
-        Sets the maximum number of AIO threads to $nthreads. If more than
+        Sets the maximum number of BDB threads to $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 $nthreads are zero, aio requests get queued but not executed
         until the number of threads has been increased again.
         (executed, but not yet processed by poll_cb).
   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
+    Before the fork, BDB enters a quiescent state where no requests can be
-    be added in other threads and no results will be processed. After the
+    added in other threads and no results will be processed. After the fork
-    fork the parent simply leaves the quiescent state and continues
+    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
+    not been called, while the child will act as if BDB has not been used
-    used yet.
+    yet.
+    Win32 note: there is no fork on win32, and perls emulation of it is too
+    broken to be supported, so do not use BDB in a windows pseudo-fork,
+    better yet, switch to a more capable platform.
   MEMORY USAGE
     Per-request usage:
     Each aio request uses - depending on your architecture - around 100-200
        with an operating system error or DB_LOCK_NOTGRANTED, the internal
        TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
        above.
 SEE ALSO
-    Coro::AIO.
+    AnyEvent::BDB (event loop integration), Coro::BDB (more natural syntax),
+    IO::AIO (nice to have).
 AUTHOR
      Marc Lehmann <schmorp@schmorp.de>
      http://home.schmorp.de/

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing BDB/README (file contents): Revision 1.3 by root, Tue Dec 4 10:14:34 2007 UTC vs. Revision 1.9 by root, Sat May 10 20:23:19 2008 UTC

Diff Legend

Comparing BDB/README (file contents):
Revision 1.3 by root, Tue Dec 4 10:14:34 2007 UTC vs.
Revision 1.9 by root, Sat May 10 20:23:19 2008 UTC