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.10 by root, Mon Aug 13 12:01:45 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 ahs 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 = '0.6';
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 db_env_create>,
122C<C<db_create>, C<txn_begin> and so on. If they have an appended _ornull>
123C<this means they are optional and you can pass C<undef> for them,
124C<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_unde
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=head3 DB_SEQUENCE/sequence methods
299
300Methods available on DB_SEQUENCE/$seq handles:
301
302 DESTROY (DB_SEQUENCE_ornull *seq)
303 CODE:
304 if (seq)
305 seq->close (seq, 0);
306
307 $int = $seq->initial_value (db_seq_t value)
308 $int = $seq->set_cachesize (U32 size)
309 $int = $seq->set_flags (U32 flags)
310 $int = $seq->set_range (db_seq_t min, db_seq_t max)
311
312=head4 example
313
314 my $seq = $db->sequence;
315
316 db_sequence_open $seq, undef, "seq", BDB::CREATE;
317 db_sequence_get $seq, undef, 1, my $value;
318
79 319
80=head2 SUPPORT FUNCTIONS 320=head2 SUPPORT FUNCTIONS
81 321
82=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 322=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
83 323
… …
167Strictly equivalent to: 407Strictly equivalent to:
168 408
169 BDB::poll_wait, BDB::poll_cb 409 BDB::poll_wait, BDB::poll_cb
170 while BDB::nreqs; 410 while BDB::nreqs;
171 411
412=back
413
172=head3 CONTROLLING THE NUMBER OF THREADS 414=head3 CONTROLLING THE NUMBER OF THREADS
415
416=over 4
173 417
174=item BDB::min_parallel $nthreads 418=item BDB::min_parallel $nthreads
175 419
176Set the minimum number of AIO threads to C<$nthreads>. The current 420Set the minimum number of AIO threads to C<$nthreads>. The current
177default is C<8>, which means eight asynchronous operations can execute 421default is C<8>, which means eight asynchronous operations can execute
… …
236 480
237You can still queue as many requests as you want. Therefore, 481You can still queue as many requests as you want. Therefore,
238C<max_oustsanding> is mainly useful in simple scripts (with low values) or 482C<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). 483as a stop gap to shield against fatal memory overflow (with large values).
240 484
485=item BDB::set_sync_prepare $cb
486
487Sets 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
489as the request callback, and the second is called to wait until the first
490callback has been called. The default implementation works like this:
491
492 sub {
493 my $status;
494 (
495 sub { $status = $! },
496 sub { BDB::poll while !defined $status; $! = $status },
497 )
498 }
499
500=back
501
241=head3 STATISTICAL INFORMATION 502=head3 STATISTICAL INFORMATION
503
504=over 4
242 505
243=item BDB::nreqs 506=item BDB::nreqs
244 507
245Returns the number of requests currently in the ready, execute or pending 508Returns the number of requests currently in the ready, execute or pending
246states (i.e. for which their callback has not been invoked yet). 509states (i.e. for which their callback has not been invoked yet).
… …
261but not yet processed by poll_cb). 524but not yet processed by poll_cb).
262 525
263=back 526=back
264 527
265=cut 528=cut
529
530set_sync_prepare {
531 my $status;
532 (
533 sub {
534 $status = $!;
535 },
536 sub {
537 BDB::poll while !defined $status;
538 $! = $status;
539 },
540 )
541};
266 542
267min_parallel 8; 543min_parallel 8;
268 544
269END { flush } 545END { flush }
270 546

Diff Legend

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