[ViewVC] Diff of: cvs/BDB/README

Comparing BDB/README (file contents):
Revision 1.1 by root, Mon Feb 5 18:40:55 2007 UTC vs.
Revision 1.15 by root, Sun Jan 11 00:56:09 2009 UTC

…		…
1	NAME	1	NAME
2	BDB::AIO - Asynchronous Berkeley DB access	2	BDB - Asynchronous Berkeley DB access
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use BDB::AIO;	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
7	DESCRIPTION	43	DESCRIPTION
8	EXAMPLE	44	See the BerkeleyDB documentation
		45	(<http://www.oracle.com/technology/documentation/berkeley-db/db/index.ht
		46	ml>). The BDB API is very similar to the C API (the translation has been
		47	very faithful).
		48
		49	See also the example sections in the document below and possibly the eg/
		50	subdirectory of the BDB distribution. Last not least see the IO::AIO
		51	documentation, as that module uses almost the same asynchronous request
		52	model as this module.
		53
		54	I know this is woefully inadequate documentation. Send a patch!
		55
9	REQUEST ANATOMY AND LIFETIME	56	REQUEST ANATOMY AND LIFETIME
10	Every request method creates a request. which is a C data structure not	57	Every request method creates a request. which is a C data structure not
11	directly visible to Perl.	58	directly visible to Perl.
12		59
13	During their existance, bdb requests travel through the following	60	During their existance, bdb requests travel through the following
39	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
40	anymore (except possibly for the Perl object, but its connection to	87	anymore (except possibly for the Perl object, but its connection to
41	the actual aio request is severed and calling its methods will	88	the actual aio request is severed and calling its methods will
42	either do nothing or result in a runtime error).	89	either do nothing or result in a runtime error).
43		90
		91	BERKELEYDB FUNCTIONS
		92	All of these are functions. The create functions simply return a new
		93	object and never block. All the remaining functions take an optional
		94	callback as last argument. If it is missing, then the function will be
		95	executed synchronously. In both cases, $! will reflect the return value
		96	of the function.
		97
		98	BDB functions that cannot block (mostly functions that manipulate
		99	settings) are method calls on the relevant objects, so the rule of thumb
		100	is: if it's a method, it's not blocking, if it's a function, it takes a
		101	callback as last argument.
		102
		103	In the following, $int signifies an integer return value, "bdb_filename"
		104	is a "filename" (octets on unix, madness on windows), "U32" is an
		105	unsigned 32 bit integer, "int" is some integer, "NV" is a floating point
		106	value.
		107
		108	Most "SV *" types are generic perl scalars (for input and output of data
		109	values).
		110
		111	The various "DB_ENV" etc. arguments are handles return by
		112	"db_env_create", "db_create", "txn_begin" and so on. If they have an
		113	appended "_ornull" this means they are optional and you can pass "undef"
		114	for them, resulting a NULL pointer on the C level.
		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
		139	BDB functions
		140	Functions in the BDB namespace, exported by default:
		141
		142	$env = db_env_create (U32 env_flags = 0)
		143	flags: RPCCLIENT
		144
		145	db_env_open (DB_ENV env, bdb_filename db_home, U32 open_flags, int mode, SV callback = 0)
		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
		147	db_env_close (DB_ENV env, U32 flags = 0, SV callback = 0)
		148	db_env_txn_checkpoint (DB_ENV env, U32 kbyte = 0, U32 min = 0, U32 flags = 0, SV callback = 0)
		149	flags: FORCE
		150	db_env_lock_detect (DB_ENV env, U32 flags = 0, U32 atype = DB_LOCK_DEFAULT, SV dummy = 0, SV *callback = 0)
		151	atype: LOCK_DEFAULT LOCK_EXPIRE LOCK_MAXLOCKS LOCK_MAXWRITE LOCK_MINLOCKS LOCK_MINWRITE LOCK_OLDEST LOCK_RANDOM LOCK_YOUNGEST
		152	db_env_memp_sync (DB_ENV env, SV dummy = 0, SV *callback = 0)
		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)
		157
		158	$db = db_create (DB_ENV *env = 0, U32 flags = 0)
		159	flags: XA_CREATE
		160
		161	db_open (DB db, DB_TXN_ornull txnid, bdb_filename file, bdb_filename database, int type, U32 flags, int mode, SV *callback = 0)
		162	flags: AUTO_COMMIT CREATE EXCL MULTIVERSION NOMMAP RDONLY READ_UNCOMMITTED THREAD TRUNCATE
		163	db_close (DB db, U32 flags = 0, SV callback = 0)
		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)
		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)
		168	flags: FREELIST_ONLY FREE_SPACE
		169	db_sync (DB db, U32 flags = 0, SV callback = 0)
		170	db_key_range (DB db, DB_TXN_ornull txn, SV key, SV key_range, U32 flags = 0, SV *callback = 0)
		171	db_put (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = 0)
		172	flags: APPEND NODUPDATA NOOVERWRITE
		173	db_exists (DB db, DB_TXN_ornull txn, SV key, U32 flags = 0, SV callback = 0) (v4.6)
		174	db_get (DB db, DB_TXN_ornull txn, SV key, SV data, U32 flags = 0, SV *callback = 0)
		175	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
		176	db_pget (DB db, DB_TXN_ornull txn, SV key, SV pkey, SV data, U32 flags = 0, SV callback = 0)
		177	flags: CONSUME CONSUME_WAIT GET_BOTH SET_RECNO MULTIPLE READ_COMMITTED READ_UNCOMMITTED RMW
		178	db_del (DB db, DB_TXN_ornull txn, SV key, U32 flags = 0, SV callback = 0)
		179	db_txn_commit (DB_TXN txn, U32 flags = 0, SV callback = 0)
		180	flags: TXN_NOSYNC TXN_SYNC
		181	db_txn_abort (DB_TXN txn, SV callback = 0)
		182
		183	db_c_close (DBC dbc, SV callback = 0)
		184	db_c_count (DBC dbc, SV count, U32 flags = 0, SV *callback = 0)
		185	db_c_put (DBC dbc, SV key, SV data, U32 flags = 0, SV callback = 0)
		186	flags: AFTER BEFORE CURRENT KEYFIRST KEYLAST NODUPDATA
		187	db_c_get (DBC dbc, SV key, SV data, U32 flags = 0, SV callback = 0)
		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
		189	db_c_pget (DBC dbc, SV key, SV pkey, SV data, U32 flags = 0, SV *callback = 0)
		190	db_c_del (DBC dbc, U32 flags = 0, SV callback = 0)
		191
		192	db_sequence_open (DB_SEQUENCE seq, DB_TXN_ornull txnid, SV key, U32 flags = 0, SV callback = 0)
		193	flags: CREATE EXCL
		194	db_sequence_close (DB_SEQUENCE seq, U32 flags = 0, SV callback = 0)
		195	db_sequence_get (DB_SEQUENCE seq, DB_TXN_ornull txnid, int delta, SV seq_value, U32 flags = DB_TXN_NOSYNC, SV callback = 0)
		196	flags: TXN_NOSYNC
		197	db_sequence_remove (DB_SEQUENCE seq, DB_TXN_ornull txnid = 0, U32 flags = 0, SV *callback = 0)
		198	flags: TXN_NOSYNC
		199
		200	db_txn_finish (DB_TXN txn, U32 flags = 0, SV callback = 0)
		201	This is not actually a Berkeley DB function but a BDB module extension.
		202	The background for this exytension is: It is very annoying to have to
		203	check every single BDB function for error returns and provide a codepath
		204	out of your transaction. While the BDB module still makes this possible,
		205	it contains the following extensions:
		206
		207	When a transaction-protected function returns any operating system error
		208	(errno > 0), BDB will set the "TXN_DEADLOCK" flag on the transaction.
		209	This flag is also set by Berkeley DB functions themselves when an
		210	operation fails with LOCK_DEADLOCK, and it causes all further operations
		211	on that transaction (including "db_txn_commit") to fail.
		212
		213	The "db_txn_finish" request will look at this flag, and, if it is set,
		214	will automatically call "db_txn_abort" (setting errno to "LOCK_DEADLOCK"
		215	if it isn't set to something else yet). If it isn't set, it will call
		216	"db_txn_commit" and return the error normally.
		217
		218	How to use this? Easy: just write your transaction normally:
		219
		220	my $txn = $db_env->txn_begin;
		221	db_get $db, $txn, "key", my $data;
		222	db_put $db, $txn, "key", $data + 1 unless $! == BDB::NOTFOUND;
		223	db_txn_finish $txn;
		224	die "transaction failed" if $!;
		225
		226	That is, handle only the expected errors. If something unexpected
		227	happens (EIO, LOCK_NOTGRANTED or a deadlock in either db_get or db_put),
		228	then the remaining requests (db_put in this case) will simply be skipped
		229	(they will fail with LOCK_DEADLOCK) and the transaction will be aborted.
		230
		231	You can use the "$txn->failed" method to check wether a transaction has
		232	failed in this way and abort further processing (excluding
		233	"db_txn_finish").
		234
		235	DB_ENV/database environment methods
		236	Methods available on DB_ENV/$env handles:
		237
		238	DESTROY (DB_ENV_ornull *env)
		239	CODE:
		240	if (env)
		241	env->close (env, 0);
		242
		243	$int = $env->set_data_dir (const char *dir)
		244	$int = $env->set_tmp_dir (const char *dir)
		245	$int = $env->set_lg_dir (const char *dir)
		246	$int = $env->set_shm_key (long shm_key)
		247	$int = $env->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
		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)
		251	$env->set_errfile (FILE *errfile = 0)
		252	$env->set_msgfile (FILE *msgfile = 0)
		253	$int = $env->set_verbose (U32 which, int onoff = 1)
		254	$int = $env->set_encrypt (const char *password, U32 flags = 0)
		255	$int = $env->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
		256	$int = $env->set_mp_max_openfd (int maxopenfd);
		257	$int = $env->set_mp_max_write (int maxwrite, int maxwrite_sleep);
		258	$int = $env->set_mp_mmapsize (int mmapsize_mb)
		259	$int = $env->set_lk_detect (U32 detect = DB_LOCK_DEFAULT)
		260	$int = $env->set_lk_max_lockers (U32 max)
		261	$int = $env->set_lk_max_locks (U32 max)
		262	$int = $env->set_lk_max_objects (U32 max)
		263	$int = $env->set_lg_bsize (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)
		269
		270	$txn = $env->txn_begin (DB_TXN_ornull *parent = 0, U32 flags = 0)
		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)
		273
		274	Example:
		275	use AnyEvent;
		276	use BDB;
		277
		278	our $FH; open $FH, "<&=" . BDB::poll_fileno;
		279	our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r', cb => \&BDB::poll_cb);
		280
		281	BDB::min_parallel 8;
		282
		283	my $env = db_env_create;
		284
		285	mkdir "bdtest", 0700;
		286	db_env_open
		287	$env,
		288	"bdtest",
		289	BDB::INIT_LOCK \| BDB::INIT_LOG \| BDB::INIT_MPOOL \| BDB::INIT_TXN \| BDB::RECOVER \| BDB::USE_ENVIRON \| BDB::CREATE,
		290	0600;
		291
		292	$env->set_flags (BDB::AUTO_COMMIT \| BDB::TXN_NOSYNC, 1);
		293
		294	DB/database methods
		295	Methods available on DB/$db handles:
		296
		297	DESTROY (DB_ornull *db)
		298	CODE:
		299	if (db)
		300	{
		301	SV env = (SV )db->app_private;
		302	db->close (db, 0);
		303	SvREFCNT_dec (env);
		304	}
		305
		306	$int = $db->set_cachesize (U32 gbytes, U32 bytes, int ncache = 0)
		307	$int = $db->set_flags (U32 flags)
		308	flags: CHKSUM ENCRYPT TXN_NOT_DURABLE
		309	Btree: DUP DUPSORT RECNUM REVSPLITOFF
		310	Hash: DUP DUPSORT
		311	Queue: INORDER
		312	Recno: RENUMBER SNAPSHOT
		313
		314	$int = $db->set_encrypt (const char *password, U32 flags)
		315	$int = $db->set_lorder (int lorder)
		316	$int = $db->set_bt_minkey (U32 minkey)
		317	$int = $db->set_re_delim (int delim)
		318	$int = $db->set_re_pad (int re_pad)
		319	$int = $db->set_re_source (char *source)
		320	$int = $db->set_re_len (U32 re_len)
		321	$int = $db->set_h_ffactor (U32 h_ffactor)
		322	$int = $db->set_h_nelem (U32 h_nelem)
		323	$int = $db->set_q_extentsize (U32 extentsize)
		324
		325	$dbc = $db->cursor (DB_TXN_ornull *txn = 0, U32 flags = 0)
		326	flags: READ_COMMITTED READ_UNCOMMITTED WRITECURSOR TXN_SNAPSHOT
		327	$seq = $db->sequence (U32 flags = 0)
		328
		329	Example:
		330	my $db = db_create $env;
		331	db_open $db, undef, "table", undef, BDB::BTREE, BDB::AUTO_COMMIT \| BDB::CREATE \| BDB::READ_UNCOMMITTED, 0600;
		332
		333	for (1..1000) {
		334	db_put $db, undef, "key $_", "data $_";
		335
		336	db_key_range $db, undef, "key $_", my $keyrange;
		337	my ($lt, $eq, $gt) = @$keyrange;
		338	}
		339
		340	db_del $db, undef, "key $_" for 1..1000;
		341
		342	db_sync $db;
		343
		344	DB_TXN/transaction methods
		345	Methods available on DB_TXN/$txn handles:
		346
		347	DESTROY (DB_TXN_ornull *txn)
		348	CODE:
		349	if (txn)
		350	txn->abort (txn);
		351
		352	$int = $txn->set_timeout (NV timeout_seconds, U32 flags = SET_TXN_TIMEOUT)
		353	flags: SET_LOCK_TIMEOUT SET_TXN_TIMEOUT
		354
		355	$bool = $txn->failed
		356	# see db_txn_finish documentation, above
		357
		358	DBC/cursor methods
		359	Methods available on DBC/$dbc handles:
		360
		361	DESTROY (DBC_ornull *dbc)
		362	CODE:
		363	if (dbc)
		364	dbc->c_close (dbc);
		365
		366	$int = $cursor->set_priority ($priority = PRIORITY_*) (v4.6)
		367
		368	Example:
		369	my $c = $db->cursor;
		370
		371	for (;;) {
		372	db_c_get $c, my $key, my $data, BDB::NEXT;
		373	warn "<$!,$key,$data>";
		374	last if $!;
		375	}
		376
		377	db_c_close $c;
		378
		379	DB_SEQUENCE/sequence methods
		380	Methods available on DB_SEQUENCE/$seq handles:
		381
		382	DESTROY (DB_SEQUENCE_ornull *seq)
		383	CODE:
		384	if (seq)
		385	seq->close (seq, 0);
		386
		387	$int = $seq->initial_value (db_seq_t value)
		388	$int = $seq->set_cachesize (U32 size)
		389	$int = $seq->set_flags (U32 flags)
		390	flags: SEQ_DEC SEQ_INC SEQ_WRAP
		391	$int = $seq->set_range (db_seq_t min, db_seq_t max)
		392
		393	Example:
		394	my $seq = $db->sequence;
		395
		396	db_sequence_open $seq, undef, "seq", BDB::CREATE;
		397	db_sequence_get $seq, undef, 1, my $value;
		398
