BDB(3)

🌸 BDB(3) 🌸 — Asynchronous Berkeley DB access 💅

okay bestie, sit down, hydrate, because this one is a ride. This is BDB, the Perl module that lets you talk to Berkeley DB — and not just talk, but talk asynchronously, which is the whole vibe. ✨

---

🎀 NAME 🎀

BDB — Asynchronous Berkeley DB access. that's it, that's the name, she's simple and she slays. 💖

---

✨ SYNOPSIS ✨

here's what it looks like in the wild, no cap:

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 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 🦋

first things first: go read the BerkeleyDB documentation at <http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>. like, actually. the BDB API here is very similar to the C API — the translation has been very faithful, which is honestly iconic of it. 👑

also check out the example sections down below in this very document, and possibly the eg/ subdirectory of the BDB distribution. and last but not least, go read the IO::AIO documentation, because that module uses almost the exact same asynchronous request model as this one. they're siblings, your honor. 🫶

ngl, I know this is woefully inadequate documentation. send a patch! 💀

---

🧚 REQUEST ANATOMY AND LIFETIME 🧚

okay so every request method creates a request, and a request is a C data structure that Perl literally cannot see. it's giving invisible main character. 💅

during their existence, bdb requests travel through these states, in order:

• ready — the second a request is created it gets yeeted into the ready state, just chilling, 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). busy era.
• pending — the request has been executed and is now waiting for result processing.

and here's the important part, bestie: while request submission and execution is fully asynchronous, result processing is not, and it relies on the perl interpreter calling poll_cb (or another function with the same effect). iykyk.

• 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. she does it all. 💖

• done — the 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). ghosted fr fr. 👻

---

🌈 BERKELEYDB FUNCTIONS 🌈

so, 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 that callback is missing, then the function will be executed synchronously. in both cases, $! will reflect the return value of the function. yes, both. no cap.

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. write that on your mirror. ✨

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 returned 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 in 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;

see how the vibe shifts? one little sub and the whole thing is async. obsessed. 💅

---

💜 BDB functions 💜

functions in the BDB namespace, exported by default:

the env girlies, first up:

$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)

then the db babies — note db_create takes env and flags both optional, she's flexible like that:

$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)

cursors!! the DBC crew, they walk the db so you don't have to 🚶‍♀️✨:

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)

and the sequence girlies, keeping your numbers in order like a true virgo 🎀:

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

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

okay so db_txn_finish — listen — this is not actually a Berkeley DB function. it's a BDB module extension. the background for this extension 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 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 operations on that transaction (including db_txn_commit) to fail. she's locked in. literally. 💀

the db_txn_finish request will look at this flag, and, if it is set, will automatically call db_txn_abort (setting errno to LOCK_DEADLOCK if it isn't set to something else yet). if it isn't set, it will call db_txn_commit and return the error normally. so polite. 🫶

how to use this? easy, bestie: just write your transaction normally:

my $txn = $db_env->txn_begin;
db_get $db, $txn, "key", my $data;
db_put $db, $txn, "key", $data + 1 unless $! == BDB::NOTFOUND;
db_txn_finish $txn;
die "transaction failed" if $!;

and that's where part 1 leaves us — more coming, don't go anywhere 💖

That is, bestie, you only handle the errors you expect. If something unexpected pops off — like EIO, LOCK_NOTGRANTED, or a deadlock in either db_get or db_put — then the remaining requests (in this case db_put) just get skipped (they fail with LOCK_DEADLOCK) and the transaction gets aborted. 💀

You can use the $txn->failed method to check whether a transaction has failed this way and then abort further processing (except for db_txn_finish). iykyk.

---

✨ DB_ENV/database environment methods ✨

Methods available on DB_ENV/$env handles, bestie:

• DESTROY (DB_ENV_ornull *env) — the cleanup queen. Code:

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

• $int = $env->set_data_dir (const char *dir) — data dir vibes 💅
• $int = $env->set_tmp_dir (const char *dir) — tmp dir vibes ✨
• $int = $env->set_lg_dir (const char *dir) — log dir vibes 🎀
• $int = $env->set_shm_key (long shm_key) — shared memory key 🦋
• $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) — cache size, slay 🌸
• $int = $env->set_flags (U32 flags, int onoff = 1) — flags on/off 💅
• $int = $env->log_set_config (U32 flags, int onoff = 1) — (v4.7) log config 🫶
• $int = $env->set_intermediate_dir_mode (const char *modestring) — (v4.7) intermediate dir mode 😭
• $env->set_errfile (FILE *errfile = 0) — set errfile 🔥
• $env->set_msgfile (FILE *msgfile = 0) — set msgfile 👑
• $int = $env->set_verbose (U32 which, int onoff = 1) — verbose vibes 🌈
• $int = $env->set_encrypt (const char *password, U32 flags = 0) — encrypt ⭐
• $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT) — timeout 💀
• $int = $env->set_mp_max_openfd (int maxopenfd); — max open fd 🙈
• $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep); — max write 🍓
• $int = $env->set_mp_mmapsize (int mmapsize_mb) — mmap size 🧚
• $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT) — lock detect 💜
• $int = $env->set_lk_max_lockers (U32 max) — max lockers 💖
• $int = $env->set_lk_max_locks (U32 max) — max locks ✨
• $int = $env->set_lk_max_objects (U32 max) — max objects 🎀
• $int = $env->set_lg_bsize (U32 max) — log bsize 🦋
• $int = $env->set_lg_max (U32 max) — log max 🌸
• $int = $env->mutex_set_increment (U32 increment) — mutex increment 💅
• $int = $env->mutex_set_tas_spins (U32 tas_spins) — tas spins 🫶
• $int = $env->mutex_set_max (U32 max) — mutex max 😭
• $int = $env->mutex_set_align (U32 align) — mutex 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, bestie:

