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

Comparing BDB/BDB.pm (file contents):
Revision 1.9 by root, Sun Jul 8 14:57:59 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
11See the eg/ directory in the distribution and the berkeleydb C 11See the BerkeleyDB documentation (L<http://www.oracle.com/technology/documentation/berkeley-db/db/index.html>).
12documentation. This is inadequate, but the only sources of documentation 12The BDB API is very similar to the C API (the translation ahs been very faithful).
13known for this module so far.
14 13
15=head2 EXAMPLE 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
16 21
17=head1 REQUEST ANATOMY AND LIFETIME 22=head1 REQUEST ANATOMY AND LIFETIME
18 23
19Every 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
20directly visible to Perl. 25directly visible to Perl.
… …
67use strict 'vars'; 72use strict 'vars';
68 73
69use base 'Exporter'; 74use base 'Exporter';
70 75
71BEGIN { 76BEGIN {
72 our $VERSION = '0.5'; 77 our $VERSION = '0.6';
73 78
74 our @BDB_REQ = qw( 79 our @BDB_REQ = qw(
75 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
76 db_env_memp_sync db_env_memp_trickle 81 db_env_memp_sync db_env_memp_trickle
77 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
… …
90 95
91 require XSLoader; 96 require XSLoader;
92 XSLoader::load ("BDB", $VERSION); 97 XSLoader::load ("BDB", $VERSION);
93} 98}
94 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
319
95=head2 SUPPORT FUNCTIONS 320=head2 SUPPORT FUNCTIONS
96 321
97=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 322=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
98 323
99=over 4 324=over 4

Diff Legend

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