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

Comparing BDB/BDB.pm (file contents):
Revision 1.36 by root, Sat May 10 20:23:06 2008 UTC vs.
Revision 1.50 by root, Thu Sep 25 22:09:02 2008 UTC

… …
108no warnings; 108no warnings;
109use strict 'vars'; 109use strict 'vars';
110 110
111use base 'Exporter'; 111use base 'Exporter';
112 112
113our $VERSION;
114
113BEGIN { 115BEGIN {
114 our $VERSION = '1.5'; 116 $VERSION = '1.8';
115 117
116 our @BDB_REQ = qw( 118 our @BDB_REQ = qw(
117 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect 119 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
118 db_env_memp_sync db_env_memp_trickle 120 db_env_memp_sync db_env_memp_trickle db_env_dbrename db_env_dbremove
119 db_open db_close db_compact db_sync db_upgrade 121 db_open db_close db_compact db_sync db_upgrade
120 db_put db_get db_pget db_del db_key_range 122 db_put db_exists db_get db_pget db_del db_key_range
121 db_txn_commit db_txn_abort db_txn_finish 123 db_txn_commit db_txn_abort db_txn_finish
122 db_c_close db_c_count db_c_put db_c_get db_c_pget db_c_del 124 db_c_close db_c_count db_c_put db_c_get db_c_pget db_c_del
123 db_sequence_open db_sequence_close 125 db_sequence_open db_sequence_close
124 db_sequence_get db_sequence_remove 126 db_sequence_get db_sequence_remove
125 ); 127 );
… …
156settings) are method calls on the relevant objects, so the rule of thumb 158settings) are method calls on the relevant objects, so the rule of thumb
157is: if it's a method, it's not blocking, if it's a function, it takes a 159is: if it's a method, it's not blocking, if it's a function, it takes a
158callback as last argument. 160callback as last argument.
159 161
160In the following, C<$int> signifies an integer return value, 162In the following, C<$int> signifies an integer return value,
161C<octetstring> is a "binary string" (i.e. a perl string with no character 163C<bdb_filename> is a "filename" (octets on unix, madness on windows),
162indices >255), C<U32> is an unsigned 32 bit integer, C<int> is some 164C<U32> is an unsigned 32 bit integer, C<int> is some integer, C<NV> is a
163integer, C<NV> is a floating point value. 165floating point value.
164 166
165The C<SV *> types are generic perl scalars (for input and output of data 167Most C<SV *> types are generic perl scalars (for input and output of data
166values), and the C<SV *callback> is the optional callback function to call 168values).
167when the request is completed.
168 169
169The various C<DB_ENV> etc. arguments are handles return by 170The various C<DB_ENV> etc. arguments are handles return by
170C<db_env_create>, C<db_create>, C<txn_begin> and so on. If they have an 171C<db_env_create>, C<db_create>, C<txn_begin> and so on. If they have an
171appended C<_ornull> this means they are optional and you can pass C<undef> 172appended C<_ornull> this means they are optional and you can pass C<undef>
172for them, resulting a NULL pointer on the C level. 173for them, resulting a NULL pointer on the C level.
173 174
175The C<SV *callback> is the optional callback function to call when the
176request is completed. This last callback argument is special: the callback
177is simply the last argument passed. If there are "optional" arguments
178before the callback they can be left out. The callback itself can be left
179out or specified as C<undef>, in which case the function will be executed
180synchronously.
181
182For example, C<db_env_txn_checkpoint> usually is called with all integer
183arguments zero. These can be left out, so all of these specify a call
184to C<< DB_ENV->txn_checkpoint >>, to be executed asynchronously with a
185callback to be called:
186
187 db_env_txn_checkpoint $db_env, 0, 0, 0, sub { };
188 db_env_txn_checkpoint $db_env, 0, 0, sub { };
189 db_env_txn_checkpoint $db_env, sub { };
190
191While these all specify a call to C<< DB_ENV->txn_checkpoint >> to be
192executed synchronously:
193
194 db_env_txn_checkpoint $db_env, 0, 0, 0, undef;
195 db_env_txn_checkpoint $db_env, 0, 0, 0;
196 db_env_txn_checkpoint $db_env, 0;
197
174=head3 BDB functions 198=head3 BDB functions
175 199
176Functions in the BDB namespace, exported by default: 200Functions in the BDB namespace, exported by default:
177 201
178 $env = db_env_create (U32 env_flags = 0) 202 $env = db_env_create (U32 env_flags = 0)
179 flags: RPCCLIENT 203 flags: RPCCLIENT
180 204
181 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef) 205 db_env_open (DB_ENV *env, bdb_filename db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef)
182 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 206 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
183 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = &PL_sv_undef) 207 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = &PL_sv_undef)
184 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 208 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
185 flags: FORCE 209 flags: FORCE
186 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef) 210 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef)
187 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST 211 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
188 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef) 212 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef)
189 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef) 213 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef)
214 db_env_dbremove (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = &PL_sv_undef)
215 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)
190 216
191 $db = db_create (DB_ENV *env = 0, U32 flags = 0) 217 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
192 flags: XA_CREATE 218 flags: XA_CREATE
193 219
194 db_open (DB *db, DB_TXN_ornull *txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef) 220 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)
195 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE 221 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
196 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 222 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
197 flags: DB_NOSYNC 223 flags: DB_NOSYNC
198 db_upgrade (DB *db, octetstring file, U32 flags = 0, SV *callback = &PL_sv_undef) 224 db_upgrade (DB *db, bdb_filename file, U32 flags = 0, SV *callback = &PL_sv_undef)
199 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) 225 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)
200 flags: FREELIST_ONLY FREE_SPACE 226 flags: FREELIST_ONLY FREE_SPACE
201 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 227 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
202 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef) 228 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef)
203 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 229 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
204 flags: APPEND NODUPDATA NOOVERWRITE 230 flags: APPEND NODUPDATA NOOVERWRITE
231 db_exists (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = 0) (v4.6)
205 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 232 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
206 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW 233 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
207 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 234 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
208 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW 235 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
209 db_del (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef) 236 db_del (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef)
… …
276 $int = $env->set_data_dir (const char *dir) 303 $int = $env->set_data_dir (const char *dir)
277 $int = $env->set_tmp_dir (const char *dir) 304 $int = $env->set_tmp_dir (const char *dir)
278 $int = $env->set_lg_dir (const char *dir) 305 $int = $env->set_lg_dir (const char *dir)
279 $int = $env->set_shm_key (long shm_key) 306 $int = $env->set_shm_key (long shm_key)
280 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 307 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
281 $int = $env->set_flags (U32 flags, int onoff) 308 $int = $env->set_flags (U32 flags, int onoff = 1)
309 $int = $env->log_set_config (U32 flags, int onoff = 1) (v4.7)
310 $int = $env->set_intermediate_dir_mode (const char *modestring) (v4.7)
282 $env->set_errfile (FILE *errfile = 0) 311 $env->set_errfile (FILE *errfile = 0)
283 $env->set_msgfile (FILE *msgfile = 0) 312 $env->set_msgfile (FILE *msgfile = 0)
284 $int = $env->set_verbose (U32 which, int onoff = 1) 313 $int = $env->set_verbose (U32 which, int onoff = 1)
285 $int = $env->set_encrypt (const char *password, U32 flags = 0) 314 $int = $env->set_encrypt (const char *password, U32 flags = 0)
286 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT) 315 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
… …
298 $int = $env->mutex_set_max (U32 max) 327 $int = $env->mutex_set_max (U32 max)
299 $int = $env->mutex_set_align (U32 align) 328 $int = $env->mutex_set_align (U32 align)
300 329
301 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0) 330 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
302 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC 331 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
332 $txn = $env->cdsgroup_begin; (v4.5)
303 333
304=head4 Example: 334=head4 Example:
305 335
306 use AnyEvent; 336 use AnyEvent;
307 use BDB; 337 use BDB;
… …
399 DESTROY (DBC_ornull *dbc) 429 DESTROY (DBC_ornull *dbc)
400 CODE: 430 CODE:
401 if (dbc) 431 if (dbc)
402 dbc->c_close (dbc); 432 dbc->c_close (dbc);
403 433
404 $int = $cursor->set_priority ($priority = PRIORITY_*) 434 $int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
405 435
406=head4 Example: 436=head4 Example:
407 437
408 my $c = $db->cursor; 438 my $c = $db->cursor;
409 439
… …
536 BDB::poll_wait, BDB::poll_cb 566 BDB::poll_wait, BDB::poll_cb
537 while BDB::nreqs; 567 while BDB::nreqs;
538 568
539=back 569=back
540 570
571=head3 VERSION CHECKING
572
573BerkeleyDB comes in various versions, many of them have minor
574incompatibilities. This means that traditional "at least version x.x"
575checks are often not sufficient.
576
577Example: set the log_autoremove option in a way compatible with <v4.7 and
578v4.7. Note the use of & on the constants to avoid triggering a compiletime
579bug when the symbol isn't available.
580
581 $DB_ENV->set_flags (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
582 $DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;
583
584=over 4
585
586=item BDB::VERSION
587
588The C<BDB::VERSION> function, when called without arguments, returns the
589Berkeley DB version as a v-string (usually with 3 components). You should
590use C<lt> and C<ge> operators exclusively to make comparisons.
591
592Example: check for at least version 4.7.
593
594 BDB::VERSION ge v4.7 or die;
595
596=item BDB::VERSION min-version
597
598Returns true if the BDB version is at least the given version (specified
599as a v-string), false otherwise.
600
601Example: check for at least version 4.5.
602
603 BDB::VERSION v4.7 or die;
604
605=item BDB::VERSION min-version, max-version
606
607Returns true of the BDB version is at least version C<min-version> (specify C<undef> or C<v0> for any minimum version)
608and less then C<max-version>.
609
610Example: check wether version is strictly less then v4.7.
611
612 BDB::VERSION v0, v4.7
613 or die "version 4.7 is not yet supported";
614
615=back
616
617=cut
618
619sub VERSION {
620 # I was dumb enough to override the VERSION method here, so let's try
621 # to fix it up.
622
623 if ($_[0] eq __PACKAGE__) {
624 $VERSION
625 } else {
626 if (@_ > 0) {
627 return undef if VERSION_v lt $_[0];
628 if (@_ > 1) {
629 return undef if VERSION_v ge $_[1];
630 }
631 }
632
633 VERSION_v
634 }
635}
636
541=head3 CONTROLLING THE NUMBER OF THREADS 637=head3 CONTROLLING THE NUMBER OF THREADS
542 638
543=over 4 639=over 4
544 640
545=item BDB::min_parallel $nthreads 641=item BDB::min_parallel $nthreads
… …
607 703
608You can still queue as many requests as you want. Therefore, 704You can still queue as many requests as you want. Therefore,
609C<max_oustsanding> is mainly useful in simple scripts (with low values) or 705C<max_oustsanding> is mainly useful in simple scripts (with low values) or
610as a stop gap to shield against fatal memory overflow (with large values). 706as a stop gap to shield against fatal memory overflow (with large values).
611 707
612=item BDB::set_sync_prepare $cb 708=item $old_cb = BDB::set_sync_prepare $cb
613 709
614Sets a callback that is called whenever a request is created without an 710Sets a callback that is called whenever a request is created without an
615explicit callback. It has to return two code references. The first is used 711explicit callback. It has to return two code references. The first is used
616as the request callback, and the second is called to wait until the first 712as the request callback (it should save the return status), and the second
617callback has been called. The default implementation works like this: 713is called to wait until the first callback has been called (it must set
714C<$!> to the return status).
715
716This mechanism can be used to include BDB into other event mechanisms,
717such as L<Coro::BDB>.
718
719To allow other, callback-based, events to be executed while callback-less
720ones are run, you could use this sync prepare function:
618 721
619 sub { 722 sub {
620 my $status; 723 my $status;
621 ( 724 (
622 sub { $status = $! }, 725 sub { $status = $! },
623 sub { BDB::poll while !defined $status; $! = $status }, 726 sub { BDB::poll while !defined $status; $! = $status },
624 ) 727 )
625 } 728 }
626 729
730It works by polling for results till the request has finished and then
731sets C<$!> to the return value. This means that if you don't use a
732callback, BDB would simply fall back to synchronous operations.
733
734By default, or if the sync prepare function is set to C<undef>, is to
735execute callback-less BDB requests in the foreground thread, setting C<$!>
736to the return value, without polling for other events.
737
627=back 738=back
628 739
629=head3 STATISTICAL INFORMATION 740=head3 STATISTICAL INFORMATION
630 741
631=over 4 742=over 4
… …
652 763
653=back 764=back
654 765
655=cut 766=cut
656 767
657set_sync_prepare { 768set_sync_prepare (undef);
658 my $status;
659 (
660 sub {
661 $status = $!;
662 },
663 sub {
664 BDB::poll while !defined $status;
665 $! = $status;
666 },
667 )
668};
669 769
670min_parallel 8; 770min_parallel 8;
671 771
672END { flush } 772END { flush }
673 773

Diff Legend

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