[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.10 by root, Tue Jul 8 08:35:12 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
		91	WIN32 FILENAMES/DATABASE NAME MESS
		92	Perl on Win32 supports only ASCII filenames (the reason is that it
		93	abuses an internal flag to store wether a filename is Unicode or ANSI,
		94	but that flag is used for somethign else in the perl core, so there is
		95	no way to detect wether a filename is ANSI or Unicode-encoded). The BDB
		96	module tries to work around this issue by assuming that the filename is
		97	an ANSI filename and BDB was built for unicode support.
		98
89	BERKELEYDB FUNCTIONS	99	BERKELEYDB FUNCTIONS
90	All of these are functions. The create functions simply return a new	100	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	101	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	102	callback as last argument. If it is missing, then the function will be
93	executed synchronously.	103	executed synchronously. In both cases, $! will reflect the return value
		104	of the function.
94		105
95	BDB functions that cannot block (mostly functions that manipulate	106	BDB functions that cannot block (mostly functions that manipulate
96	settings) are method calls on the relevant objects, so the rule of thumb	107	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	108	is: if it's a method, it's not blocking, if it's a function, it takes a
98	callback as last argument.	109	callback as last argument.
99		110
100	In the following, $int signifies an integer return value, "octetstring"	111	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	112	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"	113	unsigned 32 bit integer, "int" is some integer, "NV" is a floating point
103	is a floating point value.	114	value.
104		115
105	The "SV *" types are generic perl scalars (for input and output of data	116	The "SV *" types are generic perl scalars (for input and output of data
106	values), and the "SV *callback" is the optional callback function to	117	values), and the "SV *callback" is the optional callback function to
107	call when the request is completed.	118	call when the request is completed.
108		119
…		…
115	Functions in the BDB namespace, exported by default:	126	Functions in the BDB namespace, exported by default:
116		127
117	$env = db_env_create (U32 env_flags = 0)	128	$env = db_env_create (U32 env_flags = 0)
118	flags: RPCCLIENT	129	flags: RPCCLIENT
119		130
120	db_env_open (DB_ENV env, octetstring db_home, U32 open_flags, int mode, SV callback = &PL_sv_undef)	131	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	132	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)	133	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)	134	db_env_txn_checkpoint (DB_ENV env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV callback = &PL_sv_undef)
124	flags: FORCE	135	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)	136	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	137	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)	138	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)	139	db_env_memp_trickle (DB_ENV env, int percent, SV dummy = 0, SV *callback = &PL_sv_undef)
		140	db_env_dbremove (DB_ENV env, DB_TXN_ornull txnid, bdb_filename file, bdb_filename database, U32 flags = 0, SV *callback = &PL_sv_undef)
		141	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)
129		142
130	$db = db_create (DB_ENV *env = 0, U32 flags = 0)	143	$db = db_create (DB_ENV *env = 0, U32 flags = 0)
131	flags: XA_CREATE	144	flags: XA_CREATE
132		145
133	db_open (DB db, DB_TXN_ornull txnid, octetstring file, octetstring database, int type, U32 flags, int mode, SV *callback = &PL_sv_undef)	146	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	147	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)	148	db_close (DB db, U32 flags = 0, SV callback = &PL_sv_undef)
136	flags: DB_NOSYNC	149	flags: DB_NOSYNC
		150	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)	151	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	152	flags: FREELIST_ONLY FREE_SPACE
139	db_sync (DB db, U32 flags = 0, SV callback = &PL_sv_undef)	153	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)	154	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)	155	db_put (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = &PL_sv_undef)
…		…
212	$int = $env->set_data_dir (const char *dir)	226	$int = $env->set_data_dir (const char *dir)
213	$int = $env->set_tmp_dir (const char *dir)	227	$int = $env->set_tmp_dir (const char *dir)
214	$int = $env->set_lg_dir (const char *dir)	228	$int = $env->set_lg_dir (const char *dir)
215	$int = $env->set_shm_key (long shm_key)	229	$int = $env->set_shm_key (long shm_key)
216	$int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)	230	$int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
217	$int = $env->set_flags (U32 flags, int onoff)	231	$int = $env->set_flags (U32 flags, int onoff = 1)
		232	$int = $env->log_set_config (U32 flags, int onoff = 1) [v4.7]
		233	$int = $env->set_intermediate_dir_mode (const char *modestring) [v4.7]