44	SUPPORT FUNCTIONS	399	SUPPORT FUNCTIONS
45	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
46	$fileno = BDB::AIO::poll_fileno	409	$fileno = BDB::poll_fileno
47	Return the request result pipe file descriptor. This filehandle	410	Return the request result pipe file descriptor. This filehandle
48	must be polled for reading by some mechanism outside this module	411	must be polled for reading by some mechanism outside this module
49	(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
50	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.
51		414
52	See "poll_cb" for an example.	415	See "poll_cb" for an example.
53		416
54	BDB::AIO::poll_cb	417	BDB::poll_cb
55	Process some outstanding events on the result pipe. You have to call	418	Process some outstanding events on the result pipe. You have to call
56	this regularly. Returns the number of events processed. Returns	419	this regularly. Returns the number of events processed. Returns
57	immediately when no events are outstanding. The amount of events	420	immediately when no events are outstanding. The amount of events
58	processed depends on the settings of "BDB::AIO::max_poll_req" and	421	processed depends on the settings of "BDB::max_poll_req" and
59	"BDB::AIO::max_poll_time".	422	"BDB::max_poll_time".
60		423
61	If not all requests were processed for whatever reason, the	424	If not all requests were processed for whatever reason, the
62	filehandle will still be ready when "poll_cb" returns.	425	filehandle will still be ready when "poll_cb" returns.
63		426
64	Example: Install an Event watcher that automatically calls	427	Example: Install an Event watcher that automatically calls
65	BDB::AIO::poll_cb with high priority:	428	BDB::poll_cb with high priority:
66		429
67	Event->io (fd => BDB::AIO::poll_fileno,	430	Event->io (fd => BDB::poll_fileno,
68	poll => 'r', async => 1,	431	poll => 'r', async => 1,
69	cb => \&BDB::AIO::poll_cb);	432	cb => \&BDB::poll_cb);
70		433
71	BDB::AIO::max_poll_reqs $nreqs	434	BDB::max_poll_reqs $nreqs
72	BDB::AIO::max_poll_time $seconds	435	BDB::max_poll_time $seconds
73	These set the maximum number of requests (default 0, meaning	436	These set the maximum number of requests (default 0, meaning
74	infinity) that are being processed by "BDB::AIO::poll_cb" in one	437	infinity) that are being processed by "BDB::poll_cb" in one call,
75	call, respectively the maximum amount of time (default 0, meaning	438	respectively the maximum amount of time (default 0, meaning
76	infinity) spent in "BDB::AIO::poll_cb" to process requests (more	439	infinity) spent in "BDB::poll_cb" to process requests (more
77	correctly the mininum amount of time "poll_cb" is allowed to use).	440	correctly the mininum amount of time "poll_cb" is allowed to use).
78		441
79	Setting "max_poll_time" to a non-zero value creates an overhead of	442	Setting "max_poll_time" to a non-zero value creates an overhead of
80	one syscall per request processed, which is not normally a problem	443	one syscall per request processed, which is not normally a problem
81	unless your callbacks are really really fast or your OS is really	444	unless your callbacks are really really fast or your OS is really
…		…
86	interactiveness when perl is not fast enough to process all requests	449	interactiveness when perl is not fast enough to process all requests
87	in time.	450	in time.
88		451
89	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.
90		453
91	Example: Install an Event watcher that automatically calls	454	Example: Install an EV watcher that automatically calls BDB::poll_cb
92	BDB::AIO::poll_cb with low priority, to ensure that other parts of	455	with low priority, to ensure that other parts of the program get the
93	the program get the CPU sometimes even under high AIO load.	456	CPU sometimes even under high load.
94		457
95	# 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
96	BDB::AIO::max_poll_time 0.1;	459	BDB::max_poll_time 0.1;
97		460
98	# use a low priority so other tasks have priority	461	my $bdb_poll = EV::io BDB::poll_fileno, EV::READ, \&BDB::poll_cb);
99	Event->io (fd => BDB::AIO::poll_fileno,
100	poll => 'r', nice => 1,
101	cb => &BDB::AIO::poll_cb);
102		462
103	BDB::AIO::poll_wait	463	BDB::poll_wait
104	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
105	phase, wait till the result filehandle becomes ready for reading	465	phase, wait till the result filehandle becomes ready for reading
106	(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
107	want to synchronously wait for some requests to finish).	467	want to synchronously wait for some requests to finish).
108		468
109	See "nreqs" for an example.	469	See "nreqs" for an example.
110		470
111	BDB::AIO::poll	471	BDB::poll
112	Waits until some requests have been handled.	472	Waits until some requests have been handled.
113		473
114	Returns the number of requests processed, but is otherwise strictly	474	Returns the number of requests processed, but is otherwise strictly
115	equivalent to:	475	equivalent to:
116		476
117	BDB::AIO::poll_wait, BDB::AIO::poll_cb	477	BDB::poll_wait, BDB::poll_cb
118		478
119	BDB::AIO::flush	479	BDB::flush
120	Wait till all outstanding AIO requests have been handled.	480	Wait till all outstanding BDB requests have been handled.
121		481
122	Strictly equivalent to:	482	Strictly equivalent to:
123		483
124	BDB::AIO::poll_wait, BDB::AIO::poll_cb	484	BDB::poll_wait, BDB::poll_cb
125	while BDB::AIO::nreqs;	485	while BDB::nreqs;
126		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
127	CONTROLLING THE NUMBER OF THREADS	527	CONTROLLING THE NUMBER OF THREADS
128	BDB::AIO::min_parallel $nthreads	528	BDB::min_parallel $nthreads
129	Set the minimum number of AIO threads to $nthreads. The current	529	Set the minimum number of BDB threads to $nthreads. The current
130	default is 8, which means eight asynchronous operations can execute	530	default is 8, which means eight asynchronous operations can execute
131	concurrently at any one time (the number of outstanding requests,	531	concurrently at any one time (the number of outstanding requests,
132	however, is unlimited).	532	however, is unlimited).
133		533
134	BDB::AIO starts threads only on demand, when an AIO request is	534	BDB starts threads only on demand, when an BDB request is queued and
135	queued and no free thread exists. Please note that queueing up a	535	no free thread exists. Please note that queueing up a hundred
136	hundred requests can create demand for a hundred threads, even if it	536	requests can create demand for a hundred threads, even if it turns
137	turns out that everything is in the cache and could have been	537	out that everything is in the cache and could have been processed
138	processed faster by a single thread.	538	faster by a single thread.
139		539
140	It is recommended to keep the number of threads relatively low, as	540	It is recommended to keep the number of threads relatively low, as
141	some Linux kernel versions will scale negatively with the number of	541	some Linux kernel versions will scale negatively with the number of
142	threads (higher parallelity => MUCH higher latency). With current	542	threads (higher parallelity => MUCH higher latency). With current
143	Linux 2.6 versions, 4-32 threads should be fine.	543	Linux 2.6 versions, 4-32 threads should be fine.
144		544
145	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
146	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
147	load.	547	load.
148		548
149	BDB::AIO::max_parallel $nthreads	549	BDB::max_parallel $nthreads
150	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
151	the specified number of threads are currently running, this function	551	the specified number of threads are currently running, this function
152	kills them. This function blocks until the limit is reached.	552	kills them. This function blocks until the limit is reached.
153		553
154	While $nthreads are zero, aio requests get queued but not executed	554	While $nthreads are zero, aio requests get queued but not executed
155	until the number of threads has been increased again.	555	until the number of threads has been increased again.
…		…
158	ensure that all threads are killed and that there are no outstanding	558	ensure that all threads are killed and that there are no outstanding
159	requests.	559	requests.
160		560
161	Under normal circumstances you don't need to call this function.	561	Under normal circumstances you don't need to call this function.
162		562
163	BDB::AIO::max_idle $nthreads	563	BDB::max_idle $nthreads
164	Limit the number of threads (default: 4) that are allowed to idle	564	Limit the number of threads (default: 4) that are allowed to idle
165	(i.e., threads that did not get a request to process within 10	565	(i.e., threads that did not get a request to process within 10
166	seconds). That means if a thread becomes idle while $nthreads other	566	seconds). That means if a thread becomes idle while $nthreads other
167	threads are also idle, it will free its resources and exit.	567	threads are also idle, it will free its resources and exit.
168		568
…		…
173		573
174	The default is probably ok in most situations, especially if thread	574	The default is probably ok in most situations, especially if thread
175	creation is fast. If thread creation is very slow on your system you	575	creation is fast. If thread creation is very slow on your system you
176	might want to use larger values.	576	might want to use larger values.
177		577
178	$oldmaxreqs = BDB::AIO::max_outstanding $maxreqs	578	$oldmaxreqs = BDB::max_outstanding $maxreqs
179	This is a very bad function to use in interactive programs because	579	This is a very bad function to use in interactive programs because
180	it blocks, and a bad way to reduce concurrency because it is	580	it blocks, and a bad way to reduce concurrency because it is
181	inexact: Better use an "aio_group" together with a feed callback.	581	inexact: Better use an "aio_group" together with a feed callback.
182		582
183	Sets the maximum number of outstanding requests to $nreqs. If you to	583	Sets the maximum number of outstanding requests to $nreqs. If you to
…		…
191	You can still queue as many requests as you want. Therefore,	591	You can still queue as many requests as you want. Therefore,
192	"max_oustsanding" is mainly useful in simple scripts (with low	592	"max_oustsanding" is mainly useful in simple scripts (with low
193	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
194	(with large values).	594	(with large values).
195		595
		596	$old_cb = BDB::set_sync_prepare $cb
		597	Sets a callback that is called whenever a request is created without
		598	an explicit callback. It has to return two code references. The
		599	first is used as the request callback (it should save the return
		600	status), and the second is called to wait until the first callback
		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:
		609
		610	sub {
		611	my $status;
		612	(
		613	sub { $status = $! },
		614	sub { BDB::poll while !defined $status; $! = $status },
		615	)
		616	}
		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
196	STATISTICAL INFORMATION	626	STATISTICAL INFORMATION
197	BDB::AIO::nreqs	627	BDB::nreqs
198	Returns the number of requests currently in the ready, execute or	628	Returns the number of requests currently in the ready, execute or
199	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
200	yet).	630	yet).
201		631
202	Example: wait till there are no outstanding requests anymore:	632	Example: wait till there are no outstanding requests anymore:
203		633
204	BDB::AIO::poll_wait, BDB::AIO::poll_cb	634	BDB::poll_wait, BDB::poll_cb
205	while BDB::AIO::nreqs;	635	while BDB::nreqs;
206		636
207	BDB::AIO::nready	637	BDB::nready
208	Returns the number of requests currently in the ready state (not yet	638	Returns the number of requests currently in the ready state (not yet
209	executed).	639	executed).
210		640
211	BDB::AIO::npending	641	BDB::npending
212	Returns the number of requests currently in the pending state	642	Returns the number of requests currently in the pending state
213	(executed, but not yet processed by poll_cb).	643	(executed, but not yet processed by poll_cb).
214		644
		645	COMMON 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
