[ViewVC] Diff of: cvs/BDB/README

Comparing BDB/README (file contents):
Revision 1.4 by root, Fri Dec 7 13:39:04 2007 UTC vs.
Revision 1.14 by root, Tue Oct 21 02:21:25 2008 UTC

…		…
22	db_put $db, undef, "key", "data", 0, sub {	22	db_put $db, undef, "key", "data", 0, sub {
23	db_del $db, undef, "key";	23	db_del $db, undef, "key";
24	};	24	};
25	db_sync $db;	25	db_sync $db;
26		26
27	# automatic result processing with AnyEvent:	27	# when you also use Coro, management is easy:
28	our $FH; open $FH, "<&=" . BDB::poll_fileno;	28	use Coro::BDB;
29	our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&BDB::poll_cb);	29
		30	# automatic event loop intergration with AnyEvent:
		31	use AnyEvent::BDB;
30		32
31	# automatic result processing with EV:	33	# automatic result processing with EV:
32	my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;	34	my $WATCHER = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb;
33		35
34	# with Glib:	36	# with Glib:
…		…
84	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
85	anymore (except possibly for the Perl object, but its connection to	87	anymore (except possibly for the Perl object, but its connection to
86	the actual aio request is severed and calling its methods will	88	the actual aio request is severed and calling its methods will
87	either do nothing or result in a runtime error).	89	either do nothing or result in a runtime error).
88		90
89	BERKELEYDB FUNCTIONS	91	BERKELEYDB FUNCTIONS
90	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
91	object and never block. All the remaining functions all take an optional	93	object and never block. All the remaining functions take an optional
92	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
93	executed synchronously.	95	executed synchronously. In both cases, $! will reflect the return value
		96	of the function.
94		97
95	BDB functions that cannot block (mostly functions that manipulate	98	BDB functions that cannot block (mostly functions that manipulate
96	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
97	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
98	callback as last argument.	101	callback as last argument.
99		102
100	In the following, $int signifies an integer return value, "octetstring"	103	In the following, $int signifies an integer return value, "bdb_filename"
101	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
102	>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
103	is a floating point value.	106	value.
104		107
105	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
106	values), and the "SV *callback" is the optional callback function to	109	values).
107	call when the request is completed.
108		110
109	The various "DB_ENV" etc. arguments are handles return by	111	The various "DB_ENV" etc. arguments are handles return by
110	"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
111	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"
112	for them, resulting a NULL pointer on the C level.	114	for them, resulting a NULL pointer on the C level.
113		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
114	BDB functions	139	BDB functions
115	Functions in the BDB namespace, exported by default:	140	Functions in the BDB namespace, exported by default:
116		141
117	$env = db_env_create (U32 env_flags = 0)	142	$env = db_env_create (U32 env_flags = 0)
118	flags: RPCCLIENT	143	flags: RPCCLIENT
119		144
120	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 = &PL_sv_undef)
121	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
122	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 = &PL_sv_undef)
123	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 = &PL_sv_undef)
124	flags: FORCE	149	flags: FORCE
125	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 = &PL_sv_undef)
126	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
127	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 = &PL_sv_undef)
128	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 = &PL_sv_undef)
		154	db_env_dbremove (DB_ENV env, DB_TXN_ornull txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = &PL_sv_undef)
		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 = &PL_sv_undef)
		156	db_env_log_archive (DB_ENV env, SV listp, U32 flags = 0, SV *callback = &PL_sv_undef)
129		157
130	$db = db_create (DB_ENV *env = 0, U32 flags = 0)	158	$db = db_create (DB_ENV *env = 0, U32 flags = 0)
131	flags: XA_CREATE	159	flags: XA_CREATE
132		160
133	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 = &PL_sv_undef)
134	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
135	db_close (DB db, U32 flags = 0, SV callback = &PL_sv_undef)	163	db_close (DB db, U32 flags = 0, SV callback = &PL_sv_undef)
136	flags: DB_NOSYNC	164	flags: DB_NOSYNC
		165	db_upgrade (DB db, bdb_filename file, U32 flags = 0, SV callback = &PL_sv_undef)
137	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)	166	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)
138	flags: FREELIST_ONLY FREE_SPACE	167	flags: FREELIST_ONLY FREE_SPACE
139	db_sync (DB db, U32 flags = 0, SV callback = &PL_sv_undef)	168	db_sync (DB db, U32 flags = 0, SV callback = &PL_sv_undef)
140	db_key_range (DB db, DB_TXN_ornull txn, SV key, SV key_range, U32 flags = 0, SV *callback = &PL_sv_undef)	169	db_key_range (DB db, DB_TXN_ornull txn, SV key, SV key_range, U32 flags = 0, SV *callback = &PL_sv_undef)
141	db_put (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = &PL_sv_undef)	170	db_put (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = &PL_sv_undef)
142	flags: APPEND NODUPDATA NOOVERWRITE	171	flags: APPEND NODUPDATA NOOVERWRITE
		172	db_exists (DB db, DB_TXN_ornull txn, SV key, U32 flags = 0, SV callback = 0) (v4.6)
