ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/BDB/README
(Generate patch)

Comparing BDB/README (file contents):
Revision 1.9 by root, Sat May 10 20:23:19 2008 UTC vs.
Revision 1.10 by root, Tue Jul 8 08:35:12 2008 UTC

… …
106 BDB functions that cannot block (mostly functions that manipulate 106 BDB functions that cannot block (mostly functions that manipulate
107 settings) are method calls on the relevant objects, so the rule of thumb 107 settings) are method calls on the relevant objects, so the rule of thumb
108 is: if it's a method, it's not blocking, if it's a function, it takes a 108 is: if it's a method, it's not blocking, if it's a function, it takes a
109 callback as last argument. 109 callback as last argument.
110 110
111 In the following, $int signifies an integer return value, "octetstring" 111 In the following, $int signifies an integer return value, "bdb_filename"
112 is a "binary string" (i.e. a perl string with no character indices 112 is a "filename" (octets on unix, madness on windows), "U32" is an
113 >255), "U32" is an unsigned 32 bit integer, "int" is some integer, "NV" 113 unsigned 32 bit integer, "int" is some integer, "NV" is a floating point
114 is a floating point value. 114 value.
115 115
116 The "SV *" types are generic perl scalars (for input and output of data 116 The "SV *" types are generic perl scalars (for input and output of data
117 values), and the "SV *callback" is the optional callback function to 117 values), and the "SV *callback" is the optional callback function to
118 call when the request is completed. 118 call when the request is completed.
119 119
… …
126 Functions in the BDB namespace, exported by default: 126 Functions in the BDB namespace, exported by default:
127 127
128 $env = db_env_create (U32 env_flags = 0) 128 $env = db_env_create (U32 env_flags = 0)
129 flags: RPCCLIENT 129 flags: RPCCLIENT
130 130
131 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef) 131 db_env_open (DB_ENV *env, bdb_filename db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef)
132 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 132 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
133 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = &PL_sv_undef) 133 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = &PL_sv_undef)
134 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 134 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
135 flags: FORCE 135 flags: FORCE
136 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef) 136 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef)
137 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST 137 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
138 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef) 138 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef)
139 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef) 139 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef)
140 db_env_dbremove (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = &PL_sv_undef)
141 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)
140 142
141 $db = db_create (DB_ENV *env = 0, U32 flags = 0) 143 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
142 flags: XA_CREATE 144 flags: XA_CREATE
143 145
144 db_open (DB *db, DB_TXN_ornull *txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef) 146 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)
145 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE 147 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
146 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 148 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
147 flags: DB_NOSYNC 149 flags: DB_NOSYNC
148 db_upgrade (DB *db, octetstring file, U32 flags = 0, SV *callback = &PL_sv_undef) 150 db_upgrade (DB *db, bdb_filename file, U32 flags = 0, SV *callback = &PL_sv_undef)
149 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) 151 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)
150 flags: FREELIST_ONLY FREE_SPACE 152 flags: FREELIST_ONLY FREE_SPACE
151 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 153 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
152 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef) 154 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef)
153 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 155 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
… …
224 $int = $env->set_data_dir (const char *dir) 226 $int = $env->set_data_dir (const char *dir)
225 $int = $env->set_tmp_dir (const char *dir) 227 $int = $env->set_tmp_dir (const char *dir)
226 $int = $env->set_lg_dir (const char *dir) 228 $int = $env->set_lg_dir (const char *dir)
227 $int = $env->set_shm_key (long shm_key) 229 $int = $env->set_shm_key (long shm_key)
228 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 230 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
229 $int = $env->set_flags (U32 flags, int onoff) 231 $int = $env->set_flags (U32 flags, int onoff = 1)
232 $int = $env->log_set_config (U32 flags, int onoff = 1) [v4.7]
233 $int = $env->set_intermediate_dir_mode (const char *modestring) [v4.7]
230 $env->set_errfile (FILE *errfile = 0) 234 $env->set_errfile (FILE *errfile = 0)
231 $env->set_msgfile (FILE *msgfile = 0) 235 $env->set_msgfile (FILE *msgfile = 0)
232 $int = $env->set_verbose (U32 which, int onoff = 1) 236 $int = $env->set_verbose (U32 which, int onoff = 1)
233 $int = $env->set_encrypt (const char *password, U32 flags = 0) 237 $int = $env->set_encrypt (const char *password, U32 flags = 0)
234 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT) 238 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
… …
460 Strictly equivalent to: 464 Strictly equivalent to:
461 465
462 BDB::poll_wait, BDB::poll_cb 466 BDB::poll_wait, BDB::poll_cb
463 while BDB::nreqs; 467 while BDB::nreqs;
464 468
469 VERSION CHECKING
470 BerkeleyDB comes in various versions, many of them have minor
471 incompatibilities. This means that traditional "at least version x.x"
472 checks are often not sufficient.
473
474 Example: set the log_autoremove option in a way compatible with <v.47
475 and v4.7. Note the use of & on the constants to avoid triggering a
476 compiletime bug when the symbol isn't available.
477
478 $DB_ENV->set_flags (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
479 $DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;
480
481 BDB::VERSION
482 The "BDB::VERSION" function, when called without arguments, returns
483 the Berkeley DB version as a v-string (usually with 3 components).
484 You should use "lt" and "ge" operators exclusively to make
485 comparisons.
486
487 Example: check for at least version 4.7.
488
489 BDB::VERSION ge v4.7 or die;
490
491 BDB::VERSION min-version
492 Returns true if the BDB version is at least the given version
493 (specified as a v-string), false otherwise.
494
495 Example: check for at least version 4.5.
496
497 BDB::VERSION v4.7 or die;
498
499 BDB::VERSION min-version, max-version
500 Returns true of the BDB version is at least version "min-version"
501 (specify "undef" or "v0" for any minimum version) and less then
502 "max-version".
503
504 Example: check wether version is strictly less then v4.7.
505
506 BDB::VERSION v0, v4.7
507 or die "version 4.7 is not yet supported";
508
465 CONTROLLING THE NUMBER OF THREADS 509 CONTROLLING THE NUMBER OF THREADS
466 BDB::min_parallel $nthreads 510 BDB::min_parallel $nthreads
467 Set the minimum number of BDB threads to $nthreads. The current 511 Set the minimum number of BDB threads to $nthreads. The current
468 default is 8, which means eight asynchronous operations can execute 512 default is 8, which means eight asynchronous operations can execute
469 concurrently at any one time (the number of outstanding requests, 513 concurrently at any one time (the number of outstanding requests,
… …
532 (with large values). 576 (with large values).
533 577
534 BDB::set_sync_prepare $cb 578 BDB::set_sync_prepare $cb
535 Sets a callback that is called whenever a request is created without 579 Sets a callback that is called whenever a request is created without
536 an explicit callback. It has to return two code references. The 580 an explicit callback. It has to return two code references. The
537 first is used as the request callback, and the second is called to 581 first is used as the request callback (it should save the return
538 wait until the first callback has been called. The default 582 status), and the second is called to wait until the first callback
583 has been called (it must set $! to the return status).
584
585 This mechanism can be used to include BDB into other event
586 mechanisms, such as AnyEvent::BDB or Coro::BDB.
587
539 implementation works like this: 588 The default implementation works like this:
540 589
541 sub { 590 sub {
542 my $status; 591 my $status;
543 ( 592 (
544 sub { $status = $! }, 593 sub { $status = $! },
545 sub { BDB::poll while !defined $status; $! = $status }, 594 sub { BDB::poll while !defined $status; $! = $status },
546 ) 595 )
547 } 596 }
548 597
598 It simply blocks the process till the request has finished and then
599 sets $! to the return value. This means that if you don't use a
600 callback, BDB will simply fall back to synchronous operations.
601
549 STATISTICAL INFORMATION 602 STATISTICAL INFORMATION
550 BDB::nreqs 603 BDB::nreqs
551 Returns the number of requests currently in the ready, execute or 604 Returns the number of requests currently in the ready, execute or
552 pending states (i.e. for which their callback has not been invoked 605 pending states (i.e. for which their callback has not been invoked
553 yet). 606 yet).

Diff Legend

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