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

Comparing BDB/README (file contents):
Revision 1.3 by root, Tue Dec 4 10:14:34 2007 UTC vs.
Revision 1.15 by root, Sun Jan 11 00:56:09 2009 UTC

1NAME 1NAME
2 BDB - Asynchronous Berkeley DB access 2 BDB - Asynchronous Berkeley DB access
3 3
4SYNOPSIS 4SYNOPSIS
5 use BDB; 5 use BDB;
6
7 my $env = db_env_create;
8
9 mkdir "bdtest", 0700;
10 db_env_open
11 $env,
12 "bdtest",
13 BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL
14 | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE,
15 0600;
16
17 $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
18
19 my $db = db_create $env;
20 db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT | BDB::CREATE
21 | BDB::READ_UNCOMMITTED, 0600;
22 db_put $db, undef, "key", "data", 0, sub {
23 db_del $db, undef, "key";
24 };
25 db_sync $db;
26
27 # when you also use Coro, management is easy:
28 use Coro::BDB;
29
30 # automatic event loop intergration with AnyEvent:
31 use AnyEvent::BDB;
32
33 # automatic result processing with EV:
34 my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;
35
36 # with Glib:
37 add_watch Glib::IO BDB::poll_fileno,
38 in => sub { BDB::poll_cb; 1 };
39
40 # or simply flush manually
41 BDB::flush;
6 42
7DESCRIPTION 43DESCRIPTION
8 See the BerkeleyDB documentation 44 See the BerkeleyDB documentation
9 (<http://www.oracle.com/technology/documentation/berkeley-db/db/index.ht 45 (<http://www.oracle.com/technology/documentation/berkeley-db/db/index.ht
10 ml>). The BDB API is very similar to the C API (the translation has been 46 ml>). The BDB API is very similar to the C API (the translation has been
… …
50 Request has reached the end of its lifetime and holds no resources 86 Request has reached the end of its lifetime and holds no resources
51 anymore (except possibly for the Perl object, but its connection to 87 anymore (except possibly for the Perl object, but its connection to
52 the actual aio request is severed and calling its methods will 88 the actual aio request is severed and calling its methods will
53 either do nothing or result in a runtime error). 89 either do nothing or result in a runtime error).
54 90
55 BERKELEYDB FUNCTIONS 91BERKELEYDB FUNCTIONS
56 All of these are functions. The create functions simply return a new 92 All of these are functions. The create functions simply return a new
57 object and never block. All the remaining functions all take an optional 93 object and never block. All the remaining functions take an optional
58 callback as last argument. If it is missing, then the fucntion will be 94 callback as last argument. If it is missing, then the function will be
59 executed synchronously. 95 executed synchronously. In both cases, $! will reflect the return value
96 of the function.
60 97
61 BDB functions that cannot block (mostly functions that manipulate 98 BDB functions that cannot block (mostly functions that manipulate
62 settings) are method calls on the relevant objects, so the rule of thumb 99 settings) are method calls on the relevant objects, so the rule of thumb
63 is: if its a method, its not blocking, if its a function, it takes a 100 is: if it's a method, it's not blocking, if it's a function, it takes a
64 callback as last argument. 101 callback as last argument.
65 102
66 In the following, $int signifies an integer return value, "octetstring" 103 In the following, $int signifies an integer return value, "bdb_filename"
67 is a "binary string" (i.e. a perl string with no character indices 104 is a "filename" (octets on unix, madness on windows), "U32" is an
68 >255), "U32" is an unsigned 32 bit integer, "int" is some integer, "NV" 105 unsigned 32 bit integer, "int" is some integer, "NV" is a floating point
69 is a floating point value. 106 value.
70 107
71 The "SV *" types are generic perl scalars (for input and output of data 108 Most "SV *" types are generic perl scalars (for input and output of data
72 values), and the "SV *callback" is the optional callback function to 109 values).
73 call when the request is completed.
74 110
75 The various "DB_ENV" etc. arguments are handles return by 111 The various "DB_ENV" etc. arguments are handles return by
76 "db_env_create", "db_create", "txn_begin" and so on. If they have an 112 "db_env_create", "db_create", "txn_begin" and so on. If they have an
77 appended "_ornull" this means they are optional and you can pass "undef" 113 appended "_ornull" this means they are optional and you can pass "undef"
78 for them, resulting a NULL pointer on the C level. 114 for them, resulting a NULL pointer on the C level.
79 115
116 The "SV *callback" is the optional callback function to call when the
117 request is completed. This last callback argument is special: the
118 callback is simply the last argument passed. If there are "optional"
119 arguments before the callback they can be left out. The callback itself
120 can be left out or specified as "undef", in which case the function will
121 be executed synchronously.
122
123 For example, "db_env_txn_checkpoint" usually is called with all integer
124 arguments zero. These can be left out, so all of these specify a call to
125 "DB_ENV->txn_checkpoint", to be executed asynchronously with a callback
126 to be called:
127
128 db_env_txn_checkpoint $db_env, 0, 0, 0, sub { };
129 db_env_txn_checkpoint $db_env, 0, 0, sub { };
130 db_env_txn_checkpoint $db_env, sub { };
131
132 While these all specify a call to "DB_ENV->txn_checkpoint" to be
133 executed synchronously:
134
135 db_env_txn_checkpoint $db_env, 0, 0, 0, undef;
136 db_env_txn_checkpoint $db_env, 0, 0, 0;
137 db_env_txn_checkpoint $db_env, 0;
138
80 BDB functions 139 BDB functions
81 Functions in the BDB namespace, exported by default: 140 Functions in the BDB namespace, exported by default:
82 141
83 $env = db_env_create (U32 env_flags = 0) 142 $env = db_env_create (U32 env_flags = 0)
84 flags: RPCCLIENT 143 flags: RPCCLIENT
85 144
86 db_env_open (DB_ENV *env, octetstring db_home, U32 open_flags, int mode, SV *callback = &PL_sv_undef) 145 db_env_open (DB_ENV *env, bdb_filename db_home, U32 open_flags, int mode, SV *callback = 0)
87 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 146 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
88 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = &PL_sv_undef) 147 db_env_close (DB_ENV *env, U32 flags = 0, SV *callback = 0)
89 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 148 db_env_txn_checkpoint (DB_ENV *env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV *callback = 0)
90 flags: FORCE 149 flags: FORCE
91 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = &PL_sv_undef) 150 db_env_lock_detect (DB_ENV *env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV *dummy = 0, SV *callback = 0)
92 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST 151 atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
93 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = &PL_sv_undef) 152 db_env_memp_sync (DB_ENV *env, SV *dummy = 0, SV *callback = 0)
94 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = &PL_sv_undef) 153 db_env_memp_trickle (DB_ENV *env, int percent, SV *dummy = 0, SV *callback = 0)
154 db_env_dbremove (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = 0)
155 db_env_dbrename (DB_ENV *env, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, bdb_filename newname, U32 flags = 0, SV *callback = 0)
156 db_env_log_archive (DB_ENV *env, SV *listp, U32 flags = 0, SV *callback = 0)
95 157
96 $db = db_create (DB_ENV *env = 0, U32 flags = 0) 158 $db = db_create (DB_ENV *env = 0, U32 flags = 0)
97 flags: XA_CREATE 159 flags: XA_CREATE
98 160
99 db_open (DB *db, DB_TXN_ornull *txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef) 161 db_open (DB *db, DB_TXN_ornull *txnid, bdb_filename file, bdb_filename database, int type, U32 flags, int mode, SV *callback = 0)
100 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE 162 flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
101 db_close (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 163 db_close (DB *db, U32 flags = 0, SV *callback = 0)
102 flags: DB_NOSYNC 164 flags: DB_NOSYNC
165 db_verify (DB *db, bdb_filename file, bdb_filename database = 0, SV *dummy = 0, U32 flags = 0, SV *callback = 0)
166 db_upgrade (DB *db, bdb_filename file, U32 flags = 0, SV *callback = 0)
103 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) 167 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 = 0)
104 flags: FREELIST_ONLY FREE_SPACE 168 flags: FREELIST_ONLY FREE_SPACE
105 db_sync (DB *db, U32 flags = 0, SV *callback = &PL_sv_undef) 169 db_sync (DB *db, U32 flags = 0, SV *callback = 0)
106 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = &PL_sv_undef) 170 db_key_range (DB *db, DB_TXN_ornull *txn, SV *key, SV *key_range, U32 flags = 0, SV *callback = 0)
107 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 171 db_put (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
108 flags: APPEND NODUPDATA NOOVERWRITE 172 flags: APPEND NODUPDATA NOOVERWRITE
173 db_exists (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = 0) (v4.6)
109 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 174 db_get (DB *db, DB_TXN_ornull *txn, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
110 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW 175 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
111 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 176 db_pget (DB *db, DB_TXN_ornull *txn, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = 0)
112 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW 177 flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
113 db_del (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef) 178 db_del (DB *db, DB_TXN_ornull *txn, SV *key, U32 flags = 0, SV *callback = 0)
114 db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef) 179 db_txn_commit (DB_TXN *txn, U32 flags = 0, SV *callback = 0)
115 flags: TXN_NOSYNC TXN_SYNC 180 flags: TXN_NOSYNC TXN_SYNC
116 db_txn_abort (DB_TXN *txn, SV *callback = &PL_sv_undef) 181 db_txn_abort (DB_TXN *txn, SV *callback = 0)
117 182
118 db_c_close (DBC *dbc, SV *callback = &PL_sv_undef) 183 db_c_close (DBC *dbc, SV *callback = 0)
119 db_c_count (DBC *dbc, SV *count, U32 flags = 0, SV *callback = &PL_sv_undef) 184 db_c_count (DBC *dbc, SV *count, U32 flags = 0, SV *callback = 0)
120 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 185 db_c_put (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
121 flags: AFTER BEFORE CURRENT KEYFIRST KEYLAST NODUPDATA 186 flags: AFTER BEFORE CURRENT KEYFIRST KEYLAST NODUPDATA
122 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 187 db_c_get (DBC *dbc, SV *key, SV *data, U32 flags = 0, SV *callback = 0)
123 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 188 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
124 db_c_pget (DBC *dbc, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = &PL_sv_undef) 189 db_c_pget (DBC *dbc, SV *key, SV *pkey, SV *data, U32 flags = 0, SV *callback = 0)
125 db_c_del (DBC *dbc, U32 flags = 0, SV *callback = &PL_sv_undef) 190 db_c_del (DBC *dbc, U32 flags = 0, SV *callback = 0)
126 191
127 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = &PL_sv_undef) 192 db_sequence_open (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, SV *key, U32 flags = 0, SV *callback = 0)
128 flags: CREATE EXCL 193 flags: CREATE EXCL
129 db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = &PL_sv_undef) 194 db_sequence_close (DB_SEQUENCE *seq, U32 flags = 0, SV *callback = 0)
130 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) 195 db_sequence_get (DB_SEQUENCE *seq, DB_TXN_ornull *txnid, int delta, SV *seq_value, U32 flags = DB_TXN_NOSYNC, SV *callback = 0)
131 flags: TXN_NOSYNC 196 flags: TXN_NOSYNC
132 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = &PL_sv_undef) 197 db_sequence_remove (DB_SEQUENCE *seq, DB_TXN_ornull *txnid = 0, U32 flags = 0, SV *callback = 0)
133 flags: TXN_NOSYNC 198 flags: TXN_NOSYNC
134 199
135 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = &PL_sv_undef) 200 db_txn_finish (DB_TXN *txn, U32 flags = 0, SV *callback = 0)
136 This is not actually a Berkeley DB function but a BDB module extension. 201 This is not actually a Berkeley DB function but a BDB module extension.
137 The background for this exytension is: It is very annoying to have to 202 The background for this exytension is: It is very annoying to have to
138 check every single BDB function for error returns and provide a codepath 203 check every single BDB function for error returns and provide a codepath
139 out of your transaction. While the BDB module still makes this possible, 204 out of your transaction. While the BDB module still makes this possible,
140 it contains the following extensions: 205 it contains the following extensions:
… …
165 230
166 You can use the "$txn->failed" method to check wether a transaction has 231 You can use the "$txn->failed" method to check wether a transaction has
167 failed in this way and abort further processing (excluding 232 failed in this way and abort further processing (excluding
168 "db_txn_finish"). 233 "db_txn_finish").
169 234
170 DB_ENV/database environment methods 235 DB_ENV/database environment methods
171 Methods available on DB_ENV/$env handles: 236 Methods available on DB_ENV/$env handles:
172 237
173 DESTROY (DB_ENV_ornull *env) 238 DESTROY (DB_ENV_ornull *env)
174 CODE: 239 CODE:
175 if (env) 240 if (env)
… …
178 $int = $env->set_data_dir (const char *dir) 243 $int = $env->set_data_dir (const char *dir)
179 $int = $env->set_tmp_dir (const char *dir) 244 $int = $env->set_tmp_dir (const char *dir)
180 $int = $env->set_lg_dir (const char *dir) 245 $int = $env->set_lg_dir (const char *dir)
181 $int = $env->set_shm_key (long shm_key) 246 $int = $env->set_shm_key (long shm_key)
182 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0) 247 $int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
183 $int = $env->set_flags (U32 flags, int onoff) 248 $int = $env->set_flags (U32 flags, int onoff = 1)
249 $int = $env->log_set_config (U32 flags, int onoff = 1) (v4.7)
250 $int = $env->set_intermediate_dir_mode (const char *modestring) (v4.7)
184 $env->set_errfile (FILE *errfile = 0) 251 $env->set_errfile (FILE *errfile = 0)
185 $env->set_msgfile (FILE *msgfile = 0) 252 $env->set_msgfile (FILE *msgfile = 0)
186 $int = $env->set_verbose (U32 which, int onoff = 1) 253 $int = $env->set_verbose (U32 which, int onoff = 1)
187 $int = $env->set_encrypt (const char *password, U32 flags = 0) 254 $int = $env->set_encrypt (const char *password, U32 flags = 0)
188 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT) 255 $int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
… …
193 $int = $env->set_lk_max_lockers (U32 max) 260 $int = $env->set_lk_max_lockers (U32 max)
194 $int = $env->set_lk_max_locks (U32 max) 261 $int = $env->set_lk_max_locks (U32 max)
195 $int = $env->set_lk_max_objects (U32 max) 262 $int = $env->set_lk_max_objects (U32 max)
196 $int = $env->set_lg_bsize (U32 max) 263 $int = $env->set_lg_bsize (U32 max)
197 $int = $env->set_lg_max (U32 max) 264 $int = $env->set_lg_max (U32 max)
265 $int = $env->mutex_set_increment (U32 increment)
266 $int = $env->mutex_set_tas_spins (U32 tas_spins)
267 $int = $env->mutex_set_max (U32 max)
268 $int = $env->mutex_set_align (U32 align)
198 269
199 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0) 270 $txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
200 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC 271 flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
272 $txn = $env->cdsgroup_begin; (v4.5)
201 273
202 Example: 274 Example:
203 use AnyEvent; 275 use AnyEvent;
204 use BDB; 276 use BDB;
205 277
… …
217 BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE, 289 BDB::INIT_LOCK | BDB::INIT_LOG | BDB::INIT_MPOOL | BDB::INIT_TXN | BDB::RECOVER | BDB::USE_ENVIRON | BDB::CREATE,
218 0600; 290 0600;
219 291
220 $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1); 292 $env->set_flags (BDB::AUTO_COMMIT | BDB::TXN_NOSYNC, 1);
221 293
222 DB/database methods 294 DB/database methods
223 Methods available on DB/$db handles: 295 Methods available on DB/$db handles:
224 296
225 DESTROY (DB_ornull *db) 297 DESTROY (DB_ornull *db)
226 CODE: 298 CODE:
227 if (db) 299 if (db)
… …
267 339
268 db_del $db, undef, "key $_" for 1..1000; 340 db_del $db, undef, "key $_" for 1..1000;
269 341
270 db_sync $db; 342 db_sync $db;
271 343
272 DB_TXN/transaction methods 344 DB_TXN/transaction methods
273 Methods available on DB_TXN/$txn handles: 345 Methods available on DB_TXN/$txn handles:
274 346
275 DESTROY (DB_TXN_ornull *txn) 347 DESTROY (DB_TXN_ornull *txn)
276 CODE: 348 CODE:
277 if (txn) 349 if (txn)
… …
281 flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT 353 flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
282 354
283 $bool = $txn->failed 355 $bool = $txn->failed
284 # see db_txn_finish documentation, above 356 # see db_txn_finish documentation, above
285 357
286 DBC/cursor methods 358 DBC/cursor methods
287 Methods available on DBC/$dbc handles: 359 Methods available on DBC/$dbc handles:
288 360
289 DESTROY (DBC_ornull *dbc) 361 DESTROY (DBC_ornull *dbc)
290 CODE: 362 CODE:
291 if (dbc) 363 if (dbc)
292 dbc->c_close (dbc); 364 dbc->c_close (dbc);
365
366 $int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
293 367
294 Example: 368 Example:
295 my $c = $db->cursor; 369 my $c = $db->cursor;
296 370
297 for (;;) { 371 for (;;) {
… …
300 last if $!; 374 last if $!;
301 } 375 }
302 376
303 db_c_close $c; 377 db_c_close $c;
304 378
305 DB_SEQUENCE/sequence methods 379 DB_SEQUENCE/sequence methods
306 Methods available on DB_SEQUENCE/$seq handles: 380 Methods available on DB_SEQUENCE/$seq handles:
307 381
308 DESTROY (DB_SEQUENCE_ornull *seq) 382 DESTROY (DB_SEQUENCE_ornull *seq)
309 CODE: 383 CODE:
310 if (seq) 384 if (seq)
… …
316 flags: SEQ_DEC SEQ_INC SEQ_WRAP 390 flags: SEQ_DEC SEQ_INC SEQ_WRAP
317 $int = $seq->set_range (db_seq_t min, db_seq_t max) 391 $int = $seq->set_range (db_seq_t min, db_seq_t max)
318 392
319 Example: 393 Example:
320 my $seq = $db->sequence; 394 my $seq = $db->sequence;
321 395
322 db_sequence_open $seq, undef, "seq", BDB::CREATE; 396 db_sequence_open $seq, undef, "seq", BDB::CREATE;
323 db_sequence_get $seq, undef, 1, my $value; 397 db_sequence_get $seq, undef, 1, my $value;
324 398
325 SUPPORT FUNCTIONS 399SUPPORT FUNCTIONS
326 EVENT PROCESSING AND EVENT LOOP INTEGRATION 400 EVENT PROCESSING AND EVENT LOOP INTEGRATION
401 $msg = BDB::strerror [$errno]
402 Returns the string corresponding to the given errno value. If no
403 argument is given, use $!.
404
405 Note that the BDB module also patches the $! variable directly, so
406 you should be able to get a bdb error string by simply stringifying
407 $!.
408
327 $fileno = BDB::poll_fileno 409 $fileno = BDB::poll_fileno
328 Return the *request result pipe file descriptor*. This filehandle 410 Return the *request result pipe file descriptor*. This filehandle
329 must be polled for reading by some mechanism outside this module 411 must be polled for reading by some mechanism outside this module
330 (e.g. Event or select, see below or the SYNOPSIS). If the pipe 412 (e.g. Event or select, see below or the SYNOPSIS). If the pipe
331 becomes readable you have to call "poll_cb" to check the results. 413 becomes readable you have to call "poll_cb" to check the results.
… …
367 interactiveness when perl is not fast enough to process all requests 449 interactiveness when perl is not fast enough to process all requests
368 in time. 450 in time.
369 451
370 For interactive programs, values such as 0.01 to 0.1 should be fine. 452 For interactive programs, values such as 0.01 to 0.1 should be fine.
371 453
372 Example: Install an Event watcher that automatically calls 454 Example: Install an EV watcher that automatically calls BDB::poll_cb
373 BDB::poll_cb with low priority, to ensure that other parts of the 455 with low priority, to ensure that other parts of the program get the
374 program get the CPU sometimes even under high AIO load. 456 CPU sometimes even under high load.
375 457
376 # try not to spend much more than 0.1s in poll_cb 458 # try not to spend much more than 0.1s in poll_cb
377 BDB::max_poll_time 0.1; 459 BDB::max_poll_time 0.1;
378 460
379 # use a low priority so other tasks have priority 461 my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
380 Event->io (fd => BDB::poll_fileno,
381 poll => 'r', nice => 1,
382 cb => &BDB::poll_cb);
383 462
384 BDB::poll_wait 463 BDB::poll_wait
385 If there are any outstanding requests and none of them in the result 464 If there are any outstanding requests and none of them in the result
386 phase, wait till the result filehandle becomes ready for reading 465 phase, wait till the result filehandle becomes ready for reading
387 (simply does a "select" on the filehandle. This is useful if you 466 (simply does a "select" on the filehandle. This is useful if you
… …
396 equivalent to: 475 equivalent to:
397 476
398 BDB::poll_wait, BDB::poll_cb 477 BDB::poll_wait, BDB::poll_cb
399 478
400 BDB::flush 479 BDB::flush
401 Wait till all outstanding AIO requests have been handled. 480 Wait till all outstanding BDB requests have been handled.
402 481
403 Strictly equivalent to: 482 Strictly equivalent to:
404 483
405 BDB::poll_wait, BDB::poll_cb 484 BDB::poll_wait, BDB::poll_cb
406 while BDB::nreqs; 485 while BDB::nreqs;
407 486
487 VERSION CHECKING
488 BerkeleyDB comes in various versions, many of them have minor
489 incompatibilities. This means that traditional "at least version x.x"
490 checks are often not sufficient.
491
492 Example: set the log_autoremove option in a way compatible with <v4.7
493 and v4.7. Note the use of & on the constants to avoid triggering a
494 compiletime bug when the symbol isn't available.
495
496 $DB_ENV->set_flags (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
497 $DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;
498
499 BDB::VERSION
500 The "BDB::VERSION" function, when called without arguments, returns
501 the Berkeley DB version as a v-string (usually with 3 components).
502 You should use "lt" and "ge" operators exclusively to make
503 comparisons.
504
505 Example: check for at least version 4.7.
506
507 BDB::VERSION ge v4.7 or die;
508
509 BDB::VERSION min-version
510 Returns true if the BDB version is at least the given version
511 (specified as a v-string), false otherwise.
512
513 Example: check for at least version 4.5.
514
515 BDB::VERSION v4.7 or die;
516
517 BDB::VERSION min-version, max-version
518 Returns true of the BDB version is at least version "min-version"
519 (specify "undef" or "v0" for any minimum version) and less then
520 "max-version".
521
522 Example: check wether version is strictly less then v4.7.
523
524 BDB::VERSION v0, v4.7
525 or die "version 4.7 is not yet supported";
526
408 CONTROLLING THE NUMBER OF THREADS 527 CONTROLLING THE NUMBER OF THREADS
409 BDB::min_parallel $nthreads 528 BDB::min_parallel $nthreads
410 Set the minimum number of AIO threads to $nthreads. The current 529 Set the minimum number of BDB threads to $nthreads. The current
411 default is 8, which means eight asynchronous operations can execute 530 default is 8, which means eight asynchronous operations can execute
412 concurrently at any one time (the number of outstanding requests, 531 concurrently at any one time (the number of outstanding requests,
413 however, is unlimited). 532 however, is unlimited).
414 533
415 BDB starts threads only on demand, when an AIO request is queued and 534 BDB starts threads only on demand, when an BDB request is queued and
416 no free thread exists. Please note that queueing up a hundred 535 no free thread exists. Please note that queueing up a hundred
417 requests can create demand for a hundred threads, even if it turns 536 requests can create demand for a hundred threads, even if it turns
418 out that everything is in the cache and could have been processed 537 out that everything is in the cache and could have been processed
419 faster by a single thread. 538 faster by a single thread.
420 539
… …
426 Under most circumstances you don't need to call this function, as 545 Under most circumstances you don't need to call this function, as
427 the module selects a default that is suitable for low to moderate 546 the module selects a default that is suitable for low to moderate
428 load. 547 load.
429 548
430 BDB::max_parallel $nthreads 549 BDB::max_parallel $nthreads
431 Sets the maximum number of AIO threads to $nthreads. If more than 550 Sets the maximum number of BDB threads to $nthreads. If more than
432 the specified number of threads are currently running, this function 551 the specified number of threads are currently running, this function
433 kills them. This function blocks until the limit is reached. 552 kills them. This function blocks until the limit is reached.
434 553
435 While $nthreads are zero, aio requests get queued but not executed 554 While $nthreads are zero, aio requests get queued but not executed
436 until the number of threads has been increased again. 555 until the number of threads has been increased again.
… …
472 You can still queue as many requests as you want. Therefore, 591 You can still queue as many requests as you want. Therefore,
473 "max_oustsanding" is mainly useful in simple scripts (with low 592 "max_oustsanding" is mainly useful in simple scripts (with low
474 values) or as a stop gap to shield against fatal memory overflow 593 values) or as a stop gap to shield against fatal memory overflow
475 (with large values). 594 (with large values).
476 595
477 BDB::set_sync_prepare $cb 596 $old_cb = BDB::set_sync_prepare $cb
478 Sets a callback that is called whenever a request is created without 597 Sets a callback that is called whenever a request is created without
479 an explicit callback. It has to return two code references. The 598 an explicit callback. It has to return two code references. The
480 first is used as the request callback, and the second is called to 599 first is used as the request callback (it should save the return
481 wait until the first callback has been called. The default 600 status), and the second is called to wait until the first callback
482 implementation works like this: 601 has been called (it must set $! to the return status).
602
603 This mechanism can be used to include BDB into other event
604 mechanisms, such as Coro::BDB.
605
606 To allow other, callback-based, events to be executed while
607 callback-less ones are run, you could use this sync prepare
608 function:
483 609
484 sub { 610 sub {
485 my $status; 611 my $status;
486 ( 612 (
487 sub { $status = $! }, 613 sub { $status = $! },
488 sub { BDB::poll while !defined $status; $! = $status }, 614 sub { BDB::poll while !defined $status; $! = $status },
489 ) 615 )
490 } 616 }
491 617
618 It works by polling for results till the request has finished and
619 then sets $! to the return value. This means that if you don't use a
620 callback, BDB would simply fall back to synchronous operations.
621
622 By default, or if the sync prepare function is set to "undef", is to
623 execute callback-less BDB requests in the foreground thread, setting
624 $! to the return value, without polling for other events.
625
492 STATISTICAL INFORMATION 626 STATISTICAL INFORMATION
493 BDB::nreqs 627 BDB::nreqs
494 Returns the number of requests currently in the ready, execute or 628 Returns the number of requests currently in the ready, execute or
495 pending states (i.e. for which their callback has not been invoked 629 pending states (i.e. for which their callback has not been invoked
496 yet). 630 yet).
497 631
… …
506 640
507 BDB::npending 641 BDB::npending
508 Returns the number of requests currently in the pending state 642 Returns the number of requests currently in the pending state
509 (executed, but not yet processed by poll_cb). 643 (executed, but not yet processed by poll_cb).
510 644
645COMMON PITFALLS
646 Unexpected Crashes
647 Remember that, by default, BDB will execute requests in parallel, in
648 somewhat random order. That means that it is easy to run a "db_get"
649 request on thesa me database as a concurrent "db_close" request, leading
650 to a crash, silent data corruption, eventually the next world war on
651 terrorism.
652
653 If you only ever use foreground requests (without a callback), this will
654 not be an issue.
655
656 Unexpected Freezes or Deadlocks
657 Remember that, by default, BDB will execute requests in parallel, which
658 easily leads to deadlocks (even concurrent put's on the same database
659 can deadlock).
660
661 You either need to run deadlock detection (and handle the resulting
662 errors), or make sure only one process ever updates the database, ine
663 one thread, e.g. by using only foreground requests (without a callback).
664
511 FORK BEHAVIOUR 665FORK BEHAVIOUR
512 This module should do "the right thing" when the process using it forks: 666 This module should do "the right thing" when the process using it forks:
513 667
514 Before the fork, IO::AIO enters a quiescent state where no requests can 668 Before the fork, BDB enters a quiescent state where no requests can be
515 be added in other threads and no results will be processed. After the 669 added in other threads and no results will be processed. After the fork
516 fork the parent simply leaves the quiescent state and continues 670 the parent simply leaves the quiescent state and continues
517 request/result processing, while the child frees the request/result 671 request/result processing, while the child frees the request/result
518 queue (so that the requests started before the fork will only be handled 672 queue (so that the requests started before the fork will only be handled
519 in the parent). Threads will be started on demand until the limit set in 673 in the parent). Threads will be started on demand until the limit set in
520 the parent process has been reached again. 674 the parent process has been reached again.
521 675
522 In short: the parent will, after a short pause, continue as if fork had 676 In short: the parent will, after a short pause, continue as if fork had
523 not been called, while the child will act as if IO::AIO has not been 677 not been called, while the child will act as if BDB has not been used
524 used yet. 678 yet.
525 679
680 Win32 note: there is no fork on win32, and perls emulation of it is too
681 broken to be supported, so do not use BDB in a windows pseudo-fork,
682 better yet, switch to a more capable platform.
683
526 MEMORY USAGE 684MEMORY USAGE
527 Per-request usage: 685 Per-request usage:
528 686
529 Each aio request uses - depending on your architecture - around 100-200 687 Each aio request uses - depending on your architecture - around 100-200
530 bytes of memory. In addition, stat requests need a stat buffer (possibly 688 bytes of memory. In addition, stat requests need a stat buffer (possibly
531 a few hundred bytes), readdir requires a result buffer and so on. Perl 689 a few hundred bytes), readdir requires a result buffer and so on. Perl
… …
539 697
540 In the execution phase, some aio requests require more memory for 698 In the execution phase, some aio requests require more memory for
541 temporary buffers, and each thread requires a stack and other data 699 temporary buffers, and each thread requires a stack and other data
542 structures (usually around 16k-128k, depending on the OS). 700 structures (usually around 16k-128k, depending on the OS).
543 701
702WIN32 FILENAMES/DATABASE NAME MESS
703 Perl on Win32 supports only ASCII filenames (the reason is that it
704 abuses an internal flag to store wether a filename is Unicode or ANSI,
705 but that flag is used for somethign else in the perl core, so there is
706 no way to detect wether a filename is ANSI or Unicode-encoded). The BDB
707 module tries to work around this issue by assuming that the filename is
708 an ANSI filename and BDB was built for unicode support.
709
544KNOWN BUGS 710KNOWN BUGS
545 Known bugs will be fixed in the next release, except: 711 Known bugs will be fixed in the next release, except:
546 712
547 If you use a transaction in any request, and the request returns 713 If you use a transaction in any request, and the request returns
548 with an operating system error or DB_LOCK_NOTGRANTED, the internal 714 with an operating system error or DB_LOCK_NOTGRANTED, the internal
549 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>, 715 TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
550 above. 716 above.
551 717
552SEE ALSO 718SEE ALSO
553 Coro::AIO. 719 AnyEvent::BDB (event loop integration), Coro::BDB (more natural syntax),
720 IO::AIO (nice to have).
554 721
555AUTHOR 722AUTHOR
556 Marc Lehmann <schmorp@schmorp.de> 723 Marc Lehmann <schmorp@schmorp.de>
557 http://home.schmorp.de/ 724 http://home.schmorp.de/
558 725

Diff Legend

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