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

Comparing BDB/BDB.pm (file contents):
Revision 1.11 by root, Mon Aug 13 12:04:41 2007 UTC vs.
Revision 1.48 by root, Tue Jul 29 03:33:16 2008 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use BDB; 7 use BDB;
8 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 # when you also use Coro, management is easy:
30 use Coro::BDB;
31
32 # automatic event loop intergration with AnyEvent:
33 use AnyEvent::BDB;
34
35 # automatic result processing with EV:
36 my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;
37
38 # with Glib:
39 add_watch Glib::IO BDB::poll_fileno,
40 in => sub { BDB::poll_cb; 1 };
41
42 # or simply flush manually
43 BDB::flush;
44
45
9=head1 DESCRIPTION 46=head1 DESCRIPTION
10 47
11See the BerkeleyDB documentation (L<http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>). 48See 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 ahs been very faithful). 49The BDB API is very similar to the C API (the translation has been very faithful).
13 50
14See also the example sections in the document below and possibly the eg/ 51See also the example sections in the document below and possibly the eg/
15subdirectory of the BDB distribution. Last not least see the IO::AIO 52subdirectory of the BDB distribution. Last not least see the IO::AIO
16documentation, as that module uses almost the same asynchronous request 53documentation, as that module uses almost the same asynchronous request
17model as this module. 54model as this module.
… …
71no warnings; 108no warnings;
72use strict 'vars'; 109use strict 'vars';
73 110
74use base 'Exporter'; 111use base 'Exporter';
75 112
113our $VERSION;
114
76BEGIN { 115BEGIN {
77 our $VERSION = '1.0'; 116 $VERSION = '1.71';
78 117
79 our @BDB_REQ = qw( 118 our @BDB_REQ = qw(
80 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
81 db_env_memp_sync db_env_memp_trickle 120 db_env_memp_sync db_env_memp_trickle db_env_dbrename db_env_dbremove
82 db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range 121 db_open db_close db_compact db_sync db_upgrade
122 db_put db_exists db_get db_pget db_del db_key_range
83 db_txn_commit db_txn_abort 123 db_txn_commit db_txn_abort db_txn_finish
84 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
85 db_sequence_open db_sequence_close 125 db_sequence_open db_sequence_close
86 db_sequence_get db_sequence_remove 126 db_sequence_get db_sequence_remove
87 ); 127 );
88 our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create)); 128 our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create));
… …
95 135
96 require XSLoader; 136 require XSLoader;
97 XSLoader::load ("BDB", $VERSION); 137 XSLoader::load ("BDB", $VERSION);
98} 138}
99 139
140=head2 WIN32 FILENAMES/DATABASE NAME MESS
141
142Perl on Win32 supports only ASCII filenames (the reason is that it abuses
143an internal flag to store wether a filename is Unicode or ANSI, but that
144flag is used for somethign else in the perl core, so there is no way to
145detect wether a filename is ANSI or Unicode-encoded). The BDB module
146tries to work around this issue by assuming that the filename is an ANSI
147filename and BDB was built for unicode support.
148
100=head2 BERKELEYDB FUNCTIONS 149=head2 BERKELEYDB FUNCTIONS
101 150
102All of these are functions. The create functions simply return a new 151All of these are functions. The create functions simply return a new
103object and never block. All the remaining functions all take an optional 152object and never block. All the remaining functions take an optional
104callback as last argument. If it is missing, then the fucntion will be 153callback as last argument. If it is missing, then the function will be
105executed synchronously. 154executed synchronously. In both cases, C<$!> will reflect the return value
155of the function.
106 156
107BDB functions that cannot block (mostly functions that manipulate 157BDB functions that cannot block (mostly functions that manipulate
108settings) 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
109is: if its a method, its not blocking, if its a function, it takes a 159is: if it's a method, it's not blocking, if it's a function, it takes a
110callback as last argument. 160callback as last argument.
111 161
112In the following, C<$int> signifies an integer return value, 162In the following, C<$int> signifies an integer return value,
113C<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),
114indices >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
115integer, C<NV> is a floating point value. 165floating point value.
116 166
117The 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
118values), and the C<SV *callback> is the optional callback function to call 168values).
119when the request is completed.
120 169
121The various C<DB_ENV> etc. arguments are handles return by 170The various C<DB_ENV> etc. arguments are handles return by
122C<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
123appended 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>
124for them, resulting a NULL pointer on the C level. 173for them, resulting a NULL pointer on the C level.
125 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
126=head3 BDB functions 198=head3 BDB functions
127 199
128Functions in the BDB namespace, exported by default: 200Functions in the BDB namespace, exported by default:
129 201
130 $env = db_env_create (U32 env_flags = 0) 202 $env = db_env_create (U32 env_flags = 0)
203 flags: RPCCLIENT
131 204
132 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)
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
133 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)
134 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)
209 flags: FORCE
135 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)
211 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
136 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)
137 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)
138 216
139 $db = db_create (DB_ENV *env = 0, U32 flags = 0) 217 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
218 flags: XA_CREATE
140 219
141 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)
221 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
142 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)
223 flags: DB_NOSYNC
224 db_upgrade (DB *db, bdb_filename file, U32 flags = 0, SV *callback = &PL_sv_undef)
143 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_unde 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)
226 flags: FREELIST_ONLY FREE_SPACE
144 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)
145 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)
146 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)
230 flags: APPEND NODUPDATA NOOVERWRITE
231 db_exists (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = 0) (v4.6)
147 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)
233 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
148 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)
235 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
149 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)
150 db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef) 237 db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
238 flags: TXN_NOSYNC TXN_SYNC
151 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef) 239 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef)
240
152 db_c_close (DBC *dbc, SV *callback = &PL_sv_undef) 241 db_c_close (DBC *dbc, SV *callback = &PL_sv_undef)
153 db_c_count (DBC *dbc, SV *count, U32 flags = 0, SV *callback = &PL_sv_undef) 242 db_c_count (DBC *dbc, SV *count, U32 flags = 0, SV *callback = &PL_sv_undef)
154 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 243 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
244 flags: AFTER BEFORE CURRENT KEYFIRST KEYLAST NODUPDATA
155 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 245 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
246 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
156 db_c_pget (DBC *dbc, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 247 db_c_pget (DBC *dbc, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
157 db_c_del (DBC *dbc, U32 flags = 0, SV *callback = &PL_sv_undef) 248 db_c_del (DBC *dbc, U32 flags = 0, SV *callback = &PL_sv_undef)
158 249
159 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef) 250 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef)
251 flags: CREATE EXCL
160 db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = &PL_sv_undef) 252 db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = &PL_sv_undef)
161 db_sequence_get (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, int delta, SV *seq_value, U32 flags = DB_TXN_NOSYNC, SV *callback = &PL_sv_undef) 253 db_sequence_get (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, int delta, SV *seq_value, U32 flags = DB_TXN_NOSYNC, SV *callback = &PL_sv_undef)
254 flags: TXN_NOSYNC
162 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 255 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
256 flags: TXN_NOSYNC
163 257
258=head4 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
259
260This is not actually a Berkeley DB function but a BDB module
261extension. The background for this exytension is: It is very annoying to
262have to check every single BDB function for error returns and provide a
263codepath out of your transaction. While the BDB module still makes this
264possible, it contains the following extensions:
265
266When a transaction-protected function returns any operating system
267error (errno > 0), BDB will set the C<TXN_DEADLOCK> flag on the
268transaction. This flag is also set by Berkeley DB functions themselves
269when an operation fails with LOCK_DEADLOCK, and it causes all further
270operations on that transaction (including C<db_txn_commit>) to fail.
271
272The C<db_txn_finish> request will look at this flag, and, if it is set,
273will automatically call C<db_txn_abort> (setting errno to C<LOCK_DEADLOCK>
274if it isn't set to something else yet). If it isn't set, it will call
275C<db_txn_commit> and return the error normally.
276
277How to use this? Easy: just write your transaction normally:
278
279 my $txn = $db_env->txn_begin;
280 db_get $db, $txn, "key", my $data;
281 db_put $db, $txn, "key", $data + 1 unless $! == BDB::NOTFOUND;
282 db_txn_finish $txn;
283 die "transaction failed" if $!;
284
285That is, handle only the expected errors. If something unexpected happens
286(EIO, LOCK_NOTGRANTED or a deadlock in either db_get or db_put), then the remaining
287requests (db_put in this case) will simply be skipped (they will fail with
288LOCK_DEADLOCK) and the transaction will be aborted.
289
290You can use the C<< $txn->failed >> method to check wether a transaction
291has failed in this way and abort further processing (excluding
292C<db_txn_finish>).
164 293
165=head3 DB_ENV/database environment methods 294=head3 DB_ENV/database environment methods
166 295
167Methods available on DB_ENV/$env handles: 296Methods available on DB_ENV/$env handles:
168 297
… …
174 $int = $env->set_data_dir (const char *dir) 303 $int = $env->set_data_dir (const char *dir)
175 $int = $env->set_tmp_dir (const char *dir) 304 $int = $env->set_tmp_dir (const char *dir)
176 $int = $env->set_lg_dir (const char *dir) 305 $int = $env->set_lg_dir (const char *dir)
177 $int = $env->set_shm_key (long shm_key) 306 $int = $env->set_shm_key (long shm_key)
178 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 307 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
179 $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)
180 $env->set_errfile (FILE *errfile = 0) 311 $env->set_errfile (FILE *errfile = 0)
181 $env->set_msgfile (FILE *msgfile = 0) 312 $env->set_msgfile (FILE *msgfile = 0)
182 $int = $env->set_verbose (U32 which, int onoff = 1) 313 $int = $env->set_verbose (U32 which, int onoff = 1)
183 $int = $env->set_encrypt (const char *password, U32 flags = 0) 314 $int = $env->set_encrypt (const char *password, U32 flags = 0)
184 $int = $env->set_timeout (NV timeout, U32 flags) 315 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
185 $int = $env->set_mp_max_openfd (int maxopenfd); 316 $int = $env->set_mp_max_openfd (int maxopenfd);
186 $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep); 317 $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep);
187 $int = $env->set_mp_mmapsize (int mmapsize_mb) 318 $int = $env->set_mp_mmapsize (int mmapsize_mb)
188 $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT) 319 $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT)
189 $int = $env->set_lk_max_lockers (U32 max) 320 $int = $env->set_lk_max_lockers (U32 max)
190 $int = $env->set_lk_max_locks (U32 max) 321 $int = $env->set_lk_max_locks (U32 max)
191 $int = $env->set_lk_max_objects (U32 max) 322 $int = $env->set_lk_max_objects (U32 max)
192 $int = $env->set_lg_bsize (U32 max) 323 $int = $env->set_lg_bsize (U32 max)
193 $int = $env->set_lg_max (U32 max) 324 $int = $env->set_lg_max (U32 max)
325 $int = $env->mutex_set_increment (U32 increment)
326 $int = $env->mutex_set_tas_spins (U32 tas_spins)
327 $int = $env->mutex_set_max (U32 max)
328 $int = $env->mutex_set_align (U32 align)
194 329
195 $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)
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)
196 333
197=head4 example 334=head4 Example:
198 335
199 use AnyEvent; 336 use AnyEvent;
200 use BDB; 337 use BDB;
201 338
202 our $FH; open $FH, "<&=" . BDB::poll_fileno; 339 our $FH; open $FH, "<&=" . BDB::poll_fileno;
… …
229 SvREFCNT_dec (env); 366 SvREFCNT_dec (env);
230 } 367 }
231 368
232 $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 369 $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
233 $int = $db->set_flags (U32 flags) 370 $int = $db->set_flags (U32 flags)
371 flags: CHKSUM ENCRYPT TXN_NOT_DURABLE
372 Btree: DUP DUPSORT RECNUM REVSPLITOFF
373 Hash: DUP DUPSORT
374 Queue: INORDER
375 Recno: RENUMBER SNAPSHOT
376
234 $int = $db->set_encrypt (const char *password, U32 flags) 377 $int = $db->set_encrypt (const char *password, U32 flags)
235 $int = $db->set_lorder (int lorder) 378 $int = $db->set_lorder (int lorder)
236 $int = $db->set_bt_minkey (U32 minkey) 379 $int = $db->set_bt_minkey (U32 minkey)
237 $int = $db->set_re_delim (int delim) 380 $int = $db->set_re_delim (int delim)
238 $int = $db->set_re_pad (int re_pad) 381 $int = $db->set_re_pad (int re_pad)
… …
241 $int = $db->set_h_ffactor (U32 h_ffactor) 384 $int = $db->set_h_ffactor (U32 h_ffactor)
242 $int = $db->set_h_nelem (U32 h_nelem) 385 $int = $db->set_h_nelem (U32 h_nelem)
243 $int = $db->set_q_extentsize (U32 extentsize) 386 $int = $db->set_q_extentsize (U32 extentsize)
244 387
245 $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0) 388 $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0)
389 flags: READ_COMMITTED READ_UNCOMMITTED WRITECURSOR TXN_SNAPSHOT
246 $seq = $db->sequence (U32 flags = 0) 390 $seq = $db->sequence (U32 flags = 0)
247 391
248=head4 example 392=head4 Example:
249 393
250 my $db = db_create $env; 394 my $db = db_create $env;
251 db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE | BDB::READ_UNCOMMITTED, 0600; 395 db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE | BDB::READ_UNCOMMITTED, 0600;
252 396
253 for (1..1000) { 397 for (1..1000) {
… …
269 DESTROY (DB_TXN_ornull *txn) 413 DESTROY (DB_TXN_ornull *txn)
270 CODE: 414 CODE:
271 if (txn) 415 if (txn)
272 txn->abort (txn); 416 txn->abort (txn);
273 417
274 $int = $txn->set_timeout (NV timeout, U32 flags) 418 $int = $txn->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
419 flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
420
421 $bool = $txn->failed
422 # see db_txn_finish documentation, above
275 423
276 424
277=head3 DBC/cursor methods 425=head3 DBC/cursor methods
278 426
279Methods available on DBC/$dbc handles: 427Methods available on DBC/$dbc handles:
… …
281 DESTROY (DBC_ornull *dbc) 429 DESTROY (DBC_ornull *dbc)
282 CODE: 430 CODE:
283 if (dbc) 431 if (dbc)
284 dbc->c_close (dbc); 432 dbc->c_close (dbc);
285 433
434 $int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
435
286=head4 example 436=head4 Example:
287 437
288 my $c = $db->cursor; 438 my $c = $db->cursor;
289 439
290 for (;;) { 440 for (;;) {
291 db_c_get $c, my $key, my $data, BDB::NEXT; 441 db_c_get $c, my $key, my $data, BDB::NEXT;
… …
293 last if $!; 443 last if $!;
294 } 444 }
295 445
296 db_c_close $c; 446 db_c_close $c;
297 447
448
298=head3 DB_SEQUENCE/sequence methods 449=head3 DB_SEQUENCE/sequence methods
299 450
300Methods available on DB_SEQUENCE/$seq handles: 451Methods available on DB_SEQUENCE/$seq handles:
301 452
302 DESTROY (DB_SEQUENCE_ornull *seq) 453 DESTROY (DB_SEQUENCE_ornull *seq)
… …
305 seq->close (seq, 0); 456 seq->close (seq, 0);
306 457
307 $int = $seq->initial_value (db_seq_t value) 458 $int = $seq->initial_value (db_seq_t value)
308 $int = $seq->set_cachesize (U32 size) 459 $int = $seq->set_cachesize (U32 size)
309 $int = $seq->set_flags (U32 flags) 460 $int = $seq->set_flags (U32 flags)
461 flags: SEQ_DEC SEQ_INC SEQ_WRAP
310 $int = $seq->set_range (db_seq_t min, db_seq_t max) 462 $int = $seq->set_range (db_seq_t min, db_seq_t max)
311 463
312=head4 example 464=head4 Example:
313 465
314 my $seq = $db->sequence; 466 my $seq = $db->sequence;
315 467
316 db_sequence_open $seq, undef, "seq", BDB::CREATE; 468 db_sequence_open $seq, undef, "seq", BDB::CREATE;
317 db_sequence_get $seq, undef, 1, my $value; 469 db_sequence_get $seq, undef, 1, my $value;
… …
320=head2 SUPPORT FUNCTIONS 472=head2 SUPPORT FUNCTIONS
321 473
322=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 474=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
323 475
324=over 4 476=over 4
477
478=item $msg = BDB::strerror [$errno]
479
480Returns the string corresponding to the given errno value. If no argument
481is given, use C<$!>.
482
483Note that the BDB module also patches the C<$!> variable directly, so you
484should be able to get a bdb error string by simply stringifying C<$!>.
325 485
326=item $fileno = BDB::poll_fileno 486=item $fileno = BDB::poll_fileno
327 487
328Return the I<request result pipe file descriptor>. This filehandle must be 488Return the I<request result pipe file descriptor>. This filehandle must be
329polled for reading by some mechanism outside this module (e.g. Event or 489polled for reading by some mechanism outside this module (e.g. Event or
… …
368interactiveness when perl is not fast enough to process all requests in 528interactiveness when perl is not fast enough to process all requests in
369time. 529time.
370 530
371For interactive programs, values such as C<0.01> to C<0.1> should be fine. 531For interactive programs, values such as C<0.01> to C<0.1> should be fine.
372 532
373Example: Install an Event watcher that automatically calls 533Example: Install an EV watcher that automatically calls
374BDB::poll_cb with low priority, to ensure that other parts of the 534BDB::poll_cb with low priority, to ensure that other parts of the
375program get the CPU sometimes even under high AIO load. 535program get the CPU sometimes even under high load.
376 536
377 # try not to spend much more than 0.1s in poll_cb 537 # try not to spend much more than 0.1s in poll_cb
378 BDB::max_poll_time 0.1; 538 BDB::max_poll_time 0.1;
379 539
380 # use a low priority so other tasks have priority 540 my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
381 Event->io (fd => BDB::poll_fileno,
382 poll => 'r', nice => 1,
383 cb => &BDB::poll_cb);
384 541
385=item BDB::poll_wait 542=item BDB::poll_wait
386 543
387If there are any outstanding requests and none of them in the result 544If there are any outstanding requests and none of them in the result
388phase, wait till the result filehandle becomes ready for reading (simply 545phase, wait till the result filehandle becomes ready for reading (simply
… …
400 557
401 BDB::poll_wait, BDB::poll_cb 558 BDB::poll_wait, BDB::poll_cb
402 559
403=item BDB::flush 560=item BDB::flush
404 561
405Wait till all outstanding AIO requests have been handled. 562Wait till all outstanding BDB requests have been handled.
406 563
407Strictly equivalent to: 564Strictly equivalent to:
408 565
409 BDB::poll_wait, BDB::poll_cb 566 BDB::poll_wait, BDB::poll_cb
410 while BDB::nreqs; 567 while BDB::nreqs;
411 568
412=back 569=back
413 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
414=head3 CONTROLLING THE NUMBER OF THREADS 637=head3 CONTROLLING THE NUMBER OF THREADS
415 638
416=over 4 639=over 4
417 640
418=item BDB::min_parallel $nthreads 641=item BDB::min_parallel $nthreads
419 642
420Set the minimum number of AIO threads to C<$nthreads>. The current 643Set the minimum number of BDB threads to C<$nthreads>. The current
421default is C<8>, which means eight asynchronous operations can execute 644default is C<8>, which means eight asynchronous operations can execute
422concurrently at any one time (the number of outstanding requests, 645concurrently at any one time (the number of outstanding requests,
423however, is unlimited). 646however, is unlimited).
424 647
425BDB starts threads only on demand, when an AIO request is queued and 648BDB starts threads only on demand, when an BDB request is queued and
426no free thread exists. Please note that queueing up a hundred requests can 649no free thread exists. Please note that queueing up a hundred requests can
427create demand for a hundred threads, even if it turns out that everything 650create demand for a hundred threads, even if it turns out that everything
428is in the cache and could have been processed faster by a single thread. 651is in the cache and could have been processed faster by a single thread.
429 652
430It is recommended to keep the number of threads relatively low, as some 653It is recommended to keep the number of threads relatively low, as some
… …
435Under most circumstances you don't need to call this function, as the 658Under most circumstances you don't need to call this function, as the
436module selects a default that is suitable for low to moderate load. 659module selects a default that is suitable for low to moderate load.
437 660
438=item BDB::max_parallel $nthreads 661=item BDB::max_parallel $nthreads
439 662
440Sets the maximum number of AIO threads to C<$nthreads>. If more than the 663Sets the maximum number of BDB threads to C<$nthreads>. If more than the
441specified number of threads are currently running, this function kills 664specified number of threads are currently running, this function kills
442them. This function blocks until the limit is reached. 665them. This function blocks until the limit is reached.
443 666
444While C<$nthreads> are zero, aio requests get queued but not executed 667While C<$nthreads> are zero, aio requests get queued but not executed
445until the number of threads has been increased again. 668until the number of threads has been increased again.
… …
484 707
485=item BDB::set_sync_prepare $cb 708=item BDB::set_sync_prepare $cb
486 709
487Sets 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
488explicit 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
489as 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
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<AnyEvent::BDB> or L<Coro::BDB>.
718
490callback has been called. The default implementation works like this: 719The default implementation works like this:
491 720
492 sub { 721 sub {
493 my $status; 722 my $status;
494 ( 723 (
495 sub { $status = $! }, 724 sub { $status = $! },
496 sub { BDB::poll while !defined $status; $! = $status }, 725 sub { BDB::poll while !defined $status; $! = $status },
497 ) 726 )
498 } 727 }
728
729It simply blocks the process till the request has finished and then sets
730C<$!> to the return value. This means that if you don't use a callback,
731BDB will simply fall back to synchronous operations.
499 732
500=back 733=back
501 734
502=head3 STATISTICAL INFORMATION 735=head3 STATISTICAL INFORMATION
503 736
… …
548 781
549=head2 FORK BEHAVIOUR 782=head2 FORK BEHAVIOUR
550 783
551This module should do "the right thing" when the process using it forks: 784This module should do "the right thing" when the process using it forks:
552 785
553Before the fork, IO::AIO enters a quiescent state where no requests 786Before the fork, BDB enters a quiescent state where no requests
554can be added in other threads and no results will be processed. After 787can be added in other threads and no results will be processed. After
555the fork the parent simply leaves the quiescent state and continues 788the fork the parent simply leaves the quiescent state and continues
556request/result processing, while the child frees the request/result queue 789request/result processing, while the child frees the request/result queue
557(so that the requests started before the fork will only be handled in the 790(so that the requests started before the fork will only be handled in the
558parent). Threads will be started on demand until the limit set in the 791parent). Threads will be started on demand until the limit set in the
559parent process has been reached again. 792parent process has been reached again.
560 793
561In short: the parent will, after a short pause, continue as if fork had 794In short: the parent will, after a short pause, continue as if fork had
562not been called, while the child will act as if IO::AIO has not been used 795not been called, while the child will act as if BDB has not been used
563yet. 796yet.
797
798Win32 note: there is no fork on win32, and perls emulation of it is too
799broken to be supported, so do not use BDB in a windows pseudo-fork, better
800yet, switch to a more capable platform.
564 801
565=head2 MEMORY USAGE 802=head2 MEMORY USAGE
566 803
567Per-request usage: 804Per-request usage:
568 805
… …
570bytes of memory. In addition, stat requests need a stat buffer (possibly 807bytes of memory. In addition, stat requests need a stat buffer (possibly
571a few hundred bytes), readdir requires a result buffer and so on. Perl 808a few hundred bytes), readdir requires a result buffer and so on. Perl
572scalars and other data passed into aio requests will also be locked and 809scalars and other data passed into aio requests will also be locked and
573will consume memory till the request has entered the done state. 810will consume memory till the request has entered the done state.
574 811
575This is now awfully much, so queuing lots of requests is not usually a 812This is not awfully much, so queuing lots of requests is not usually a
576problem. 813problem.
577 814
578Per-thread usage: 815Per-thread usage:
579 816
580In the execution phase, some aio requests require more memory for 817In the execution phase, some aio requests require more memory for
581temporary buffers, and each thread requires a stack and other data 818temporary buffers, and each thread requires a stack and other data
582structures (usually around 16k-128k, depending on the OS). 819structures (usually around 16k-128k, depending on the OS).
583 820
584=head1 KNOWN BUGS 821=head1 KNOWN BUGS
585 822
586Known bugs will be fixed in the next release. 823Known bugs will be fixed in the next release, except:
824
825 If you use a transaction in any request, and the request returns
826 with an operating system error or DB_LOCK_NOTGRANTED, the internal
827 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
828 above.
587 829
588=head1 SEE ALSO 830=head1 SEE ALSO
589 831
590L<Coro::AIO>. 832L<AnyEvent::BDB> (event loop integration), L<Coro::BDB> (more natural
833syntax), L<IO::AIO> (nice to have).
591 834
592=head1 AUTHOR 835=head1 AUTHOR
593 836
594 Marc Lehmann <schmorp@schmorp.de> 837 Marc Lehmann <schmorp@schmorp.de>
595 http://home.schmorp.de/ 838 http://home.schmorp.de/

Diff Legend

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