use AnyEvent;
use BDB;

our $FH; open $FH, "<&=" . BDB::poll_fileno;
our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&BDB::poll_cb);

BDB::min_parallel 8;

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

---

🌸 DB/database methods 🌸

Methods available on DB/$db handles, bestie:

• DESTROY (DB_ornull *db) — cleanup queen. Code:

if (db)
  {
    SV *env = (SV *)db->app_private;
    db->close (db, 0);
    SvREFCNT_dec (env);
  }

• $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) — cache size 💅
• $int = $db->set_flags (U32 flags) — flags, and here are the vibes:
  • CHKSUM ENCRYPT TXN_NOT_DURABLE
  • Btree: DUP DUPSORT RECNUM REVSPLITOFF
  • Hash: DUP DUPSORT
  • Queue: INORDER
  • Recno: RENUMBER SNAPSHOT
• $int = $db->set_encrypt (const char *password, U32 flags) — encrypt ✨
• $int = $db->set_lorder (int lorder) — lorder 🎀
• $int = $db->set_bt_minkey (U32 minkey) — bt minkey 🦋
• $int = $db->set_re_delim (int delim) — re delim 🌸
• $int = $db->set_re_pad (int re_pad) — re pad 💅
• $int = $db->set_re_source (char *source) — re source 🫶
• $int = $db->set_re_len (U32 re_len) — re len 😭
• $int = $db->set_h_ffactor (U32 h_ffactor) — h ffactor 🔥
• $int = $db->set_h_nelem (U32 h_nelem) — h nelem 👑
• $int = $db->set_q_extentsize (U32 extentsize) — q extentsize 🌈
• $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) — sequence ⭐

Example, bestie:

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_put $db, undef, "key $_", "data $_";

   db_key_range $db, undef, "key $_", my $keyrange;
   my ($lt, $eq, $gt) = @$keyrange;
}

db_del $db, undef, "key $_" for 1..1000;

db_sync $db;

---

💀 DB_TXN/transaction methods 💀

Methods available on DB_TXN/$txn handles, bestie:

• DESTROY (DB_TXN_ornull *txn) — cleanup queen. Code:

if (txn)
  txn->abort (txn);

• $int = $txn->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT) flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
• $bool = $txn->failed

# see db_txn_finish documentation, above

---

🎀 DBC/cursor methods 🎀

Methods available on DBC/$dbc handles, bestie:

• DESTROY (DBC_ornull *dbc) — cleanup queen. Code:

if (dbc)
  dbc->c_close (dbc);

• $int = $cursor->set_priority ($priority = PRIORITY_*) — (v4.6) priority vibes 💅

Example, bestie:

my $c = $db->cursor;

for (;;) {
   db_c_get $c, my $key, my $data, BDB::NEXT;
   warn "<$!,$key,$data>";
   last if $!;
}

db_c_close $c;

---

🌈 DB_SEQUENCE/sequence methods 🌈

Methods available on DB_SEQUENCE/$seq handles, bestie:

• DESTROY (DB_SEQUENCE_ornull *seq) — cleanup queen. Code:

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

• $int = $seq->initial_value (db_seq_t value) — initial value 💖
• $int = $seq->set_cachesize (U32 size) — cache 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) — range 🎀

Example, bestie:

my $seq = $db->sequence;

db_sequence_open $seq, undef, "seq", BDB::CREATE;
db_sequence_get $seq, undef, 1, my $value;

✨ SUPPORT FUNCTIONS ✨

okay bestie, these are the little helper functions that make the whole thing actually run 💖

---

🎀 EVENT PROCESSING AND EVENT LOOP INTEGRATION 🎀

