[ViewVC] Diff of: cvs/BDB/README

Comparing BDB/README (file contents):
Revision 1.10 by root, Tue Jul 8 08:35:12 2008 UTC vs.
Revision 1.13 by root, Sat Sep 27 12:02:21 2008 UTC

     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.
-    The "SV *" types are generic perl scalars (for input and output of data
+    Most "SV *" types are generic perl scalars (for input and output of data
-    values), and the "SV *callback" is the optional callback function to
+    values).
-    call when the request is completed.
     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)
           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)
           flags: APPEND NODUPDATA NOOVERWRITE
+       db_exists (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = 0) (v4.6)
        db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
           flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
        db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
           flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
        db_del (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef)
        $int = $env->set_tmp_dir (const char *dir)
        $int = $env->set_lg_dir (const char *dir)
        $int = $env->set_shm_key (long shm_key)
        $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
        $int = $env->set_flags (U32 flags, int onoff = 1)
-       $int = $env->log_set_config (U32 flags, int onoff = 1) [v4.7]
+       $int = $env->log_set_config (U32 flags, int onoff = 1) (v4.7)
-       $int = $env->set_intermediate_dir_mode (const char *modestring) [v4.7]
+       $int = $env->set_intermediate_dir_mode (const char *modestring) (v4.7)
        $env->set_errfile (FILE *errfile = 0)
        $env->set_msgfile (FILE *msgfile = 0)
        $int = $env->set_verbose (U32 which, int onoff = 1)
        $int = $env->set_encrypt (const char *password, U32 flags = 0)
        $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
        $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
+       $txn = $env->cdsgroup_begin; (v4.5)
    Example:
        use AnyEvent;
        use BDB;
        DESTROY (DBC_ornull *dbc)
                CODE:
                if (dbc)
                  dbc->c_close (dbc);
-       $int = $cursor->set_priority ($priority = PRIORITY_*)
+       $int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
    Example:
        my $c = $db->cursor;
        for (;;) {
    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 <v.47
+    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;
         You can still queue as many requests as you want. Therefore,
         "max_oustsanding" is mainly useful in simple scripts (with low
         values) or as a stop gap to shield against fatal memory overflow
         (with large values).
-    BDB::set_sync_prepare $cb
+    $old_cb = BDB::set_sync_prepare $cb
         Sets a callback that is called whenever a request is created without
         an explicit callback. It has to return two code references. The
         first is used as the request callback (it should save the return
         status), and the second is called to wait until the first callback
         has been called (it must set $! to the return status).
         This mechanism can be used to include BDB into other event
-        mechanisms, such as AnyEvent::BDB or Coro::BDB.
+        mechanisms, such as Coro::BDB.
-        The default implementation works like this:
+        To allow other, callback-based, events to be executed while
+        callback-less ones are run, you could use this sync prepare
+        function:
            sub {
               my $status;
               (
                  sub { $status = $! },
                  sub { BDB::poll while !defined $status; $! = $status },
               )
            }
-        It simply blocks the process till the request has finished and then
+        It works by polling for results till the request has finished and
-        sets $! to the return value. This means that if you don't use a
+        then sets $! to the return value. This means that if you don't use a
-        callback, BDB will simply fall back to synchronous operations.
+        callback, BDB would simply fall back to synchronous operations.
+        By default, or if the sync prepare function is set to "undef", is to
+        execute callback-less BDB requests in the foreground thread, setting
+        $! to the return value, without polling for other events.
    STATISTICAL INFORMATION
     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

Diff Legend

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

Comparing BDB/README (file contents): Revision 1.10 by root, Tue Jul 8 08:35:12 2008 UTC vs. Revision 1.13 by root, Sat Sep 27 12:02:21 2008 UTC

Diff Legend

Comparing BDB/README (file contents):
Revision 1.10 by root, Tue Jul 8 08:35:12 2008 UTC vs.
Revision 1.13 by root, Sat Sep 27 12:02:21 2008 UTC