143	db_get (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = &PL_sv_undef)	173	db_get (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = &PL_sv_undef)
144	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW	174	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
145	db_pget (DB db, DB_TXN_ornull txn, SV key, SV pkey, SV data, U32 flags = 0, SV callback = &PL_sv_undef)	175	db_pget (DB db, DB_TXN_ornull txn, SV key, SV pkey, SV data, U32 flags = 0, SV callback = &PL_sv_undef)
146	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW	176	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
147	db_del (DB db, DB_TXN_ornull txn, SV key, U32 flags = 0, SV callback = &PL_sv_undef)	177	db_del (DB db, DB_TXN_ornull txn, SV key, U32 flags = 0, SV callback = &PL_sv_undef)
…		…
199		229
200	You can use the "$txn->failed" method to check wether a transaction has	230	You can use the "$txn->failed" method to check wether a transaction has
201	failed in this way and abort further processing (excluding	231	failed in this way and abort further processing (excluding
202	"db_txn_finish").	232	"db_txn_finish").
203		233
204	DB_ENV/database environment methods	234	DB_ENV/database environment methods
205	Methods available on DB_ENV/$env handles:	235	Methods available on DB_ENV/$env handles:
206		236
207	DESTROY (DB_ENV_ornull *env)	237	DESTROY (DB_ENV_ornull *env)
208	CODE:	238	CODE:
209	if (env)	239	if (env)
…		…
212	$int = $env->set_data_dir (const char *dir)	242	$int = $env->set_data_dir (const char *dir)
213	$int = $env->set_tmp_dir (const char *dir)	243	$int = $env->set_tmp_dir (const char *dir)
214	$int = $env->set_lg_dir (const char *dir)	244	$int = $env->set_lg_dir (const char *dir)
215	$int = $env->set_shm_key (long shm_key)	245	$int = $env->set_shm_key (long shm_key)
216	$int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)	246	$int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
217	$int = $env->set_flags (U32 flags, int onoff)	247	$int = $env->set_flags (U32 flags, int onoff = 1)
		248	$int = $env->log_set_config (U32 flags, int onoff = 1) (v4.7)
		249	$int = $env->set_intermediate_dir_mode (const char *modestring) (v4.7)
218	$env->set_errfile (FILE *errfile = 0)	250	$env->set_errfile (FILE *errfile = 0)
219	$env->set_msgfile (FILE *msgfile = 0)	251	$env->set_msgfile (FILE *msgfile = 0)
220	$int = $env->set_verbose (U32 which, int onoff = 1)	252	$int = $env->set_verbose (U32 which, int onoff = 1)
221	$int = $env->set_encrypt (const char *password, U32 flags = 0)	253	$int = $env->set_encrypt (const char *password, U32 flags = 0)
222	$int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)	254	$int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
…		…
234	$int = $env->mutex_set_max (U32 max)	266	$int = $env->mutex_set_max (U32 max)
235	$int = $env->mutex_set_align (U32 align)	267	$int = $env->mutex_set_align (U32 align)
236		268
237	$txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)	269	$txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
238	flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC	270	flags: READ_COMMITTED READ_UNCOMMITTED TXN_NOSYNC TXN_NOWAIT TXN_SNAPSHOT TXN_SYNC TXN_WAIT TXN_WRITE_NOSYNC
		271	$txn = $env->cdsgroup_begin; (v4.5)