218	$env->set_errfile (FILE *errfile = 0)	234	$env->set_errfile (FILE *errfile = 0)
219	$env->set_msgfile (FILE *msgfile = 0)	235	$env->set_msgfile (FILE *msgfile = 0)
220	$int = $env->set_verbose (U32 which, int onoff = 1)	236	$int = $env->set_verbose (U32 which, int onoff = 1)
221	$int = $env->set_encrypt (const char *password, U32 flags = 0)	237	$int = $env->set_encrypt (const char *password, U32 flags = 0)
222	$int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)	238	$int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
…		…
327	DESTROY (DBC_ornull *dbc)	343	DESTROY (DBC_ornull *dbc)
328	CODE:	344	CODE:
329	if (dbc)	345	if (dbc)
330	dbc->c_close (dbc);	346	dbc->c_close (dbc);
331		347
		348	$int = $cursor->set_priority ($priority = PRIORITY_*)
		349
332	Example:	350	Example:
333	my $c = $db->cursor;	351	my $c = $db->cursor;
334		352
335	for (;;) {	353	for (;;) {
336	db_c_get $c, my $key, my $data, BDB::NEXT;	354	db_c_get $c, my $key, my $data, BDB::NEXT;
…		…
354	flags: SEQ_DEC SEQ_INC SEQ_WRAP	372	flags: SEQ_DEC SEQ_INC SEQ_WRAP
355	$int = $seq->set_range (db_seq_t min, db_seq_t max)	373	$int = $seq->set_range (db_seq_t min, db_seq_t max)
356		374
357	Example:	375	Example:
358	my $seq = $db->sequence;	376	my $seq = $db->sequence;
359		377
360	db_sequence_open $seq, undef, "seq", BDB::CREATE;	378	db_sequence_open $seq, undef, "seq", BDB::CREATE;
361	db_sequence_get $seq, undef, 1, my $value;	379	db_sequence_get $seq, undef, 1, my $value;
362		380
363	SUPPORT FUNCTIONS	381	SUPPORT FUNCTIONS
364	EVENT PROCESSING AND EVENT LOOP INTEGRATION	382	EVENT PROCESSING AND EVENT LOOP INTEGRATION
		383	$msg = BDB::strerror [$errno]
		384	Returns the string corresponding to the given errno value. If no
		385	argument is given, use $!.
		386
		387	Note that the BDB module also patches the $! variable directly, so
		388	you should be able to get a bdb error string by simply stringifying
		389	$!.
		390
365	$fileno = BDB::poll_fileno	391	$fileno = BDB::poll_fileno
366	Return the request result pipe file descriptor. This filehandle	392	Return the request result pipe file descriptor. This filehandle
367	must be polled for reading by some mechanism outside this module	393	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	394	(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.	395	becomes readable you have to call "poll_cb" to check the results.
…		…
438	Strictly equivalent to:	464	Strictly equivalent to:
439		465
440	BDB::poll_wait, BDB::poll_cb	466	BDB::poll_wait, BDB::poll_cb
441	while BDB::nreqs;	467	while BDB::nreqs;
442		468
		469	VERSION CHECKING
		470	BerkeleyDB comes in various versions, many of them have minor
		471	incompatibilities. This means that traditional "at least version x.x"
		472	checks are often not sufficient.
		473
		474	Example: set the log_autoremove option in a way compatible with <v.47
		475	and v4.7. Note the use of & on the constants to avoid triggering a
		476	compiletime bug when the symbol isn't available.
		477
		478	$DB_ENV->set_flags (&BDB::LOG_AUTOREMOVE ) if BDB::VERSION v0, v4.7;
		479	$DB_ENV->log_set_config (&BDB::LOG_AUTO_REMOVE) if BDB::VERSION v4.7;
		480
		481	BDB::VERSION
		482	The "BDB::VERSION" function, when called without arguments, returns
		483	the Berkeley DB version as a v-string (usually with 3 components).
		484	You should use "lt" and "ge" operators exclusively to make
		485	comparisons.
		486
		487	Example: check for at least version 4.7.
		488
		489	BDB::VERSION ge v4.7 or die;
		490
		491	BDB::VERSION min-version
		492	Returns true if the BDB version is at least the given version
		493	(specified as a v-string), false otherwise.
		494
		495	Example: check for at least version 4.5.
		496
		497	BDB::VERSION v4.7 or die;
		498
		499	BDB::VERSION min-version, max-version
		500	Returns true of the BDB version is at least version "min-version"
		501	(specify "undef" or "v0" for any minimum version) and less then
		502	"max-version".
		503
		504	Example: check wether version is strictly less then v4.7.
		505
		506	BDB::VERSION v0, v4.7
		507	or die "version 4.7 is not yet supported";
		508
443	CONTROLLING THE NUMBER OF THREADS	509	CONTROLLING THE NUMBER OF THREADS
444	BDB::min_parallel $nthreads	510	BDB::min_parallel $nthreads
445	Set the minimum number of BDB threads to $nthreads. The current	511	Set the minimum number of BDB threads to $nthreads. The current
446	default is 8, which means eight asynchronous operations can execute	512	default is 8, which means eight asynchronous operations can execute
447	concurrently at any one time (the number of outstanding requests,	513	concurrently at any one time (the number of outstanding requests,
…		…
510	(with large values).	576	(with large values).
511		577
512	BDB::set_sync_prepare $cb	578	BDB::set_sync_prepare $cb
513	Sets a callback that is called whenever a request is created without	579	Sets a callback that is called whenever a request is created without
514	an explicit callback. It has to return two code references. The	580	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	581	first is used as the request callback (it should save the return
516	wait until the first callback has been called. The default	582	status), and the second is called to wait until the first callback
		583	has been called (it must set $! to the return status).
		584
		585	This mechanism can be used to include BDB into other event
		586	mechanisms, such as AnyEvent::BDB or Coro::BDB.
		587
517	implementation works like this:	588	The default implementation works like this:
518		589
519	sub {	590	sub {
520	my $status;	591	my $status;
521	(	592	(
522	sub { $status = $! },	593	sub { $status = $! },
523	sub { BDB::poll while !defined $status; $! = $status },	594	sub { BDB::poll while !defined $status; $! = $status },
524	)	595	)
525	}	596	}
526		597
		598	It simply blocks the process till the request has finished and then
		599	sets $! to the return value. This means that if you don't use a
		600	callback, BDB will simply fall back to synchronous operations.
		601
527	STATISTICAL INFORMATION	602	STATISTICAL INFORMATION
528	BDB::nreqs	603	BDB::nreqs
529	Returns the number of requests currently in the ready, execute or	604	Returns the number of requests currently in the ready, execute or
530	pending states (i.e. for which their callback has not been invoked	605	pending states (i.e. for which their callback has not been invoked
531	yet).	606	yet).
…		…
556		631
557	In short: the parent will, after a short pause, continue as if fork had	632	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	633	not been called, while the child will act as if BDB has not been used
559	yet.	634	yet.
560		635
		636	Win32 note: there is no fork on win32, and perls emulation of it is too
		637	broken to be supported, so do not use BDB in a windows pseudo-fork,
		638	better yet, switch to a more capable platform.
		639
561	MEMORY USAGE	640	MEMORY USAGE
562	Per-request usage:	641	Per-request usage:
563		642
564	Each aio request uses - depending on your architecture - around 100-200	643	Each aio request uses - depending on your architecture - around 100-200
565	bytes of memory. In addition, stat requests need a stat buffer (possibly	644	bytes of memory. In addition, stat requests need a stat buffer (possibly
…		…
583	with an operating system error or DB_LOCK_NOTGRANTED, the internal	662	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>,	663	TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
585	above.	664	above.
586		665
587	SEE ALSO	666	SEE ALSO
588	Coro::BDB, IO::AIO.	667	AnyEvent::BDB (event loop integration), Coro::BDB (more natural syntax),
		668	IO::AIO (nice to have).
589		669
590	AUTHOR	670	AUTHOR
591	Marc Lehmann <schmorp@schmorp.de>	671	Marc Lehmann <schmorp@schmorp.de>
592	http://home.schmorp.de/	672	http://home.schmorp.de/
593		673

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.10 by root, Tue Jul 8 08:35:12 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.10 by root, Tue Jul 8 08:35:12 2008 UTC