view release on metacpan or  search on metacpan

BDB.pm  view on Meta::CPAN

callback as last argument. If it is missing, then the function will be
executed synchronously. In both cases, C<$!> 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, C<$int> signifies an integer return value,
C<bdb_filename> is a "filename" (octets on unix, madness on windows),
C<U32> is an unsigned 32 bit integer, C<int> is some integer, C<NV> is a
floating point value.

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

The various C<DB_ENV> etc. arguments are handles return by
C<db_env_create>, C<db_create>, C<txn_begin> and so on. If they have an
appended C<_ornull> this means they are optional and you can pass C<undef>
for them, resulting a NULL pointer on the C level.

The C<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 C<undef>, in which case the function will be executed
synchronously.

For example, C<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 C<< 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 C<< 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;

=head2 BDB functions

Functions in the BDB namespace, exported by default:

   $env = db_env_create (U32 env_flags = 0)
      flags: RPCCLIENT

   db_env_open (DB_ENV *env, bdb_filename db_home, U32 open_flags, int mode, SV *callback = 0)
      open_flags: INIT_CDB INIT_LOCK INIT_LOG INIT_MPOOL INIT_REP INIT_TXN RECOVER RECOVER_FATAL USE_ENVIRON USE_ENVIRON_ROOT CREATE LOCKDOWN PRIVATE REGISTER SYSTEM_MEM
   db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = 0)
   db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = 0)
      flags: FORCE
   db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = 0)
      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 = 0)
   db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = 0)
   db_env_dbremove (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = 0)
   db_env_dbrename (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, bdb_filename newname, U32 flags = 0, SV *callback = 0)
   db_env_log_archive (DB_ENV *env, SV *listp, U32 flags = 0, SV *callback = 0)
   db_env_lsn_reset (DB_ENV *env, bdb_filename db, U32 flags = 0, SV *callback = 0)
   db_env_fileid_reset (DB_ENV *env, bdb_filename db, U32 flags = 0, SV *callback = 0)

   $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 = 0)
      flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
   db_close (DB *db, U32 flags = 0, SV *callback = 0)
      flags: DB_NOSYNC
   db_verify (DB *db, bdb_filename file, bdb_filename database = 0, SV *dummy = 0, U32 flags = 0, SV *callback = 0)
   db_upgrade (DB *db, bdb_filename file, U32 flags = 0, SV *callback = 0)
   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 = 0)
      flags: FREELIST_ONLY FREE_SPACE
   db_sync (DB *db, U32 flags = 0, SV *callback = 0)
   db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = 0)
   db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
      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 = 0)
      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 = 0)
      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 = 0)
   db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = 0)
      flags: TXN_NOSYNC TXN_SYNC
   db_txn_abort (DB_TXN *txn, SV *callback = 0)

   db_c_close (DBC *dbc, SV *callback = 0)
   db_c_count (DBC *dbc, SV *count, U32 flags = 0, SV *callback = 0)
   db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
      flags: AFTER BEFORE CURRENT KEYFIRST KEYLAST NODUPDATA
   db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
      flags: CURRENT FIRST GET_BOTH GET_BOTH_RANGE GET_RECNO JOIN_ITEM LAST NEXT NEXT_DUP NEXT_NODUP PREV PREV_DUP PREV_NODUP SET SET_RANGE SET_RECNO READ_UNCOMMITTED MULTIPLE MULTIPLE_KEY RMW
   db_c_pget (DBC *dbc, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = 0)
   db_c_del (DBC *dbc, U32 flags = 0, SV *callback = 0)

   db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = 0)
      flags: CREATE EXCL
   db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = 0)
   db_sequence_get (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, int delta, SV *seq_value, U32 flags = DB_TXN_NOSYNC, SV *callback = 0)
      flags: TXN_NOSYNC
   db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = 0)
      flags: TXN_NOSYNC

=head3 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = 0)

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
possible, it contains the following extensions:

When a transaction-protected function returns any operating system
error (errno > 0), BDB will set the C<TXN_DEADLOCK> flag on the
transaction. This flag is also set by Berkeley DB functions themselves
when an operation fails with LOCK_DEADLOCK, and it causes all further