239		272
240	Example:	273	Example:
241	use AnyEvent;	274	use AnyEvent;
242	use BDB;	275	use BDB;
243		276
…		…
255	BDB::INIT_LOCK \| BDB::INIT_LOG \| BDB::INIT_MPOOL \| BDB::INIT_TXN \| BDB::RECOVER \| BDB::USE_ENVIRON \| BDB::CREATE,	288	BDB::INIT_LOCK \| BDB::INIT_LOG \| BDB::INIT_MPOOL \| BDB::INIT_TXN \| BDB::RECOVER \| BDB::USE_ENVIRON \| BDB::CREATE,
256	0600;	289	0600;
257		290
258	$env->set_flags (BDB::AUTO_COMMIT \| BDB::TXN_NOSYNC, 1);	291	$env->set_flags (BDB::AUTO_COMMIT \| BDB::TXN_NOSYNC, 1);
259		292
260	DB/database methods	293	DB/database methods
261	Methods available on DB/$db handles:	294	Methods available on DB/$db handles:
262		295
263	DESTROY (DB_ornull *db)	296	DESTROY (DB_ornull *db)
264	CODE:	297	CODE:
265	if (db)	298	if (db)
…		…
305		338
306	db_del $db, undef, "key $_" for 1..1000;	339	db_del $db, undef, "key $_" for 1..1000;
307		340
308	db_sync $db;	341	db_sync $db;
309		342
310	DB_TXN/transaction methods	343	DB_TXN/transaction methods
311	Methods available on DB_TXN/$txn handles:	344	Methods available on DB_TXN/$txn handles:
312		345
313	DESTROY (DB_TXN_ornull *txn)	346	DESTROY (DB_TXN_ornull *txn)
314	CODE:	347	CODE:
315	if (txn)	348	if (txn)
…		…
319	flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT	352	flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
320		353
321	$bool = $txn->failed	354	$bool = $txn->failed
322	# see db_txn_finish documentation, above	355	# see db_txn_finish documentation, above
323		356
324	DBC/cursor methods	357	DBC/cursor methods
325	Methods available on DBC/$dbc handles:	358	Methods available on DBC/$dbc handles:
326		359
327	DESTROY (DBC_ornull *dbc)	360	DESTROY (DBC_ornull *dbc)
328	CODE:	361	CODE:
329	if (dbc)	362	if (dbc)
330	dbc->c_close (dbc);	363	dbc->c_close (dbc);
		364
		365	$int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
331		366
332	Example:	367	Example:
333	my $c = $db->cursor;	368	my $c = $db->cursor;
334		369
335	for (;;) {	370	for (;;) {
…		…
338	last if $!;	373	last if $!;
339	}	374	}
340		375
341	db_c_close $c;	376	db_c_close $c;
342		377
343	DB_SEQUENCE/sequence methods	378	DB_SEQUENCE/sequence methods
344	Methods available on DB_SEQUENCE/$seq handles:	379	Methods available on DB_SEQUENCE/$seq handles:
345		380
346	DESTROY (DB_SEQUENCE_ornull *seq)	381	DESTROY (DB_SEQUENCE_ornull *seq)
347	CODE:	382	CODE:
348	if (seq)	383	if (seq)
…		…
354	flags: SEQ_DEC SEQ_INC SEQ_WRAP	389	flags: SEQ_DEC SEQ_INC SEQ_WRAP
355	$int = $seq->set_range (db_seq_t min, db_seq_t max)	390	$int = $seq->set_range (db_seq_t min, db_seq_t max)
356		391
357	Example:	392	Example:
358	my $seq = $db->sequence;	393	my $seq = $db->sequence;
359		394
360	db_sequence_open $seq, undef, "seq", BDB::CREATE;	395	db_sequence_open $seq, undef, "seq", BDB::CREATE;
361	db_sequence_get $seq, undef, 1, my $value;	396	db_sequence_get $seq, undef, 1, my $value;
362		397
363	SUPPORT FUNCTIONS	398	SUPPORT FUNCTIONS
364	EVENT PROCESSING AND EVENT LOOP INTEGRATION	399	EVENT PROCESSING AND EVENT LOOP INTEGRATION
		400	$msg = BDB::strerror [$errno]
		401	Returns the string corresponding to the given errno value. If no
		402	argument is given, use $!.
		403
		404	Note that the BDB module also patches the $! variable directly, so
		405	you should be able to get a bdb error string by simply stringifying
		406	$!.
		407