• $msg = BDB::strerror [$errno] — gimme an errno value and I'll hand you back the matching string. no argument? then it just uses $!. and here's the cute part: the BDB module also patches $! directly, so you can literally just stringify $! and a bdb error string falls right out. iconic.
• $fileno = BDB::poll_fileno — returns the request result pipe file descriptor. this filehandle has to be polled for reading by some mechanism outside this module (think Event or select — see below, or peek the SYNOPSIS). if the pipe goes readable, you gotta call poll_cb to go check the results.

there's an example waiting for you under "poll_cb" 👇

• BDB::poll_cb — processes some of the outstanding events sitting on the result pipe. you have to call this regularly, fr fr. returns the number of events it processed. if nothing's outstanding it comes back immediately. how much it actually chews through depends on the settings of BDB::max_poll_req and BDB::max_poll_time.

if for whatever reason not all the requests got processed, the filehandle will still be ready when poll_cb returns.

Example: install an Event watcher that auto-calls BDB::poll_cb at 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 two set the ceiling on stuff happening inside BDB::poll_cb in a single call. max_poll_reqs is the max number of requests (default 0, which means infinity 🌌). max_poll_time is the max amount of time spent processing requests (default 0, also infinity) — or, more correctly, the minimum 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. normally no biggie — unless your callbacks are really really fast or your OS is really really slow (and I am not mentioning Solaris here 💀). using max_poll_reqs incurs no overhead.

why bother? these are useful when you want to guarantee some level of interactiveness while perl is not fast enough to process every request in time. for interactive programs, values like 0.01 to 0.1 should be totally fine.

Example: install an EV watcher that auto-calls BDB::poll_cb at low priority, so the rest of your program still gets CPU sometimes even under heavy 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 are in the result phase, this waits till the result filehandle becomes ready for reading (it just does a select on the filehandle, lowkey simple like that). super handy if you wanna 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 other than that it's strictly equivalent to:

BDB::poll_wait, BDB::poll_cb

• BDB::flush — waits 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 a whole pile of versions and, ngl, a lot of them have minor incompatibilities with each other. which means the classic "at least version x.x" check is often just... not enough, bestie 😭

Example: set the log_autoremove option in a way that's compatible with both <v4.7 and v4.7. notice the & on the constants — that's on purpose, to dodge a compiletime bug that triggers 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 — called with no arguments, this returns the Berkeley DB version as a v-string (usually with 3 components). you should use the lt and ge operators exclusively when comparing, okay? no mixing and matching.

Example: check for at least version 4.7.

BDB::VERSION ge v4.7 or die;

• BDB::VERSION min-version — returns true if the BDB version is at least the version you gave (specified as a v-string), false otherwise.

Example: check for at least version 4.5.

BDB::VERSION v4.7 or die;