215	FORK BEHAVIOUR	665	FORK BEHAVIOUR
216	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:
217		667
218	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
219	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
220	fork the parent simply leaves the quiescent state and continues	670	the parent simply leaves the quiescent state and continues
221	request/result processing, while the child frees the request/result	671	request/result processing, while the child frees the request/result
222	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
223	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
224	the parent process has been reached again.	674	the parent process has been reached again.
225		675
226	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
227	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
228	used yet.	678	yet.
229		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
230	MEMORY USAGE	684	MEMORY USAGE
231	Per-request usage:	685	Per-request usage:
232		686
233	Each aio request uses - depending on your architecture - around 100-200	687	Each aio request uses - depending on your architecture - around 100-200
234	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
235	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
236	scalars and other data passed into aio requests will also be locked and	690	scalars and other data passed into aio requests will also be locked and
237	will consume memory till the request has entered the done state.	691	will consume memory till the request has entered the done state.
238		692
239	This is now awfully much, so queuing lots of requests is not usually a	693	This is not awfully much, so queuing lots of requests is not usually a
240	problem.	694	problem.
241		695
242	Per-thread usage:	696	Per-thread usage:
243		697
244	In the execution phase, some aio requests require more memory for	698	In the execution phase, some aio requests require more memory for
245	temporary buffers, and each thread requires a stack and other data	699	temporary buffers, and each thread requires a stack and other data
246	structures (usually around 16k-128k, depending on the OS).	700	structures (usually around 16k-128k, depending on the OS).
247		701
		702	WIN32 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
