[ViewVC] Diff of: cvs/BDB/BDB.pm

Comparing BDB/BDB.pm (file contents):
Revision 1.52 by root, Mon Oct 20 02:33:40 2008 UTC vs.
Revision 1.53 by root, Tue Oct 21 02:21:25 2008 UTC

    $VERSION = '1.81';
    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_open db_close db_compact db_sync 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
    require XSLoader;
    XSLoader::load ("BDB", $VERSION);
 }
-=head2 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.
-=head2 BERKELEYDB FUNCTIONS
+=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
    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;
-=head3 BDB functions
+=head2 BDB functions
 Functions in the BDB namespace, exported by default:
    $env = db_env_create (U32 env_flags = 0)
       flags: RPCCLIENT
       atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
    db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef)
    db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef)
    db_env_dbremove (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = &PL_sv_undef)
    db_env_dbrename (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, bdb_filename newname, U32 flags = 0, SV *callback = &PL_sv_undef)
+   db_env_log_archive (DB_ENV *env, SV *listp, U32 flags = 0, SV *callback = &PL_sv_undef)
    $db = db_create (DB_ENV *env = 0, U32 flags = 0)
       flags: XA_CREATE
    db_open (DB *db, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef)
    db_sequence_get (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, int delta, SV *seq_value, U32 flags = DB_TXN_NOSYNC, SV *callback = &PL_sv_undef)
       flags: TXN_NOSYNC
    db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
       flags: TXN_NOSYNC
-=head4 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
+=head3 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
 This is not actually a Berkeley DB function but a BDB module
 extension. The background for this exytension is: It is very annoying to
 have to check every single BDB function for error returns and provide a
 codepath out of your transaction. While the BDB module still makes this
 You can use the C<< $txn->failed >> method to check wether a transaction
 has failed in this way and abort further processing (excluding
 C<db_txn_finish>).
-=head3 DB_ENV/database environment methods
+=head2 DB_ENV/database environment methods
 Methods available on DB_ENV/$env handles:
    DESTROY (DB_ENV_ornull *env)
            CODE:
    $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
    $txn = $env->cdsgroup_begin; (v4.5)
-=head4 Example:
+=head3 Example:
    use AnyEvent;
    use BDB;
    our $FH; open $FH, "<&=" . BDB::poll_fileno;
       0600;
    $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
-=head3 DB/database methods
+=head2 DB/database methods
 Methods available on DB/$db handles:
    DESTROY (DB_ornull *db)
            CODE:
    $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0)
       flags: READ_COMMITTED READ_UNCOMMITTED WRITECURSOR TXN_SNAPSHOT
    $seq = $db->sequence (U32 flags = 0)
-=head4 Example:
+=head3 Example:
    my $db = db_create $env;
    db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE | BDB::READ_UNCOMMITTED, 0600;
    for (1..1000) {
    db_del $db, undef, "key $_" for 1..1000;
    db_sync $db;
-=head3 DB_TXN/transaction methods
+=head2 DB_TXN/transaction methods
 Methods available on DB_TXN/$txn handles:
    DESTROY (DB_TXN_ornull *txn)
            CODE:
    $bool = $txn->failed
    # see db_txn_finish documentation, above
-=head3 DBC/cursor methods
+=head2 DBC/cursor methods
 Methods available on DBC/$dbc handles:
    DESTROY (DBC_ornull *dbc)
            CODE:
            if (dbc)
              dbc->c_close (dbc);
    $int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
-=head4 Example:
+=head3 Example:
    my $c = $db->cursor;
    for (;;) {
       db_c_get $c, my $key, my $data, BDB::NEXT;
    }
    db_c_close $c;
-=head3 DB_SEQUENCE/sequence methods
+=head2 DB_SEQUENCE/sequence methods
 Methods available on DB_SEQUENCE/$seq handles:
    DESTROY (DB_SEQUENCE_ornull *seq)
            CODE:
    $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)
-=head4 Example:
+=head3 Example:
    my $seq = $db->sequence;
    db_sequence_open $seq, undef, "seq", BDB::CREATE;
    db_sequence_get $seq, undef, 1, my $value;
-=head2 SUPPORT FUNCTIONS
+=head1 SUPPORT FUNCTIONS
-=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
+=head2 EVENT PROCESSING AND EVENT LOOP INTEGRATION
 =over 4
 =item $msg = BDB::strerror [$errno]
    BDB::poll_wait, BDB::poll_cb
       while BDB::nreqs;
 =back
-=head3 VERSION CHECKING
+=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.
       VERSION_v
    }
 }
-=head3 CONTROLLING THE NUMBER OF THREADS
+=head2 CONTROLLING THE NUMBER OF THREADS
 =over 4
 =item BDB::min_parallel $nthreads
 execute callback-less BDB requests in the foreground thread, setting C<$!>
 to the return value, without polling for other events.
 =back
-=head3 STATISTICAL INFORMATION
+=head2 STATISTICAL INFORMATION
 =over 4
 =item BDB::nreqs
 END { flush }
 1;
+=head1 COMMON PITFALLS
+=head2 Unexpected Crashes
+Remember that, by default, BDB will execute requests in parallel, in
+somewhat random order. That means that it is easy to run a C<db_get>
+request on thesa me database as a concurrent C<db_close> request, leading
+to a crash, silent data corruption, eventually the next world war on
+terrorism.
+If you only ever use foreground requests (without a callback), this will
+not be an issue.
+=head2 Unexpected Freezes or Deadlocks
+Remember that, by default, BDB will execute requests in parallel, which
+easily leads to deadlocks (even concurrent put's on the same database can
+deadlock).
+You either need to run deadlock detection (and handle the resulting
+errors), or make sure only one process ever updates the database, ine one
+thread, e.g. by using only foreground requests (without a callback).
-=head2 FORK BEHAVIOUR
+=head1 FORK BEHAVIOUR
 This module should do "the right thing" when the process using it forks:
 Before the fork, BDB enters a quiescent state where no requests
 can be added in other threads and no results will be processed. After
 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.
-=head2 MEMORY USAGE
+=head1 MEMORY USAGE
 Per-request usage:
 Each aio request uses - depending on your architecture - around 100-200
 bytes of memory. In addition, stat requests need a stat buffer (possibly
 In the execution phase, some aio requests require more memory for
 temporary buffers, and each thread requires a stack and other data
 structures (usually around 16k-128k, depending on the OS).
+=head1 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.
 =head1 KNOWN BUGS
 Known bugs will be fixed in the next release, except:
    If you use a transaction in any request, and the request returns

Diff Legend

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

Comparing BDB/BDB.pm (file contents): Revision 1.52 by root, Mon Oct 20 02:33:40 2008 UTC vs. Revision 1.53 by root, Tue Oct 21 02:21:25 2008 UTC

Diff Legend

Comparing BDB/BDB.pm (file contents):
Revision 1.52 by root, Mon Oct 20 02:33:40 2008 UTC vs.
Revision 1.53 by root, Tue Oct 21 02:21:25 2008 UTC