• BDB::VERSION min-version, max-version — returns true if the BDB version is at least min-version (pass undef or v0 if you don't care about a minimum) and less than max-version.

Example: check whether the version is strictly less than v4.7.

BDB::VERSION v0, v4.7
   or die "version 4.7 is not yet supported";

---

🦋 CONTROLLING THE NUMBER OF THREADS 🦋

• BDB::min_parallel $nthreads — sets the minimum number of BDB threads to $nthreads. the current default is 8, which means eight asynchronous operations can run concurrently at any one time (tho the number of outstanding requests is unlimited, so don't get it twisted).

BDB only spins up threads on demand — when a BDB request gets queued and there's no free thread lying around. heads up: queueing up a hundred requests can create demand for a hundred threads, even if it turns out everything was already in the cache and a single thread could've handled it faster.

you're better off keeping the thread count relatively low, because some Linux kernel versions scale negatively with thread count (more parallelity ⇒ MUCH higher latency 😭). on current Linux 2.6 versions, 4-32 threads should be fine.

under most circumstances you don't need to call this at all — the module picks a default that's suitable for low to moderate load.

• BDB::max_parallel $nthreads — sets the maximum number of BDB threads to $nthreads. if more than the specified number are currently running, this function kills them. it blocks until the limit is reached.

while $nthreads is zero, aio requests get queued but not executed — they just sit there until the number of threads gets increased again.

this module automatically runs max_parallel 0 at program end, to make sure all threads are killed and there are no outstanding requests. good hygiene bestie 🫶

under normal circumstances you don't need to call this function.

• BDB::max_idle $nthreads — limits the number of threads (default: 4) that are allowed to idle — meaning threads that didn't get a request to process within 10 seconds. so if a thread goes idle while $nthreads other threads are also idle, it frees its resources and exits.

this is useful when you allow a huge number of threads (like 100 or 1000) to handle extreme load situations, but you still want to free resources under normal circumstances (1000 threads can easily eat 30MB of RAM 💀).

the default is probably fine in most situations, especially if thread creation is fast. but if thread creation is very slow on your system, you might wanna use larger values.

• $oldmaxreqs = BDB::max_outstanding $maxreqs — okay so this is a very bad function to use in interactive programs because it blocks, and it's also a bad way to reduce concurrency because it's inexact. better: use an aio_group together with a feed callback, periodt.

it sets the maximum number of outstanding requests to $nreqs. if you try to queue up more than that, the next call to poll_cb (and poll_some and the other functions that call poll_cb) will block until the limit is no longer exceeded.

the default value is very large, so there's no practical limit on the number of outstanding requests.

you can still queue as many requests as you want, so 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).

• $old_cb = BDB::set_sync_prepare $cb — sets a callback that gets 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 lets you fold BDB into other event mechanisms, like Coro::BDB ✨

to let other, callback-based events run while callback-less ones are going, you could use this sync prepare function:

sub {
   my $status;
   (
      sub { $status = $! },
      sub { BDB::poll while !defined $status; $! = $status },
   )
}

it works by polling for results till the request has finished, then setting $! to the return value. which means: if you don't use a callback, BDB would simply fall back to synchronous operations.

by default — or if the sync prepare function is set to undef — callback-less BDB requests get executed 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. the ones whose callback hasn't been invoked yet).

Example: wait till there are no outstanding requests anymore.

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

• BDB::nready — returns the number of requests currently in the ready state (not yet executed).
• BDB::npending — returns the number of requests currently in the pending state (executed, but not yet processed by poll_cb).

---

💀 COMMON PITFALLS 💀

🙈 Unexpected Crashes 🙈

remember bestie: by default, BDB executes requests in parallel, in a somewhat random order. which means it's super easy to run a db_get request on the same database as a concurrent db_close request — and that leads to a crash, silent data corruption, and eventually the next world war on terrorism 😭

if you only ever use foreground requests (without a callback), this will not be an issue — unless you use threads, in which case all bets are off.

🥶 Unexpected Freezes or Deadlocks 🥶

again: by default, BDB executes requests in parallel, which easily leads to deadlocks (even concurrent put's on the same database can deadlock, fr fr).

you've got two options, pick one:

1. run deadlock detection (and handle the resulting errors), or
2. make sure only one process ever updates the database, in one thread — e.g. by using only foreground requests (without a callback).

🍴 FORK BEHAVIOUR 🍴

okay bestie, this is the part where people get scared, but listen — this module lowkey does the right thing when the process using it forks. 💅

Before the fork, BDB slips into a quiescent state — that means no new requests can be added in other threads, and no results are getting processed either. it's like the group chat going silent for a sec. 😶

After the fork? Here's the split:

• the parent just leaves the quiescent state and carries on with request/result processing like nothing happened.
• the child frees the request/result queue. so any requests that were started before the fork only ever get handled in the parent. no dupe handling, no chaos. ✨

Threads get started on demand until the limit that was set in the parent process has been reached again.

In short (the tl;dr you can screenshot 📸):

• the parent will, after a short pause, continue as if fork had not been called.
• the child will act as if BDB has not been used yet. fresh start, clean slate, main character energy. 🌸

Win32 note: there is no fork on win32, and perl's 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. 💀 sorry not sorry.

---

🧠 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 a few hundred bytes),
• readdir requires a result buffer,
• and so on. 🌈

Perl scalars and other data passed into aio requests will also be locked, and they'll consume memory until the request has entered the done state.

This is not awfully much, so queuing lots of requests is not usually a problem. go ahead, queue 'em up, she can handle it. 🫶

Per-thread usage:

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.

---

🪟 WIN32 FILENAMES/DATABASE NAME MESS 🪟

Perl on Win32 supports only ASCII filenames. the reason? it abuses an internal flag to store whether a filename is Unicode or ANSI, but that flag is used for something else in the perl core — so there is no way to detect whether 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 that BDB was built for unicode support. it's giving "we did our best with what we had". 🎀

---

🐛 KNOWN BUGS 🐛

Known bugs will be fixed in the next release, except:

• If you use a transaction in any request, and the request returns with an operating system error or DB_LOCK_NOTGRANTED, the internal TXN_DEADLOCK flag will be set on the transaction. See db_txn_finish, above.

that one's still hanging around, so bestie… know about it. 🙈

---

👀 SEE ALSO 👀

• 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/

---

and that's the whole page, bestie!! you made it all the way to the bottom, which is genuinely iconic of you. 👑 this one came from perl v5.42.0, dated 2025-07-25, and it's the BDB(3) page — so if you're quoting it, that's your receipt. 🧾 now go forth and aio responsibly. slay. 💅🌸💖