365	$fileno = BDB::poll_fileno	408	$fileno = BDB::poll_fileno
366	Return the request result pipe file descriptor. This filehandle	409	Return the request result pipe file descriptor. This filehandle
367	must be polled for reading by some mechanism outside this module	410	must be polled for reading by some mechanism outside this module
368	(e.g. Event or select, see below or the SYNOPSIS). If the pipe	411	(e.g. Event or select, see below or the SYNOPSIS). If the pipe
369	becomes readable you have to call "poll_cb" to check the results.	412	becomes readable you have to call "poll_cb" to check the results.
…		…
438	Strictly equivalent to:	481	Strictly equivalent to:
439		482
440	BDB::poll_wait, BDB::poll_cb	483	BDB::poll_wait, BDB::poll_cb
441	while BDB::nreqs;	484	while BDB::nreqs;
442		485
		486	VERSION CHECKING
		487	BerkeleyDB comes in various versions, many of them have minor
		488	incompatibilities. This means that traditional "at least version x.x"
		489	checks are often not sufficient.
		490
		491	Example: set the log_autoremove option in a way compatible with <v4.7
		492	and v4.7. Note the use of & on the constants to avoid triggering a
		493	compiletime bug when the symbol isn't available.
		494
		495	$DB_ENV->set_flags (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
		496	$DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;
		497
		498	BDB::VERSION
		499	The "BDB::VERSION" function, when called without arguments, returns
		500	the Berkeley DB version as a v-string (usually with 3 components).
		501	You should use "lt" and "ge" operators exclusively to make
		502	comparisons.
		503
		504	Example: check for at least version 4.7.
		505
		506	BDB::VERSION ge v4.7 or die;
		507
		508	BDB::VERSION min-version
		509	Returns true if the BDB version is at least the given version
		510	(specified as a v-string), false otherwise.
		511
		512	Example: check for at least version 4.5.
		513
		514	BDB::VERSION v4.7 or die;
		515
		516	BDB::VERSION min-version, max-version
		517	Returns true of the BDB version is at least version "min-version"
		518	(specify "undef" or "v0" for any minimum version) and less then
		519	"max-version".
		520
		521	Example: check wether version is strictly less then v4.7.
		522
		523	BDB::VERSION v0, v4.7
		524	or die "version 4.7 is not yet supported";
		525
443	CONTROLLING THE NUMBER OF THREADS	526	CONTROLLING THE NUMBER OF THREADS
444	BDB::min_parallel $nthreads	527	BDB::min_parallel $nthreads
445	Set the minimum number of BDB threads to $nthreads. The current	528	Set the minimum number of BDB threads to $nthreads. The current
446	default is 8, which means eight asynchronous operations can execute	529	default is 8, which means eight asynchronous operations can execute
447	concurrently at any one time (the number of outstanding requests,	530	concurrently at any one time (the number of outstanding requests,
448	however, is unlimited).	531	however, is unlimited).
…		…
507	You can still queue as many requests as you want. Therefore,	590	You can still queue as many requests as you want. Therefore,
508	"max_oustsanding" is mainly useful in simple scripts (with low	591	"max_oustsanding" is mainly useful in simple scripts (with low
509	values) or as a stop gap to shield against fatal memory overflow	592	values) or as a stop gap to shield against fatal memory overflow
510	(with large values).	593	(with large values).
511		594
512	BDB::set_sync_prepare $cb	595	$old_cb = BDB::set_sync_prepare $cb
513	Sets a callback that is called whenever a request is created without	596	Sets a callback that is called whenever a request is created without
514	an explicit callback. It has to return two code references. The	597	an explicit callback. It has to return two code references. The
515	first is used as the request callback, and the second is called to	598	first is used as the request callback (it should save the return
516	wait until the first callback has been called. The default	599	status), and the second is called to wait until the first callback
517	implementation works like this:	600	has been called (it must set $! to the return status).
		601
		602	This mechanism can be used to include BDB into other event
		603	mechanisms, such as Coro::BDB.
		604
		605	To allow other, callback-based, events to be executed while
		606	callback-less ones are run, you could use this sync prepare
		607	function:
518		608
519	sub {	609	sub {
520	my $status;	610	my $status;
521	(	611	(
522	sub { $status = $! },	612	sub { $status = $! },
523	sub { BDB::poll while !defined $status; $! = $status },	613	sub { BDB::poll while !defined $status; $! = $status },
524	)	614	)
525	}	615	}
526		616
		617	It works by polling for results till the request has finished and
		618	then sets $! to the return value. This means that if you don't use a
		619	callback, BDB would simply fall back to synchronous operations.
		620
		621	By default, or if the sync prepare function is set to "undef", is to
		622	execute callback-less BDB requests in the foreground thread, setting
		623	$! to the return value, without polling for other events.
		624
527	STATISTICAL INFORMATION	625	STATISTICAL INFORMATION
528	BDB::nreqs	626	BDB::nreqs
529	Returns the number of requests currently in the ready, execute or	627	Returns the number of requests currently in the ready, execute or
530	pending states (i.e. for which their callback has not been invoked	628	pending states (i.e. for which their callback has not been invoked
531	yet).	629	yet).
532		630
…		…
541		639
542	BDB::npending	640	BDB::npending
543	Returns the number of requests currently in the pending state	641	Returns the number of requests currently in the pending state
544	(executed, but not yet processed by poll_cb).	642	(executed, but not yet processed by poll_cb).
545		643
		644	COMMON PITFALLS
		645	Unexpected Crashes
		646	Remember that, by default, BDB will execute requests in parallel, in
		647	somewhat random order. That means that it is easy to run a "db_get"
		648	request on thesa me database as a concurrent "db_close" request, leading
		649	to a crash, silent data corruption, eventually the next world war on
		650	terrorism.
		651
		652	If you only ever use foreground requests (without a callback), this will
		653	not be an issue.
		654
		655	Unexpected Freezes or Deadlocks
		656	Remember that, by default, BDB will execute requests in parallel, which
		657	easily leads to deadlocks (even concurrent put's on the same database
		658	can deadlock).
		659
		660	You either need to run deadlock detection (and handle the resulting
		661	errors), or make sure only one process ever updates the database, ine
		662	one thread, e.g. by using only foreground requests (without a callback).
		663
546	FORK BEHAVIOUR	664	FORK BEHAVIOUR
547	This module should do "the right thing" when the process using it forks:	665	This module should do "the right thing" when the process using it forks:
548		666
549	Before the fork, BDB enters a quiescent state where no requests can be	667	Before the fork, BDB enters a quiescent state where no requests can be
550	added in other threads and no results will be processed. After the fork	668	added in other threads and no results will be processed. After the fork
551	the parent simply leaves the quiescent state and continues	669	the parent simply leaves the quiescent state and continues
…		…
556		674
557	In short: the parent will, after a short pause, continue as if fork had	675	In short: the parent will, after a short pause, continue as if fork had
558	not been called, while the child will act as if BDB has not been used	676	not been called, while the child will act as if BDB has not been used
559	yet.	677	yet.
560		678
		679	Win32 note: there is no fork on win32, and perls emulation of it is too
		680	broken to be supported, so do not use BDB in a windows pseudo-fork,
		681	better yet, switch to a more capable platform.
		682
561	MEMORY USAGE	683	MEMORY USAGE
562	Per-request usage:	684	Per-request usage:
563		685
564	Each aio request uses - depending on your architecture - around 100-200	686	Each aio request uses - depending on your architecture - around 100-200
565	bytes of memory. In addition, stat requests need a stat buffer (possibly	687	bytes of memory. In addition, stat requests need a stat buffer (possibly
566	a few hundred bytes), readdir requires a result buffer and so on. Perl	688	a few hundred bytes), readdir requires a result buffer and so on. Perl
…		…
574		696
575	In the execution phase, some aio requests require more memory for	697	In the execution phase, some aio requests require more memory for
576	temporary buffers, and each thread requires a stack and other data	698	temporary buffers, and each thread requires a stack and other data
577	structures (usually around 16k-128k, depending on the OS).	699	structures (usually around 16k-128k, depending on the OS).
578		700
		701	WIN32 FILENAMES/DATABASE NAME MESS
		702	Perl on Win32 supports only ASCII filenames (the reason is that it
		703	abuses an internal flag to store wether a filename is Unicode or ANSI,
		704	but that flag is used for somethign else in the perl core, so there is
		705	no way to detect wether a filename is ANSI or Unicode-encoded). The BDB
		706	module tries to work around this issue by assuming that the filename is
		707	an ANSI filename and BDB was built for unicode support.
		708
579	KNOWN BUGS	709	KNOWN BUGS
580	Known bugs will be fixed in the next release, except:	710	Known bugs will be fixed in the next release, except:
581		711
582	If you use a transaction in any request, and the request returns	712	If you use a transaction in any request, and the request returns
583	with an operating system error or DB_LOCK_NOTGRANTED, the internal	713	with an operating system error or DB_LOCK_NOTGRANTED, the internal
584	TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,	714	TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
585	above.	715	above.
586		716
587	SEE ALSO	717	SEE ALSO
588	Coro::BDB, IO::AIO.	718	AnyEvent::BDB (event loop integration), Coro::BDB (more natural syntax),
		719	IO::AIO (nice to have).
589		720
590	AUTHOR	721	AUTHOR
591	Marc Lehmann <schmorp@schmorp.de>	722	Marc Lehmann <schmorp@schmorp.de>
592	http://home.schmorp.de/	723	http://home.schmorp.de/
593		724

Diff Legend

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

Comparing BDB/README (file contents): Revision 1.4 by root, Fri Dec 7 13:39:04 2007 UTC vs. Revision 1.14 by root, Tue Oct 21 02:21:25 2008 UTC

Diff Legend

Comparing BDB/README (file contents):
Revision 1.4 by root, Fri Dec 7 13:39:04 2007 UTC vs.
Revision 1.14 by root, Tue Oct 21 02:21:25 2008 UTC