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

Comparing BDB/BDB.pm (file contents):
Revision 1.13 by root, Mon Aug 13 12:07:55 2007 UTC vs.
Revision 1.15 by root, Thu Sep 13 21:34:00 2007 UTC

… …
72use strict 'vars'; 72use strict 'vars';
73 73
74use base 'Exporter'; 74use base 'Exporter';
75 75
76BEGIN { 76BEGIN {
77 our $VERSION = '1.0'; 77 our $VERSION = '1.1';
78 78
79 our @BDB_REQ = qw( 79 our @BDB_REQ = qw(
80 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect 80 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
81 db_env_memp_sync db_env_memp_trickle 81 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 82 db_open db_close db_compact db_sync db_put db_get db_pget db_del db_key_range
83 db_txn_commit db_txn_abort 83 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 84 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 85 db_sequence_open db_sequence_close
86 db_sequence_get db_sequence_remove 86 db_sequence_get db_sequence_remove
87 ); 87 );
88 our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create)); 88 our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create));
… …
126=head3 BDB functions 126=head3 BDB functions
127 127
128Functions in the BDB namespace, exported by default: 128Functions in the BDB namespace, exported by default:
129 129
130 $env = db_env_create (U32 env_flags = 0) 130 $env = db_env_create (U32 env_flags = 0)
131 flags: RPCCLIENT
131 132
132 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef) 133 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef)
134 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) 135 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) 136 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
137 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) 138 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef)
139 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) 140 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) 141 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef)
138 142
139 $db = db_create (DB_ENV *env = 0, U32 flags = 0) 143 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
144 flags: XA_CREATE
140 145
141 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, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef)
147 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) 148 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef)
149 flags: DB_NOSYNC
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_undef) 150 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 flags: FREELIST_ONLY FREE_SPACE
144 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 152 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) 153 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) 154 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
155 flags: APPEND NODUPDATA NOOVERWRITE
147 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 156 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
157 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) 158 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
159 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) 160 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) 161 db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
162 flags: TXN_NOSYNC TXN_SYNC
151 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef) 163 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef)
164
152 db_c_close (DBC *dbc, SV *callback = &PL_sv_undef) 165 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) 166 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) 167 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
168 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) 169 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
170 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) 171 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) 172 db_c_del (DBC *dbc, U32 flags = 0, SV *callback = &PL_sv_undef)
158 173
159 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef) 174 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef)
175 flags: CREATE EXCL
160 db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = &PL_sv_undef) 176 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) 177 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)
178 flags: TXN_NOSYNC
162 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 179 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
180 flags: TXN_NOSYNC
163 181
182=head4 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef)
183
184This is not a Berkeley DB function but a BDB module extension. It is very
185annoying to have to check every single BDB function for error returns and
186provide a codepath out of your transaction. While the BDB module still
187makes this possible, it contains the following extensions:
188
189When a transaction-protected function returns any operating system
190error (errno > 0), BDB will set the C<TXN_DEADLOCK> flag on the
191transaction. This flag is also set by Berkeley DB functions externally
192when an operation fails with LOCK_DEADLOCK, and it causes all further
193operations on that transaction (including C<db_txn_commit>) to fail.
194
195The C<db_txn_finish> request will look at this flag, and, if it is set,
196will automatically call C<db_txn_abort> (setting errno to C<LOCK_DEADLOCK>
197if it isn't set). If it isn't set, it will call C<db_txn_commit> and
198return the error normally.
199
200How to use this? Easy: just write your transaction normally:
201
202 my $txn = $db_env->txn_begin;
203 db_get $db, $txn, "key", my $data;
204 db_put $db, $txn, "key", $data + 1 unless $! == BDB::NOTFOUND;
205 db_txn_finish $txn;
206 die "transaction failed" if $!;
207
208That is, handle only the expected errors. If something unexpected happens
209(EIO, LOCK_NOTGRANTED or a deadlock in either db_get or db_put), then the remaining
210requests (db_put in this case) will simply be skipped (they will fail with
211LOCK_DEADLOCK) and the transaction will be aborted.
212
213You cna use the C<< $txn->failed >> method to check wether a transaction
214has failed in this way and abort further processing (excluding
215C<db_txn_finish>).
164 216
165=head3 DB_ENV/database environment methods 217=head3 DB_ENV/database environment methods
166 218
167Methods available on DB_ENV/$env handles: 219Methods available on DB_ENV/$env handles:
168 220
… …
179 $int = $env->set_flags (U32 flags, int onoff) 231 $int = $env->set_flags (U32 flags, int onoff)
180 $env->set_errfile (FILE *errfile = 0) 232 $env->set_errfile (FILE *errfile = 0)
181 $env->set_msgfile (FILE *msgfile = 0) 233 $env->set_msgfile (FILE *msgfile = 0)
182 $int = $env->set_verbose (U32 which, int onoff = 1) 234 $int = $env->set_verbose (U32 which, int onoff = 1)
183 $int = $env->set_encrypt (const char *password, U32 flags = 0) 235 $int = $env->set_encrypt (const char *password, U32 flags = 0)
184 $int = $env->set_timeout (NV timeout, U32 flags) 236 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
185 $int = $env->set_mp_max_openfd (int maxopenfd); 237 $int = $env->set_mp_max_openfd (int maxopenfd);
186 $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep); 238 $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep);
187 $int = $env->set_mp_mmapsize (int mmapsize_mb) 239 $int = $env->set_mp_mmapsize (int mmapsize_mb)
188 $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT) 240 $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT)
189 $int = $env->set_lk_max_lockers (U32 max) 241 $int = $env->set_lk_max_lockers (U32 max)
… …
191 $int = $env->set_lk_max_objects (U32 max) 243 $int = $env->set_lk_max_objects (U32 max)
192 $int = $env->set_lg_bsize (U32 max) 244 $int = $env->set_lg_bsize (U32 max)
193 $int = $env->set_lg_max (U32 max) 245 $int = $env->set_lg_max (U32 max)
194 246
195 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0) 247 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
248 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
196 249
197=head4 Example: 250=head4 Example:
198 251
199 use AnyEvent; 252 use AnyEvent;
200 use BDB; 253 use BDB;
… …
229 SvREFCNT_dec (env); 282 SvREFCNT_dec (env);
230 } 283 }
231 284
232 $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 285 $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
233 $int = $db->set_flags (U32 flags) 286 $int = $db->set_flags (U32 flags)
287 flags: CHKSUM ENCRYPT TXN_NOT_DURABLE
288 Btree: DUP DUPSORT RECNUM REVSPLITOFF
289 Hash: DUP DUPSORT
290 Queue: INORDER
291 Recno: RENUMBER SNAPSHOT
292
234 $int = $db->set_encrypt (const char *password, U32 flags) 293 $int = $db->set_encrypt (const char *password, U32 flags)
235 $int = $db->set_lorder (int lorder) 294 $int = $db->set_lorder (int lorder)
236 $int = $db->set_bt_minkey (U32 minkey) 295 $int = $db->set_bt_minkey (U32 minkey)
237 $int = $db->set_re_delim (int delim) 296 $int = $db->set_re_delim (int delim)
238 $int = $db->set_re_pad (int re_pad) 297 $int = $db->set_re_pad (int re_pad)
… …
241 $int = $db->set_h_ffactor (U32 h_ffactor) 300 $int = $db->set_h_ffactor (U32 h_ffactor)
242 $int = $db->set_h_nelem (U32 h_nelem) 301 $int = $db->set_h_nelem (U32 h_nelem)
243 $int = $db->set_q_extentsize (U32 extentsize) 302 $int = $db->set_q_extentsize (U32 extentsize)
244 303
245 $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0) 304 $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0)
305 flags: READ_COMMITTED READ_UNCOMMITTED WRITECURSOR TXN_SNAPSHOT
246 $seq = $db->sequence (U32 flags = 0) 306 $seq = $db->sequence (U32 flags = 0)
247 307
248=head4 Example: 308=head4 Example:
249 309
250 my $db = db_create $env; 310 my $db = db_create $env;
… …
269 DESTROY (DB_TXN_ornull *txn) 329 DESTROY (DB_TXN_ornull *txn)
270 CODE: 330 CODE:
271 if (txn) 331 if (txn)
272 txn->abort (txn); 332 txn->abort (txn);
273 333
274 $int = $txn->set_timeout (NV timeout, U32 flags) 334 $int = $txn->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
335 flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
336
337 $bool = $txn->failed
338 # see db_txn_finish documentation, above
275 339
276 340
277=head3 DBC/cursor methods 341=head3 DBC/cursor methods
278 342
279Methods available on DBC/$dbc handles: 343Methods available on DBC/$dbc handles:
… …
306 seq->close (seq, 0); 370 seq->close (seq, 0);
307 371
308 $int = $seq->initial_value (db_seq_t value) 372 $int = $seq->initial_value (db_seq_t value)
309 $int = $seq->set_cachesize (U32 size) 373 $int = $seq->set_cachesize (U32 size)
310 $int = $seq->set_flags (U32 flags) 374 $int = $seq->set_flags (U32 flags)
375 flags: SEQ_DEC SEQ_INC SEQ_WRAP
311 $int = $seq->set_range (db_seq_t min, db_seq_t max) 376 $int = $seq->set_range (db_seq_t min, db_seq_t max)
312 377
313=head4 Example: 378=head4 Example:
314 379
315 my $seq = $db->sequence; 380 my $seq = $db->sequence;
… …
582temporary buffers, and each thread requires a stack and other data 647temporary buffers, and each thread requires a stack and other data
583structures (usually around 16k-128k, depending on the OS). 648structures (usually around 16k-128k, depending on the OS).
584 649
585=head1 KNOWN BUGS 650=head1 KNOWN BUGS
586 651
587Known bugs will be fixed in the next release. 652Known bugs will be fixed in the next release, except:
653
654 If you use a transaction in any request, and the request returns
655 with an operating system error or DB_LOCK_NOTGRANTED, the internal
656 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
657 above.
588 658
589=head1 SEE ALSO 659=head1 SEE ALSO
590 660
591L<Coro::AIO>. 661L<Coro::AIO>.
592 662

Diff Legend

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