BerkeleyDB环境API (转载)
source: http://blog.sina.com.cn/u/1210195593
转自:http://www.cnblogs.com/huqingyu/archive/2006/10/06/522250.html
熬了两天,终于把这该死的环境API给翻译出来了,不知道质量如何,这里给贴出来,各位大牛给看看什么地方有错。
本来翻译这玩意的目的是为了给自己一个对BDB环境使用的大局观,可是现在看来作用并不是很明显,这该死的玩意太多需要细细揣摩的地方了,要在工程中使用,恐怕没有更熟练的掌握更大的工夫是有点难搞的。如果看客中有个中高手,请务必拉小弟一把,万分感谢!
好,现在正式贴上乌焦巴弓版环境API,可信度:70%,语句:勉强能懂。
概述:
berkeleydb的环境就是对一个或几个数据库的封装,包括log file和region file。region file就是包含了内存池cache页信息的共享内存区。可移植性:由于只有数据库文件是字序独立的(byte-order independent),所以只有它可以在不同字节序的机器间互相移植。log file则只能在字序一致的机器间移植。而region file甚至只能在相同的机器间移植,还对操作系统的版本都有要求。
所谓byte order,是CPU的架构问题,包括:littel-endian和big-endian,也就是传说中的小头大头问题。一般的CPU都是小头的,也就是说高字节在先;相反网络就是大头,低字节在先。小头的机器上0x23AB在网络上就为0xAB23,所以我们在socket通讯时,就有htonl() 一类的函数了。
这里有一个管理bdb环境的简单方法:为将要共享环境的应用程序的环境文件创建一个单独的home路径,这个路径是用户自己定义的,bdb的应用程序根据路径名来找它。dbd常被几个不同的进程或线程共享。环境可以包含来自同一系统不同路径的资源,程序常常由于执行或其他原因为其他路径分配资源。但一般情况下,库文件、共享region以及log file将被存储在一个路径下面的不同文件夹。
所有共享一个db环境的程序默认是相互信任的,他们可以象访问共享region一样访问彼此的数据,他们还共享着buffer空间及locks。几个包含一致性的程序必须共享着相同的环境才能同时对一个库进行操作。
常用函数:
一、数据库环境操作函数
1. int db_env_create(DB_ENV **dbenvp, u_int32_t flags);
创建环境句柄。参1为bdb环境句柄的地址,包含了数据库、日志(log file)以及缓存(caching)、锁(locking)、日志(logging)、事件(transaction)子系统。句柄中包含的管理系统环境的方法同时也管理着子系统和数据库。参2在使用DB_RPCCLIENT时创建的是一个客户端(client)环境,为0时为本地的环境.
2. int DB_ENV->open(DB_ENV *dbenv, char *db_home, u_int32_t flags, int mode);
打开一个环境。参2为该环境的home路径,以后所有函数使用的相对路径均是以该路径为基础。指定该路径有其他几种方法:指定DB_HOME的环境变量,在该函数中使用DB_HOME;写DB_CONFIG文件;使用DB_ENV->set_data_dir系列函数为环境相关的文件指定路径,使用这种方法的时候要记得把DB_USE_ENVIRON或者DB_USE_ENVIRON_ROOT加入flags。参数mode使用方法参见linux系统中权限表示,比如:660,664等。
参数flags可多了,使用多个标志时请按位与"|"。大致分为四类:
一、启用各子系统的标志
DB_INIT_CDB
为并发数据存储(concurrent data store)初始化锁机制。多用户读单用户写。
DB_INIT_LOCK
启用锁子系统。当多进程/线程同时读写数据库时,让他们互不干扰。若所有线程都只是读数据库,没必要启用。启用了锁子系统时,通常需要启用一个死锁探测器(deadlock detector),该函数为DB_ENV->lock_detect。
DB_INIT_LOG
启用日志子系统以恢复因程序或系统失败产生的影响。如果日志文件已经存在或被创建,以后的日志会直接添加在以前日志的后面,而不是重写。
DB_INIT_MPOOL
启用共享内存缓存池子系统。注意:这个标志是无论任何情况必须要用上的。
DB_INIT_REP
启用备份(replication)子系统。至少需要DB_INIT_TXN、DB_INIT_LOCK与之同时使用,DB_INIT_MPOOL标志就更不用说了。
DB_INIT_TXN
启用事件子系统。当原子多重操作很重要以及恢复的时候,该子系统需要启用。启用该子系统已经包含了DB_INIT_LOG的启用。
二、决定在系统初始化的时候恢复些什么的标志
DB_RECOVER
在打开环境之前在环境里进行一般性的恢复。由于regions将被删除并重建,应用程序的恢复需要事件子系统,所以DB_CREATE及DB_INIT_TXN标志应该同时启用。就算没有恢复的必要,设置该标志也不会产生什么不良影响。
DB_RECOVER_FATAL
在打开环境之前在该环境内进行灾难恢复,基于与上面相同的原因,DB_CREATE及DB_INIT_TXN需要同时启用。
注意:所有dbd的恢复进程必须是单线程的,也就是说,当进行恢复这个动作时,只允许单独的线程来恢复或访问该环境。bdb文档中推荐,在打开环境的时候,将标志DB_CREATE、DB_RECOVER一直置位。注意:在DB_RECOVER_FATAL或DB_RECOVER被启用,但日志文件不存在时,DB_ENV->open仍然返回0,所以在进行恢复操作之前有必要确定一下需要的日志文件是否存在。如果你需要恢复操作的更多信息,请参考 db_archive以及db_recover.
三、使用指定环境路径的扩展函数相关标志
DB_USE_ENVIRON
使用该标志后,bdb文件命名扩展函数才有用。
DB_USE_ENVIRON_ROOT
使用该标志后,dbd文件命名扩展函数指定的与环境相关的一些文件路径只有root权限才可以访问。
四、一些其他的标志
DB_CREATE
允许bdb环境的子系统创建任何有必要创建的文件。
DB_LOCKDOWN
锁住共享的dbd环境文件以及映射到内存的数据库。
DB_PRIVATE
在堆中分配region空间,而不是在系统共享内存或文件系统的备用内存中。用了该标志的环境种所有相关数据都将在各自进程的内存区域分配空间,互斥只存在于各个线程之间。所以环境此时只允许单进程操作,但允许多线程。
DB_REGISTER
检查进程使用环境时是否出错。如果由于某种原因需要进行恢复操作(recovery),但DB_RECOVER等相关的标志未被置位,那么DB_ENV->open将返回DB_RUNRECOVERY的错误号。
DB_SYSTEM_MEM
在共享内存区中分配region空间,而不是在文件系统备用内存或者堆中分配。参考文档中Shared Memory Regions一节。
DB_THREAD
允许地址空间种多线程并发。
3. int DB_ENV->close(DB_ENV *dbenv, u_int32_t flags);
关掉环境及其所有子系统句柄,同时释放掉所有分配的内存资源。环境句柄应该在环境中其他句柄(DB, DBC, DB_TXN, DB_LOGC以及DB_MPOOLFILE)都关闭以后再关闭。关闭时将丢弃参1中包含的数据库信息,参数2一般为0。
如果DB_ENV->open()的时候启用了进程锁(DB_INIT_LOCK),关闭环境操作并不会去释放仍然作用着的进程锁,用户可以调用 DB_ENV->lock_vec去处理;若启用了DB_INIT_MPOOL,关闭操作会将打开的内存池文件全部关闭(调用 DB_MPOOLFILE->close),但不会处理同步问题(DB_MPOOLFILE->sync);若启用了 DB_INIT_TXN,关闭操作将忽略所有未处理事件,但要注意:关闭操作进行时,如果还存在未处理事件,这本身就是一个错误;如果log游标被调用 (DB_ENV->log_cursor)且尚未关闭,你需要自己处理。
操作成功返回0,但是就算操作不成功,该环境句柄已经无法正常访问。
4. int DB_ENV->remove(DB_ENV *dbenv, char *db_home, u_int32_t flags);
销毁当前不用的环境。所有与之相关的备份文件及环境区域被删除,而日志文件、数据库文件及环境路径仍然保留。若当前环境仍然在使用,需指定DB_ENV- >FORCE标志,所有已经进入该环境区域的进程将照常运行,但新加入该环境的动作将失败。一般情况下,环境将随着数据库恢复的操作被清除,该函数并没有必要。但当打开该环境时启用了DB_SYSTEM_MEM,需要调用该函数释放掉被分配的共享内存段;另外,互斥结构被分配的系统资源也需要调用该函数来释放。在多线程操作中,只允许一个线程来进行该操作。
db_home用来指定被销毁环境的路径;若参数3为DB_USE_ENVIRON或DB_USE_ENVIRON_ROOT,说明环境路径使用了BDB File Naming来命名,参3为DB_FORCE的情况只在应用程序无法关闭或者出现死锁的时候出现。
5. int DB_ENV->dbremove(DB_ENV *dbenv, DB_TXN *txnid, const char *file, const char *database, u_int32_t flags);
若数据库没有指定,删除该环境下与file相关的所有子系统的信息以及该文件里所有数据库内容;若指定,则只删除与指定file内该database相关的子系统信息及该库内容。在打开的环境句柄中的数据库不能简单的用DB->remove来删除,因为此时环境对数据库具有写保护作用。
如果该操作是某指定应用程序事件的一部分,参数2为事件句柄,否则为NULL。参数flag可以为0或者DB_AUTO_COMMIT,后者使该操作由事件子系统来处理,这样就使得该操作具有了可恢复性。当flag为DB_AUTO_COMMIT,而参数2为NULL时,事件系统对该操作写保护,操作无效。
6. int DB_ENV->dbrename(DB_ENV *dbenv, DB_TXN *txnid, const char *file,
const char *database, const char *newname, u_int32_t flags);
给某数据库重命名。应该注意的事项以及参数意义与DB_ENV->dbremove相仿。
7. int DB_ENV->get_home(DB_ENV *dbenv, const char **homep);
得到环境的主路径,存入homep指向的地址中,该函数可以在任何时候调用。
8. int DB_ENV->get_open_flags(DB_ENV *dbenv, u_int32_t *flagsp);
得到打开环境时用的标志。该函数在环境打开后使用。
9. int DB_ENV->fileid_reset(DB_ENV *dbenv, const char *file, u_int32_t flags);
修改文件id,该操作将允许在环境中复制数据库文件,然后替代原文件使用。你可以在程序执行的任何时候调用该函数,但要注意:所有当前正被使用的物理文件不能使用该操作。
在数据库环境缓存中,所有的库都含有唯一标志该库的ID串。如果物理数据库文件被复制后,却在相同的环境中作为新的文件与原文件使用相同的ID串,这就产生了数据腐烂。本操作为物理文件中的所有表创建新的ID串。参数file为将被创建新ID串的物理文件名;参数flags为0或DB_ENCRYPT(表示该文件进行过加密操作)。
10. int DB_ENV->lsn_reset(DB_ENV *dbenv, const char *file, u_int32_t flags);
该操作修改数据库的LSN,这将允许数据库文件从一个事件数据库环境移动到另外一个,你可以在程序执行的任何时候调用该函数,但要注意:该函数不能修改使用中的数据库的LSN。
事件数据库环境中的数据库页包含着对环境日志文件的引用(LSN--log sequence numbers),将数据库文件从一个环境复制或移动到另一个环境然后修改的操作,如果没有对LSN进行清理,将导致数据的腐烂(data corruption)。对LSN的重设应该先于复制或移动数据库的操作。当LSN仍然与老的环境相关联的时候,该函数的调用将触发一致性检查 (consistency checks)。
参数file为LSN将被清除的文件的物理路径。参数flags可以为0或者DB_ENCRYPT。
11. int DB_ENV->dbenv_failchk(DB_ENV *dbenv, u_int32_t flags);
该函数检查某线程或进程是否由于在对数据库操作时退出而造成了未决锁,或者有未决事件导致事件子系统出错。该操作的调用基于DB_ENV->set_thread_id或者DB_ENV->set_isalive。
如果调用该函数检测到确实存在死锁或者未决事件,那么该操作将释放掉该锁或将未决事件忽略,还将报告与此被释放掉的锁或忽略掉的事件相关的进程、线程号,相关信息将被打印到特定的输出渠道(DB_ENV->set_msgfile)或传给某应用程序的回调函数(DB_ENV-> set_msgcall)。
当该操作检测到退出的线程是环境恢复需要的,将返回DB_RUNRECOVERY,此时该环境已经不适合使用。
该函数需在DB_ENV->open被调用之后使用。参数flags一般都为0。
其他4个统计用函数省略,到需要的时候再查手册。
二、环境配置函数
1. int DB_ENV->set_alloc(DB_ENV *dbenv, void *(*app_malloc)(size_t),
void *(*app_realloc)(void *, size_t), void (*app_free)(void *));
为被程序使用的环境设置分配、释放内存函数。BDB有许多由链接库为程序分配内存空间的接口,比如DBT结构中的flags参数可以为 DB_DBT_MALLOC或DB_DBT_REALLOC,再如BDB的许多统计信息函数,如:DB->stat, DB_ENV->lock_stat, DB_ENV->log_archive, DB_ENV->log_stat, DB_ENV->memp_stat以及DB_ENV->txn_stat;另外由程序为链接库分配内存空间的情况只有一种:DB-> associate。但由于链接库的版本可能存在区别(主要是在WIN NT里),所以我们调用该函数来避免这个问题。
你不必为所有3个回调函数参数指定相关函数。但你指定的函数将与链接库函数一起使用,基于与标准链接库接口的兼容性考虑,你指定的函数须遵从ANSI C X3.159-1989的调用规则。环境打开后,使用该函数将返回EINVAL错误。
2. int DB_ENV->set_app_dispatch(DB_ENV *dbenv,
int (*tx_recover)(DB_ENV *dbenv, DBT *log_rec, DB_LSN *lsn, db_recops op));
为当事件失败(abort),恢复程序指定的日志记录的动作指定回调函数。该函数应在环境打开之前调用,否则可能由于与环境的不一致性产生数据腐烂。
回调函数参数tx_recover的参数:log_rec为一个日志记录,lsn为日志序列号,op可以为以下几个标志之一:
DB_TXN_BACKWARD_ROLL
由被读回的日志来判断哪个事件被触发以及终止未完成的操作,并消除(undo)日志记录描述的操作。
DB_TXN_FORWARD_ROLL
重做(redo)由日志记录描述的操作。
DB_TXN_ABORT
当一个事件终止(abort)时读回日志,消除日志记录描述的操作。
DB_TXN_APPLY
日志被用到一个复制地址,重做日志记录描述的操作。与DB_TXN_FORWARD_ROLL常常表示相同操作。
DB_TXN_PRINT
日志记录以需要的格式被打印出来供调试用。
3. int DB_ENV->set_cachesize(DB_ENV *dbenv, u_int32_t gbytes, u_int32_t bytes, int ncache);
设置共享内存池空间大小,也就是缓存(cache)。该缓存的大小应该为程序一般性工作数据设置大小加上少量为异常事件准备的附加内存。注意:工作空间设置比并发内存页入口(pages accessed simultaneously)要大得多。
默认的cache大小为256K,设置时至少要为20K。所有小于500M的缓存将自动增加1/4来计量内存池过载的情况,所有大于500M的缓存则根据其指定的大小。32位系统中最大缓存为4G,64位系统中最大则为10T。参数ncache如果为0或1,cache被分配在内存中连续的空间中,若大于 1,cache则被分配为ncache块相同大小的内存。数据库环境缓存大小也可以在环境的DB_CONFIG文件中配置。语法为:
set_cachesize 多少G 缓存附加空间多少位 缓存的块数
例如:在DB_CONFIG文件中写下以下一句将创建被分为3块的总共500M的cache空间:
set_cachesize 0 524288000 3
该函数应该在环境打开之前调用,如果环境已经打开,该函数将被忽略。
4. int DB_ENV->get_cachesize(DB_ENV *dbenv, u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
得到环境cache的信息。该函数在程序运行的任何时候都可以调用。
5. int DB_ENV->set_data_dir(DB_ENV *dbenv, const char *dir);
设置环境中数据库文件路径。DB->open调用的时候指定的路径将以该路径为基础。数据库路径将以第一个被指定的路径为准。如果该函数没有被调用,数据库路径就是环境的home目录。
同样,该路径的指定也可以在DB_COFIG中指定,格式为:
set_data_dir /usr/local/dbpath
该函数的调用应该在环境被打开之前,且需在DB_ENV->open中指定DB_USE_ENVIRON标志,set_data_dir函数指定的路径才起作用。
6. int DB_ENV->get_data_dirs(DB_ENV *dbenv, const char ***dirpp);
该函数返回路径数组,该数组最后一个成员不为NULL。该操作可在程序运行的任何时间调用,成功则返回0,失败返回非0值。
7. int DB_ENV->set_encrypt(DB_ENV *dbenv, const char *passwd, u_int32_t flags);
为BDB的库函数指定用来进行加密解密的口令(password)。该函数并非只是对指定的环境句柄操作进行配置,事实上它配置了整个数据库的环境。该操作应该在环境打开之前调用,如果调用时环境已经打开且与该环境没有保持同步,将返回一个错误。标志为0或DB_ENCRYPT_AES,后者表示使用 Rijndael/AES算法进行加密解密。
8. int DB_ENV->get_encrypt_flags(DB_ENV *dbenv, u_int32_t *flagsp);
得到加密标志,可以在程序运行的任何时间调用,成功返回0并将标志存储在flagsp指向的地址中,失败则返回非0值。
9. int DB_ENV->set_feedback(DB_ENV *dbenv, void (*db_feedback_fcn)(DB_ENV *dbenv, int opcode, int percent));
BDB的库函数的一些操作可能占用大量的时间,应用程序调用该函数来管理这些操作的进展。当一个操作可能占用很长时间时,BDB将调用该操作指定的回调函数来处理进程信息。该函数可以在程序运行的任意时间指定。成功返回0,失败返回非0值。
回调函数参数:
dbenv 某未关闭的环境句柄的引用。
opcode 为一操作码,可以是DB_RECOVER,表示环境被恢复。
percent 表示该操作已经完成了多少,可以为0到100。
10. int DB_ENV->set_flags(DB_ENV *dbenv, u_int32_t flags, int onoff);
配置数据库环境,该函数的作用也可以用DB_CONFIG文件来表现,为保持同步性,除非特别说明,这些标志要么用该函数设置,要么写入DB_CONFIG文件。参数onoff为0,取消标志;为1,设置标志。
参数flags可以为以下几个标志的中的几个,用"|"来连接。
DB_AUTO_COMMIT
该标志一旦被设置,事件句柄没有指定且修改了环境中数据库的操作将被自动与事件挂钩。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_CDB_ALLDB
该标志一旦被设置,BDB将针对整个数据库环境的并发存储操作上锁,而不是环境中单独的数据库。该标志可以在环境打开之前用set_flags导入环境配置。
DB_DIRECT_DB
关闭数据库文件的系统缓冲(buffering)以避免重复储藏(caching)。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_DIRECT_LOG
关闭数据库文件的的日志文件以避免重复储藏(caching)。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_DSYNC_DB
配置BDB,使之在从写系统调用返回之前刷新数据库写操作到备份磁盘,而不是明确的在单独的系统调用中刷新数据库写操作。该标志只在某些系统中有效(比如支持POSIX标准的O_DYNC标志的系统,支持Win32的FILE_FLAG_WRITE_THROUGH标志的系统),并且可能导致文件修改时间及其他一些文件级的信息不真确。在大多数系统中,该标志还导致运行效率的下降。所以,该标志只在有强壮的容错功能的文件系统中适用(比如Veritas VxFS文件系统)。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_DSYNC_LOG
配置BDB,使之在从写系统调用返回之前刷新日志写操作到备份磁盘,而不是明确的在单独的系统调用中刷新数据库日志写操作。该标志只在某些系统中有效(比如支持POSIX标准的O_DYNC标志的系统,支持Win32的FILE_FLAG_WRITE_THROUGH标志的系统),并且可能导致文件修改时间及其他一些文件级的信息不真确。该标志在有的系统导致运行效率的下降,有的却导致性能上升。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_LOG_AUTOREMOVE
该标志自动删除不再需要的日志文件,不过将导致灾难恢复(catastrophic recovery)变得不可能。用set_flags设置该标志将影响到对数据库环境进行操作的所有线程。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_LOG_INMEMORY
该标志使事件日志保留在内存而不是磁盘。这意味着事件支持ACI(atomicity,consistency,isolation)特性,而非D (durability),也就是说数据库的完整性(integrity)将被维护,但当程序或系统出错,该完整性不被保留,在这种情况下,所有的数据库文件必须从可靠的档案备份或replication group master进行恢复。用set_flags设置该标志将影响到对数据库环境进行操作的所有线程。该标志可以在环境打开之前导入环境配置。
当为日志分配的内存满的时候,BDB将返回一个附加错误号:DB_LOG_BUFFER_FULL。所以为内存日志配置大小时,程序应该确定其足够大,以避免某事件霸占整个日志的内存以及由于某事件一直在日志内存中活跃而导致该空间没有可释放的空间的情况。
DB_NOLOCKING
该标志允许所有互斥锁解除而不考虑他们的现实作用。注意:只能用于调试!该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境起句柄作用。
DB_NOMMAP
该标志将把只读的数据库拷贝到本地缓存中,而不是映射(mapping)到进程内存中。该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。
DB_NOPANIC
该标志将忽略掉数据库环境中所有的惊恐状态(panic state).注意:只能用于调试!该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。
DB_OVERWRITE
在删除之前重写(overwrite)以加密格式存储的文件。BDB交替使用0xFF,0x00以及0xFF字节的模式来重写文件。要使文件重写有效,文件必须存储在fixed-block文件系统中。带日志的系统及日志文件系统需要对BDB源文件进行修改。该标志可以在程序运行任何时期用 set_flags导入环境配置,只对指定的环境句柄起作用。
DB_PANIC_ENVIRONMENT
该标志将系统环境设置为恐慌状态,该状态下的环境会拒绝任何调用BDB函数的操作,并返回DB_RUNRECOVERY。该标志不能在DB_CONFIG 文件中配置,且会在环境打开之后起作用,但可以在程序运行的任何时期导入环境配置。对整个数据库环境,包括对其进行操作的线程起作用。
DB_REGION_INIT
该标志一旦设置,BDB将在创建或加入一个环境时,page-fault的共享区域到内存中;另外,BDB将在创建一个环境时写共享区域,强迫虚拟内存及文件系统举例说明必要的内存及磁盘空间;也避免了以后out-of-disk space错误。该标志可以在程序运行任何时期用set_flags导入环境配置。
DB_TIME_NOTGRANTED
该标志使基于时钟或事件超时值的数据库调用超时返回DB_LOCK_NOTGRANTED,以区别真正的死锁返回的DB_LOCK_DEADLOCK。该操作只对指定的环境句柄起作用。
DB_TXN_NOSYNC
BDB将不在事件触发(commit)日志或同步刷新日志。这意味着事件支持ACI(atomicity,consistency,isolation) 特性,而非D(durability),也就是说数据库的完整性(integrity)将被维护,但当程序或系统出错,一些最常触发的事件可能在恢复操作中被取消(undone)。风险事件的数目由多少日志更新与日志内存匹配,操作系统将脏文件刷新到磁盘,以及日志被检查的频率决定。该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。
DB_TXN_WRITE_NOSYNC
BDB将在事件触发时写但不同步刷新日志。这意味着事件支持ACI(atomicity,consistency,isolation)特性,而非D (durability),也就是说数据库的完整性(integrity)将被维护,但当程序或系统出错,一些最常触发的事件可能在恢复操作中被取消 (undone)。风险事件的数目由多少日志更新与日志内存匹配,操作系统将脏文件刷新到磁盘,以及日志被检查的频率决定。该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。
DB_YIELDCPU
BDB将在每个内存页或互斥体获得后立即产生处理。注意:该标志只是用来做压力测试(stress testing)。该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。
11. int DB_ENV->get_flags(DB_ENV *dbenv, u_int32_t *flagsp);
该函数可在程序运行的任何时期调用,返回环境配置标志位。
12. int DB_ENV->set_isalive(DB_ENV *dbenv, int (*is_alive)(DB_ENV *dbenv, pid_t pid, db_threadid_t tid));
声明一个判断线程、进程是否还在运行的函数。该标志可以在程序运行任何时期用set_flags导入环境配置,只对指定的环境句柄起作用。回调函数参数:
dbenv 环境句柄。
pid 由DB_ENV->set_thread_id函数指定的进程ID。
tid 由DB_ENV->set_thread_id函数指定的线程ID。
13. int DB_ENV->set_paniccall(DB_ENV *dbenv, void (*db_panic_fcn)(DB_ENV *dbenv, int errval));
当出现只能由BDB库关掉应用程序并进行恢复的情况,函数将返回DB_RUNRECOVERY。一般情况下,程序会简单的退出而不是把错误码返回。该函数指定当DB_RUNRECOVERY将被返回时调用的函数。该标志可以在程序运行任何时期用set_flags导入环境配置。
14. int DB_ENV->set_rpc_server(DB_ENV *dbenv, CLIENT *client, char *host,
long cl_timeout, long sv_timeout, u_int32_t flags);
建立数据库环境和远程进程通讯(RPC)服务器之间的联系。该函数被调用后,后来对BDB库接口的调用可能会返回或抛出包含了DB_NOSERVER, DB_NOSERVER_ID或者DB_NOSERVER_HOME的异常。只对指定的环境句柄起作用,而并不包含对库环境的相关操作。该函数不可在环境打开之后调用。
参数client:如果在函数中提供了客户端的路径,DBD就以之作为连接,并忽略host和cl_timeout参数。参数cl_timeout:指定客户端等待服务器的延时时间,为0时使用默认的延时时间;如果超时,将返回DB_NOSERVER。参数host指定了BDB服务器连接的host,以创建联络通道。参数flags为0。参数sv_timeout指定服务器允许客户端空闲的时间;一旦该延时达到,服务器将释放掉所有与该客户端相关的资源。此后该客户端连接服务器的尝试将返回DB_NOSERVER_ID,表示给了服务器一个无用的标志;注意:该值只是作为服务器的一个参考,服务器可以按自己的策略做出改动;如果该值为0,将使用默认的延时。
15. int DB_ENV->set_shm_key(DB_ENV *dbenv, long shm_key);
为在VxWorks或支持X/Open-style共享内存接口的系统内存中创建的BDB环境的共享内存区域指定一个基本段ID。提示:你在自己系统的shell下输入man 2 shmget,看是否支持。
这个基础的段ID将在BDB共享内存区域首次被创建时被用到。当一个新的共享内存区域被创建时,新的ID号将比该ID略大。比如说,基本ID为35,第一个被创建的共享内存区域的ID号就是35,而下一个将是36到40之间的某数。BDB环境只创建一个主的共享内存区域,而每一个环境支持的子系统将有自己附加的共享内存区域(比如锁,日志,内存池及事件),每一个附加内存池缓存也将获得附加共享内存区域。如果相同段ID号已存在,将移出该已存在的区域。
使用这种方式的好处有两个:其一,如果没有这个机制,无法得知应用程序是否使用相同的段ID号来创建不同的BDB环境。其二,就算每次使用相同的段ID号来创建环境,先前创建的段将被移出,而这些系统中的段将不会无限增长。
同样,你也可以用DB_CONFIG来配置这个基础段ID,格式如下:
set_shm_key ID号
只对指定的环境句柄起作用,而并不包含对库环境的相关操作。该函数不可在环境打开之后调用。若在环境打开之后调用该函数,可能由于不同步导致现存环境的数据腐烂。
16. int DB_ENV->get_shm_key(DB_ENV *dbenv, long *shm_keyp);
返回基本的段ID,该函数可以在程序运行的任何时期调用。
17. int DB_ENV->set_thread_id(DB_ENV *dbenv, int (*thread_id)(DB_ENV *dbenv, pid_t *pid, db_threadid_t *tid));
声明一个返回当前线程管理的特定pid/tid对的函数。只对指定的环境句柄起作用,而并不包含对库环境的相关操作,该函数可以在程序运行的任何时期调用。
回调函数参数:
pid 指向一个pid_t结构的供当前控制线程的进程ID返回的内存地址。
tid 指向一个db_threadid_t结构的供当前控制线程的进程ID返回的内存地址。
标准系统系统库供返回进程线程ID的调用非常多。但如果BDB程序是动态创建进程、线程,你得在分配特定ID的方面留点神。在大多数的线程系统中,进程\ 线程ID在该进程\线程退出之后马上可以重用,有这么一个情况:如果进程\线程已经退出,但DB_ENV->failchk尚未调用,这时创建新的进程\线程ID,而这个ID恰好重用了之前退出的线程\进程,这样可能会导致后来调用的DB_ENV->failchk无法正确判断之前退出的线程 \进程是否正确释放了所有BDB的资源。解决这个问题有两种方法:其一,禁止新的进程\线程在调用DB_ENV->failchk之前创建;其二,新创建的进程\线程不重用之前用过的pid/tid对。注意:为DB_ENV->set_isalive指定的is_alive函数必须与为该函数指定的thread_id函数兼容。某些系统可能不认db_threadid_t结构,出现这个问题请与客服联系。
如果没有为程序指定thread_id函数,POSIX线程将调用getpid()或者pthread_self,UI线程将调用getpid()及thr_self()函数。
18. int DB_ENV->set_thread_id_string(DB_ENV *dbenv, char *(*thread_id_string)(DB_ENV *dbenv,
pid_t pid, db_threadid_t tid, char *buf));
声明一个将pid/tid对格式化到调用方提供的buffer中的函数。只对指定的环境句柄起作用,而并不包含对库环境的相关操作。该函数可在程序运行的任何时期调用。回调函数参数:
pid 进程ID号。
tid 线程ID号。
buf 就是上面提到的buffer,至少有DB_THREADID_STRLEN大小的空间。
如果没有指定thread_id_string函数,默认会这样显示:"pid/tid"。
19. int DB_ENV->get_timeout(DB_ENV *dbenv, db_timeout_t *timeoutp, u_int32_t flag);
为数据库环境的锁/事件指定延时。延时计数只发生在锁的线程控制块或启用了死锁探测时,所以延时的正确设置决定于是否启用了死锁探测。这个延时值在以per-lock/per-transaction为根据的环境中可能无效。
该函数配置了整个数据库环境,而不止是环境句柄。该函数可在程序运行的任何时期调用。
20. int DB_ENV->set_tmp_dir(DB_ENV *dbenv, const char *dir);
为本地临时文件指定路径。临时文件的创建将以该路径为基础。临时文件可能很大,这决定与数据库的大小。
如果没有指定临时文件路径,以下几个路径将被按顺序检测,第一个被检测到的路径将被作为默认临时文件路径。
系统环境变量TMPDIR,TEMP,TMP,TempFolder;由GetTempPath接口函数(Windows)返回的路径; /var/tmp,/usr/tmp,/temp,/tmp。该函数只有在打开环境时指定了DB_USE_ENVIRON及 DB_USE_ENVIRON_ROOT标志才能使用。
同样,临时文件的路径也可以在DB_CONFIG文件中指定,格式如下:
set_tmp_dir /tmppath
该函数只是配置了环境句柄,而非整个数据库环境。该函数只能在环境打开之前调用,如果在环境之后调用,可能由于不一致性产生数据腐烂。
21. int DB_ENV->set_verbose(DB_ENV *dbenv, u_int32_t which, int onoff);
该函数可打开/关闭BDB指定的附加信息或调试信息。为了得到附加信息,需要为程序配置冗长(verbose)信息,具体请参考DB->set_errfile(未翻译)。onoff为0时,不输出附加信息;为非0时,输出附加信息。
数据库环境信息同样也可以用DB_CONFIG文件来配置,格式如下:
set_verbose DB_VERB_RECOVERY
该函数只是配置了环境句柄,而非整个数据库环境。该函数可在程序运行的任何时期调用。参数which为以下中的一个:
DB_VERB_DEADLOCK 启用死锁探测时显示附加信息。
DB_VERB_RECOVERY 进行恢复时显示附加信息。
DB_VERB_REGISTER 显示DB_ENV->open与DB_REGISTER标志相关的附加信息。
DB_VERB_REPLICATION 显示复制消息的附加信息。如需要得到调试复制程序的完整日志。你需要在编译BDB时启用--enable-diagnostic,还需调用DB_ENV->set_verbose。
DB_VERB_WAITSFOR 启用死锁探测时显示waits-for表。
22. int DB_ENV->get_verbose(DB_ENV *dbenv, u_int32_t which, int *onoffp);
由which得到哪个标志被置位或取消置位。该函数可以在程序运行期间任何时候调用。