248	KNOWN BUGS	710	KNOWN BUGS
249	Known bugs will be fixed in the next release.	711	Known bugs will be fixed in the next release, except:
		712
		713	If you use a transaction in any request, and the request returns
		714	with an operating system error or DB_LOCK_NOTGRANTED, the internal
		715	TXN_DEADLOCK flag will be set on the transaction. See C<db_txn_finish>,
		716	above.
250		717
251	SEE ALSO	718	SEE ALSO
252	Coro::AIO.	719	AnyEvent::BDB (event loop integration), Coro::BDB (more natural syntax),
		720	IO::AIO (nice to have).
253		721
254	AUTHOR	722	AUTHOR
255	Marc Lehmann <schmorp@schmorp.de>	723	Marc Lehmann <schmorp@schmorp.de>
256	http://home.schmorp.de/	724	http://home.schmorp.de/
257		725

Diff Legend

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

Comparing BDB/README (file contents): Revision 1.1 by root, Mon Feb 5 18:40:55 2007 UTC vs. Revision 1.15 by root, Sun Jan 11 00:56:09 2009 UTC

Diff Legend

Comparing BDB/README (file contents):
Revision 1.1 by root, Mon Feb 5 18:40:55 2007 UTC vs.
Revision 1.15 by root, Sun Jan 11 00:56:09 2009 UTC