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

Comparing BDB/BDB.pm (file contents):
Revision 1.2 by root, Mon Feb 5 20:21:38 2007 UTC vs.
Revision 1.12 by root, Mon Aug 13 12:07:46 2007 UTC

… …
6 6
7 use BDB; 7 use BDB;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11=head2 EXAMPLE 11See 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).
13
14See also the example sections in the document below and possibly the eg/
15subdirectory of the BDB distribution. Last not least see the IO::AIO
16documentation, as that module uses almost the same asynchronous request
17model as this module.
18
19I know this is woefully inadequate documentation. Send a patch!
20
12 21
13=head1 REQUEST ANATOMY AND LIFETIME 22=head1 REQUEST ANATOMY AND LIFETIME
14 23
15Every request method creates a request. which is a C data structure not 24Every request method creates a request. which is a C data structure not
16directly visible to Perl. 25directly visible to Perl.
… …
63use strict 'vars'; 72use strict 'vars';
64 73
65use base 'Exporter'; 74use base 'Exporter';
66 75
67BEGIN { 76BEGIN {
68 our $VERSION = '0.1'; 77 our $VERSION = '1.0';
69 78
70 our @BDB_REQ = qw(); 79 our @BDB_REQ = qw(
80 db_env_open db_env_close db_env_txn_checkpoint db_env_lock_detect
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
83 db_txn_commit db_txn_abort
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
86 db_sequence_get db_sequence_remove
87 );
88 our @EXPORT = (@BDB_REQ, qw(dbreq_pri dbreq_nice db_env_create db_create));
89 our @EXPORT_OK = qw(
71 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 90 poll_fileno poll_cb poll_wait flush
72 min_parallel max_parallel max_idle 91 min_parallel max_parallel max_idle
73 nreqs nready npending nthreads 92 nreqs nready npending nthreads
74 max_poll_time max_poll_reqs); 93 max_poll_time max_poll_reqs
94 );
75 95
76 require XSLoader; 96 require XSLoader;
77 XSLoader::load ("BDB", $VERSION); 97 XSLoader::load ("BDB", $VERSION);
78} 98}
99
100=head2 BERKELEYDB FUNCTIONS
101
102All of these are functions. The create functions simply return a new
103object and never block. All the remaining functions all take an optional
104callback as last argument. If it is missing, then the fucntion will be
105executed synchronously.
106
107BDB functions that cannot block (mostly functions that manipulate
108settings) 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
110callback as last argument.
111
112In the following, C<$int> signifies an integer return value,
113C<octetstring> is a "binary string" (i.e. a perl string with no character
114indices >255), C<U32> is an unsigned 32 bit integer, C<int> is some
115integer, C<NV> is a floating point value.
116
117The 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
119when the request is completed.
120
121The 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
123appended C<_ornull> this means they are optional and you can pass C<undef>
124for them, resulting a NULL pointer on the C level.
125
126=head3 BDB functions
127
128Functions in the BDB namespace, exported by default:
129
130 $env = db_env_create (U32 env_flags = 0)
131
132 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, 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)
135 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_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)
138
139 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
140
141 db_open (DB *db, DB_TXN_ornull *txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef)
142 db_close (DB *db, 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_undef)
144 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)
146 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
147 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
148 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
149 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)
151 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef)
152 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)
154 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
155 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef)
156 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)
158
159 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef)
160 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)
162 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef)
163
164
165=head3 DB_ENV/database environment methods
166
167Methods available on DB_ENV/$env handles:
168
169 DESTROY (DB_ENV_ornull *env)
170 CODE:
171 if (env)
172 env->close (env, 0);
173
174 $int = $env->set_data_dir (const char *dir)
175 $int = $env->set_tmp_dir (const char *dir)
176 $int = $env->set_lg_dir (const char *dir)
177 $int = $env->set_shm_key (long shm_key)
178 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
179 $int = $env->set_flags (U32 flags, int onoff)
180 $env->set_errfile (FILE *errfile = 0)
181 $env->set_msgfile (FILE *msgfile = 0)
182 $int = $env->set_verbose (U32 which, int onoff = 1)
183 $int = $env->set_encrypt (const char *password, U32 flags = 0)
184 $int = $env->set_timeout (NV timeout, U32 flags)
185 $int = $env->set_mp_max_openfd (int maxopenfd);
186 $int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep);
187 $int = $env->set_mp_mmapsize (int mmapsize_mb)
188 $int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT)
189 $int = $env->set_lk_max_lockers (U32 max)
190 $int = $env->set_lk_max_locks (U32 max)
191 $int = $env->set_lk_max_objects (U32 max)
192 $int = $env->set_lg_bsize (U32 max)
193 $int = $env->set_lg_max (U32 max)
194
195 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
196
197=head4 Example:
198
199 use AnyEvent;
200 use BDB;
201
202 our $FH; open $FH, "<&=" . BDB::poll_fileno;
203 our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&BDB::poll_cb);
204
205 BDB::min_parallel 8;
206
207 my $env = db_env_create;
208
209 mkdir "bdtest", 0700;
210 db_env_open
211 $env,
212 "bdtest",
213 BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE,
214 0600;
215
216 $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
217
218
219=head3 DB/database methods
220
221Methods available on DB/$db handles:
222
223 DESTROY (DB_ornull *db)
224 CODE:
225 if (db)
226 {
227 SV *env = (SV *)db->app_private;
228 db->close (db, 0);
229 SvREFCNT_dec (env);
230 }
231
232 $int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
233 $int = $db->set_flags (U32 flags)
234 $int = $db->set_encrypt (const char *password, U32 flags)
235 $int = $db->set_lorder (int lorder)
236 $int = $db->set_bt_minkey (U32 minkey)
237 $int = $db->set_re_delim (int delim)
238 $int = $db->set_re_pad (int re_pad)
239 $int = $db->set_re_source (char *source)
240 $int = $db->set_re_len (U32 re_len)
241 $int = $db->set_h_ffactor (U32 h_ffactor)
242 $int = $db->set_h_nelem (U32 h_nelem)
243 $int = $db->set_q_extentsize (U32 extentsize)
244
245 $dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0)
246 $seq = $db->sequence (U32 flags = 0)
247
248=head4 Example:
249
250 my $db = db_create $env;
251 db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE | BDB::READ_UNCOMMITTED, 0600;
252
253 for (1..1000) {
254 db_put $db, undef, "key $_", "data $_";
255
256 db_key_range $db, undef, "key $_", my $keyrange;
257 my ($lt, $eq, $gt) = @$keyrange;
258 }
259
260 db_del $db, undef, "key $_" for 1..1000;
261
262 db_sync $db;
263
264
265=head3 DB_TXN/transaction methods
266
267Methods available on DB_TXN/$txn handles:
268
269 DESTROY (DB_TXN_ornull *txn)
270 CODE:
271 if (txn)
272 txn->abort (txn);
273
274 $int = $txn->set_timeout (NV timeout, U32 flags)
275
276
277=head3 DBC/cursor methods
278
279Methods available on DBC/$dbc handles:
280
281 DESTROY (DBC_ornull *dbc)
282 CODE:
283 if (dbc)
284 dbc->c_close (dbc);
285
286=head4 Example:
287
288 my $c = $db->cursor;
289
290 for (;;) {
291 db_c_get $c, my $key, my $data, BDB::NEXT;
292 warn "<$!,$key,$data>";
293 last if $!;
294 }
295
296 db_c_close $c;
297
298
299=head3 DB_SEQUENCE/sequence methods
300
301Methods available on DB_SEQUENCE/$seq handles:
302
303 DESTROY (DB_SEQUENCE_ornull *seq)
304 CODE:
305 if (seq)
306 seq->close (seq, 0);
307
308 $int = $seq->initial_value (db_seq_t value)
309 $int = $seq->set_cachesize (U32 size)
310 $int = $seq->set_flags (U32 flags)
311 $int = $seq->set_range (db_seq_t min, db_seq_t max)
312
313=head4 Example:
314
315 my $seq = $db->sequence;
316
317 db_sequence_open $seq, undef, "seq", BDB::CREATE;
318 db_sequence_get $seq, undef, 1, my $value;
319
79 320
80=head2 SUPPORT FUNCTIONS 321=head2 SUPPORT FUNCTIONS
81 322
82=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 323=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
83 324
… …
167Strictly equivalent to: 408Strictly equivalent to:
168 409
169 BDB::poll_wait, BDB::poll_cb 410 BDB::poll_wait, BDB::poll_cb
170 while BDB::nreqs; 411 while BDB::nreqs;
171 412
413=back
414
172=head3 CONTROLLING THE NUMBER OF THREADS 415=head3 CONTROLLING THE NUMBER OF THREADS
416
417=over 4
173 418
174=item BDB::min_parallel $nthreads 419=item BDB::min_parallel $nthreads
175 420
176Set the minimum number of AIO threads to C<$nthreads>. The current 421Set the minimum number of AIO threads to C<$nthreads>. The current
177default is C<8>, which means eight asynchronous operations can execute 422default is C<8>, which means eight asynchronous operations can execute
… …
236 481
237You can still queue as many requests as you want. Therefore, 482You can still queue as many requests as you want. Therefore,
238C<max_oustsanding> is mainly useful in simple scripts (with low values) or 483C<max_oustsanding> is mainly useful in simple scripts (with low values) or
239as a stop gap to shield against fatal memory overflow (with large values). 484as a stop gap to shield against fatal memory overflow (with large values).
240 485
486=item BDB::set_sync_prepare $cb
487
488Sets a callback that is called whenever a request is created without an
489explicit callback. It has to return two code references. The first is used
490as the request callback, and the second is called to wait until the first
491callback has been called. The default implementation works like this:
492
493 sub {
494 my $status;
495 (
496 sub { $status = $! },
497 sub { BDB::poll while !defined $status; $! = $status },
498 )
499 }
500
501=back
502
241=head3 STATISTICAL INFORMATION 503=head3 STATISTICAL INFORMATION
504
505=over 4
242 506
243=item BDB::nreqs 507=item BDB::nreqs
244 508
245Returns the number of requests currently in the ready, execute or pending 509Returns the number of requests currently in the ready, execute or pending
246states (i.e. for which their callback has not been invoked yet). 510states (i.e. for which their callback has not been invoked yet).
… …
261but not yet processed by poll_cb). 525but not yet processed by poll_cb).
262 526
263=back 527=back
264 528
265=cut 529=cut
530
531set_sync_prepare {
532 my $status;
533 (
534 sub {
535 $status = $!;
536 },
537 sub {
538 BDB::poll while !defined $status;
539 $! = $status;
540 },
541 )
542};
266 543
267min_parallel 8; 544min_parallel 8;
268 545
269END { flush } 546END { flush }
270 547

Diff Legend

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