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

Comparing BDB/BDB.pm (file contents):
Revision 1.16 by root, Sun Sep 16 18:17:58 2007 UTC vs.
Revision 1.20 by root, Fri Dec 7 13:14:41 2007 UTC

… …
3BDB - Asynchronous Berkeley DB access 3BDB - Asynchronous Berkeley DB access
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use BDB; 7 use BDB;
8
9 my $env = db_env_create;
10
11 mkdir "bdtest", 0700;
12 db_env_open
13 $env,
14 "bdtest",
15 BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL
16 | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE,
17 0600;
18
19 $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
20
21 my $db = db_create $env;
22 db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE
23 | BDB::READ_UNCOMMITTED, 0600;
24 db_put $db, undef, "key", "data", 0, sub {
25 db_del $db, undef, "key";
26 };
27 db_sync $db;
28
29 # automatic result processing with AnyEvent:
30 our $FH; open $FH, "<&=" . BDB::poll_fileno;
31 our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&BDB::poll_cb);
32
33 # automatic result processing with EV:
34 my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;
35
36 # with Glib:
37 add_watch Glib::IO BDB::poll_fileno,
38 in => sub { BDB::poll_cb; 1 };
39
40 # or simply flush manually
41 BDB::flush;
42
8 43
9=head1 DESCRIPTION 44=head1 DESCRIPTION
10 45
11See the BerkeleyDB documentation (L<http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>). 46See the BerkeleyDB documentation (L<http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>).
12The BDB API is very similar to the C API (the translation has been very faithful). 47The BDB API is very similar to the C API (the translation has been very faithful).
… …
72use strict 'vars'; 107use strict 'vars';
73 108
74use base 'Exporter'; 109use base 'Exporter';
75 110
76BEGIN { 111BEGIN {
77 our $VERSION = '1.1'; 112 our $VERSION = '1.2';
78 113
79 our @BDB_REQ = qw( 114 our @BDB_REQ = qw(
80 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect 115 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
81 db_env_memp_sync db_env_memp_trickle 116 db_env_memp_sync db_env_memp_trickle
82 db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range 117 db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range
… …
242 $int = $env->set_lk_max_lockers (U32 max) 277 $int = $env->set_lk_max_lockers (U32 max)
243 $int = $env->set_lk_max_locks (U32 max) 278 $int = $env->set_lk_max_locks (U32 max)
244 $int = $env->set_lk_max_objects (U32 max) 279 $int = $env->set_lk_max_objects (U32 max)
245 $int = $env->set_lg_bsize (U32 max) 280 $int = $env->set_lg_bsize (U32 max)
246 $int = $env->set_lg_max (U32 max) 281 $int = $env->set_lg_max (U32 max)
282 $int = $env->mutex_set_increment (U32 increment)
283 $int = $env->mutex_set_tas_spins (U32 tas_spins)
284 $int = $env->mutex_set_max (U32 max)
285 $int = $env->mutex_set_align (U32 align)
247 286
248 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0) 287 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
249 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC 288 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
250 289
251=head4 Example: 290=head4 Example:
… …
435interactiveness when perl is not fast enough to process all requests in 474interactiveness when perl is not fast enough to process all requests in
436time. 475time.
437 476
438For interactive programs, values such as C<0.01> to C<0.1> should be fine. 477For interactive programs, values such as C<0.01> to C<0.1> should be fine.
439 478
440Example: Install an Event watcher that automatically calls 479Example: Install an EV watcher that automatically calls
441BDB::poll_cb with low priority, to ensure that other parts of the 480BDB::poll_cb with low priority, to ensure that other parts of the
442program get the CPU sometimes even under high AIO load. 481program get the CPU sometimes even under high load.
443 482
444 # try not to spend much more than 0.1s in poll_cb 483 # try not to spend much more than 0.1s in poll_cb
445 BDB::max_poll_time 0.1; 484 BDB::max_poll_time 0.1;
446 485
447 # use a low priority so other tasks have priority 486 my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
448 Event->io (fd => BDB::poll_fileno,
449 poll => 'r', nice => 1,
450 cb => &BDB::poll_cb);
451 487
452=item BDB::poll_wait 488=item BDB::poll_wait
453 489
454If there are any outstanding requests and none of them in the result 490If there are any outstanding requests and none of them in the result
455phase, wait till the result filehandle becomes ready for reading (simply 491phase, wait till the result filehandle becomes ready for reading (simply
… …
467 503
468 BDB::poll_wait, BDB::poll_cb 504 BDB::poll_wait, BDB::poll_cb
469 505
470=item BDB::flush 506=item BDB::flush
471 507
472Wait till all outstanding AIO requests have been handled. 508Wait till all outstanding BDB requests have been handled.
473 509
474Strictly equivalent to: 510Strictly equivalent to:
475 511
476 BDB::poll_wait, BDB::poll_cb 512 BDB::poll_wait, BDB::poll_cb
477 while BDB::nreqs; 513 while BDB::nreqs;
… …
482 518
483=over 4 519=over 4
484 520
485=item BDB::min_parallel $nthreads 521=item BDB::min_parallel $nthreads
486 522
487Set the minimum number of AIO threads to C<$nthreads>. The current 523Set the minimum number of BDB threads to C<$nthreads>. The current
488default is C<8>, which means eight asynchronous operations can execute 524default is C<8>, which means eight asynchronous operations can execute
489concurrently at any one time (the number of outstanding requests, 525concurrently at any one time (the number of outstanding requests,
490however, is unlimited). 526however, is unlimited).
491 527
492BDB starts threads only on demand, when an AIO request is queued and 528BDB starts threads only on demand, when an BDB request is queued and
493no free thread exists. Please note that queueing up a hundred requests can 529no free thread exists. Please note that queueing up a hundred requests can
494create demand for a hundred threads, even if it turns out that everything 530create demand for a hundred threads, even if it turns out that everything
495is in the cache and could have been processed faster by a single thread. 531is in the cache and could have been processed faster by a single thread.
496 532
497It is recommended to keep the number of threads relatively low, as some 533It is recommended to keep the number of threads relatively low, as some
… …
502Under most circumstances you don't need to call this function, as the 538Under most circumstances you don't need to call this function, as the
503module selects a default that is suitable for low to moderate load. 539module selects a default that is suitable for low to moderate load.
504 540
505=item BDB::max_parallel $nthreads 541=item BDB::max_parallel $nthreads
506 542
507Sets the maximum number of AIO threads to C<$nthreads>. If more than the 543Sets the maximum number of BDB threads to C<$nthreads>. If more than the
508specified number of threads are currently running, this function kills 544specified number of threads are currently running, this function kills
509them. This function blocks until the limit is reached. 545them. This function blocks until the limit is reached.
510 546
511While C<$nthreads> are zero, aio requests get queued but not executed 547While C<$nthreads> are zero, aio requests get queued but not executed
512until the number of threads has been increased again. 548until the number of threads has been increased again.
… …
615 651
616=head2 FORK BEHAVIOUR 652=head2 FORK BEHAVIOUR
617 653
618This module should do "the right thing" when the process using it forks: 654This module should do "the right thing" when the process using it forks:
619 655
620Before the fork, IO::AIO enters a quiescent state where no requests 656Before the fork, BDB enters a quiescent state where no requests
621can be added in other threads and no results will be processed. After 657can be added in other threads and no results will be processed. After
622the fork the parent simply leaves the quiescent state and continues 658the fork the parent simply leaves the quiescent state and continues
623request/result processing, while the child frees the request/result queue 659request/result processing, while the child frees the request/result queue
624(so that the requests started before the fork will only be handled in the 660(so that the requests started before the fork will only be handled in the
625parent). Threads will be started on demand until the limit set in the 661parent). Threads will be started on demand until the limit set in the
626parent process has been reached again. 662parent process has been reached again.
627 663
628In short: the parent will, after a short pause, continue as if fork had 664In short: the parent will, after a short pause, continue as if fork had
629not been called, while the child will act as if IO::AIO has not been used 665not been called, while the child will act as if BDB has not been used
630yet. 666yet.
631 667
632=head2 MEMORY USAGE 668=head2 MEMORY USAGE
633 669
634Per-request usage: 670Per-request usage:
… …
657 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>, 693 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
658 above. 694 above.
659 695
660=head1 SEE ALSO 696=head1 SEE ALSO
661 697
662L<Coro::AIO>. 698L<Coro::BDB>, L<IO::AIO>.
663 699
664=head1 AUTHOR 700=head1 AUTHOR
665 701
666 Marc Lehmann <schmorp@schmorp.de> 702 Marc Lehmann <schmorp@schmorp.de>
667 http://home.schmorp.de/ 703 http://home.schmorp.de/

Diff Legend

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