Collection Berkeley DB Articles Collection-Environment API

BerkeleyDB Environment APIOverview:
The BERKELEYDB environment is the encapsulation of one or several databases, including log file and region file. Region file is the shared memory area that contains the cache page information for the memory pool. Portability: Since only the database file is a word order independent (Byte-order independent), only it can be ported between machines of different byte sequences. Log file can only be ported between machines that are in the same word sequence. The region file can only be ported between the same machines and the operating system version is required.

The so-called byte order, is the structure of the CPU problem, including: Littel-endian and Big-endian, which is the legendary small head problem. The average CPU is a small head, which means that the high byte first, the opposite network is the big one, the lower byte first. The small head of the machine 0x23ab on the network for the 0xab23, so we in the socket communication, there are htonl () a class of functions.

Here's an easy way to manage the BDB environment: Create a separate home path for the environment files of the application that will be shared, the path is defined by the user, and the BDB application will find it according to the path name. DBD is often shared by several different processes or threads. An environment can contain resources from different paths of the same system, and programs often allocate resources for other paths for execution or other reasons. In general, however, library files, shared region, and log file will be stored in different folders under a path.

All programs that share a DB environment trust each other by default, and they can access each other's data as they would access a shared region, and they also share buffer space and locks. Several programs that contain consistency must share the same environment in order to operate on a single library at the same time.

Common functions:
Operation function of database environment
1. int db_env_create (db_env **DBENVP, u_int32_t flags);
Creates an environment handle. The parameter 1 is the address of the BDB environment handle, including the database, log file, and cache (caching), lock (locking), log (logging), Event (transaction) subsystem. The method of managing the system environment contained in a handle also manages subsystems and databases. Parameter 2 creates a client-side environment when using db_rpcclient, and is a local environment for 0.

2. int Db_env->open (db_env *dbenv, char *db_home, u_int32_t flags, int mode);
Open an environment. Parameter 2 is the home path for the environment, and the relative paths used by all functions later are based on that path. Specifies that the path has several other methods: Specify the DB_HOME environment variable, use Db_home in the function, write Db_config file, and specify the path for the environment-related files using the Db_env->set_data_dir series function. When using this method, remember to add Db_use_environ or db_use_environ_root to the flags. Parameter mode is used in the Linux system, such as: 660, 664, and so on.
The parameters flags are many, and when using multiple flags, press the bit and "|". Roughly divided into four categories:
First, enable the subsystems of the logo
Db_init_cdb
Initializes the lock mechanism for the concurrent data store (concurrent data store). Multiple users read a single user write.
Db_init_lock
Enable the lock subsystem. When multiple processes/threads read and write to the database at the same time, let them not interfere. If all threads are simply reading the database, it is not necessary to enable it. When the lock subsystem is enabled, it is often necessary to enable a deadlock detector (deadlock detector), which is db_env->lock_detect.
Db_init_log
Enable the log subsystem to recover the impact of a program or system failure. If the log file already exists or is created, subsequent logs are added directly to the back of the previous log, rather than overridden.
Db_init_mpool
Enable the shared memory cache pool system. Note: This flag is to be used regardless of any circumstances.
Db_init_rep
Enable the backup (replication) subsystem. At the very least, db_init_txn and db_init_lock should be used at the same time, not to mention the Db_init_mpool logo.
Db_init_txn
Enable the event subsystem. This subsystem needs to be enabled when atomic multiple operations are important and are restored. Enabling this subsystem already contains the Db_init_log enabled.
Second, the decision to restore some of the signs of the system initialization
Db_recover
Perform a general recovery in the environment before you open the environment. Because the regions will be deleted and rebuilt, the application recovery requires the event subsystem, so the db_create and DB_INIT_TXN flags should be enabled simultaneously. Even if there is no need to recover, setting the flag will not have any adverse effects.
Db_recover_fatal
Disaster recovery within the environment before you open the environment, and db_create and DB_INIT_TXN need to be enabled for the same reasons as above.
Note: All DBD recovery processes must be single-threaded, that is, when the action is resumed, only individual threads are allowed to recover or access the environment. BDB document recommended, in the open environment, the logo db_create, Db_recover always place. Note: When Db_recover_fatal or Db_recover is enabled, but the log file does not exist, Db_env->open still returns 0, so it is necessary to determine the existence of the required log file before resuming operations. If you need more information about the recovery operation, please refer to db_archive and db_recover.
Third, using the specified environment path extension function related flags
Db_use_environ
The bdb file name extension function is useful when the flag is used.
Db_use_environ_root
With this flag, some of the environment-related file paths specified by the dbd file naming extension function are accessible only by root.
Iv. some other signs
Db_create
Allow subsystems of the BDB environment to create any files that are necessary to create.
Db_lockdown
Lock the shared DBD environment file and the database mapped to memory.
Db_private
Allocate region space in the heap, not in the system's shared memory or in the standby memory of the file system. The environment in which the flag is used all relevant data will be allocated space in the memory area of the respective process, and the mutex exists only between threads. So the environment allows only single process operations at this time, but multithreading is allowed.
Db_register
Check if the process is using the environment with errors. If a recovery operation (recovery) is required for some reason, but db_recover and other related flags are not set, then Db_env->open returns the Db_runrecovery error number.
Db_system_mem
Allocate region space in the shared memory area instead of allocating it in the file system standby memory or heap. The Shared Memory Regions section of the reference document.
Db_thread
Allows the address space to be kind of multi-threaded concurrency.

3. int Db_env->close (db_env *dbenv, u_int32_t flags);
Turn off the environment and all of its subsystem handles while releasing all allocated memory resources. The environment handle should be closed after the other handles in the environment (DB, DBC, Db_txn, DB_LOGC, and Db_mpoolfile) are closed. The database information contained in Parameter 1 is discarded when closing, and the argument 2 is typically 0.
If a process lock (Db_init_lock) is enabled when Db_env->open (), shutting down the environment does not release the still-functioning process lock, and the user can invoke the Db_env->lock_vec to handle it; If the Db_init_ is enabled Mpool, the shutdown will shut down all open memory pool files (call Db_mpoolfile->close), but will not handle synchronization problems (Db_mpoolfile->sync), and if DB_INIT_TXN is enabled, The shutdown ignores all unhandled events, but note that this is an error in itself if there is an unhandled event, if the log cursor is invoked (Db_env->log_cursor) and is not closed, you need to handle it yourself.
The operation successfully returned 0, but even if the operation is unsuccessful, the environment handle has not been properly accessed.

4. int Db_env->remove (db_env *dbenv, char *db_home, u_int32_t flags);
Destroy the currently unused environment. All associated backup files and environment areas are deleted, while log files, database files, and environment paths remain. If the current environment is still in use, you need to specify the db_env->force flag, and all processes that have entered the environment will run as usual, but new actions to join the environment will fail. In general, the environment will be purged as the database recovery operation is not necessary. However, when Db_system_mem is turned on when the environment is opened, the function needs to be called to release the allocated shared memory segment, and the system resources allocated by the mutex structure need to be called to release the function. In a multithreaded operation, only one thread is allowed to do this operation.
Db_home is used to specify the path of the destroyed environment, if parameter 3 is Db_use_environ or db_use_environ_root, the environment path is named with BDB File naming, and Parameter 3 is db_force only if the application has no Occurs when the method closes or a deadlock occurs.

5. int Db_env->dbremove (db_env *dbenv, Db_txn *txnid, const char *file, const char *database, u_int32_t flags);
If the database is not specified, delete information about all the subsystems associated with file in the environment and the contents of all the databases in the file, and if specified, delete only subsystem information and the contents of that database in the specified file. The database in the open environment handle cannot be easily deleted with Db->remove because the environment has write protection to the database at this time.
If the action is part of a specified application event, parameter 2 is an event handle, otherwise null. The parameter flag can be either 0 or db_auto_commit, which causes the operation to be handled by the event subsystem, which makes the operation recoverable. When flag is db_auto_commit and parameter 2 is NULL, the event system writes protection to the action, and the operation is invalid.

6. int Db_env->dbrename (db_env *dbenv, Db_txn *txnid, const char *file,
const char *database, const char *newname, u_int32_t flags);
Rename a database. The matters that should be noted and the significance of the parameters are similar to Db_env->dbremove.

7. int Db_env->get_home (db_env *dbenv, const char **HOMEP);
The main path to the environment is stored in the address HOMEP points to, which can be invoked at any time.

8. int Db_env->get_open_flags (db_env *dbenv, u_int32_t *flagsp);
Gets the flag to use when opening the environment. This function is used after the environment is opened.

9. int Db_env->fileid_reset (db_env *dbenv, const char *file, u_int32_t flags);
Modify the file ID, which allows the database file to be replicated in the environment and then used instead of the original file. You can call the function at any time the program executes, but be aware that the operation is not available for all physical files currently being used.
In the database environment cache, all libraries contain an ID string that uniquely flags the library. If the physical database file is replicated, the same ID string is used as the new file in the same environment as the original file, which results in data decay. This operation creates a new ID string for all tables in the physical file. The parameter file is the physical file name of the new ID string to be created; The parameter flags is 0 or db_encrypt (indicates that the file has been encrypted).

Db_env->lsn_reset Int (db_env *dbenv, const char *file, u_int32_t flags);
This action modifies the LSN of the database, which allows the database file to be moved from one event database environment to another, and you can call the function at any time the program executes, but note that the function cannot modify the LSN of the database in use.
Database pages in an event database environment contain references to the environment log files (Lsn--log sequence numbers), copying or moving database files from one environment to another and then modifying them, resulting in corrupt data if no LSN are cleaned up Corruption). Resetting the LSN should precede the operation of copying or moving the database. When the LSN is still associated with the old environment, the call to the function triggers the consistency check (consistency checks).
The parameter file is the physical path of the file to which LSN will be purged. The parameter flags can be 0 or db_encrypt.

int Db_env->dbenv_failchk (db_env *dbenv, u_int32_t flags);
This function checks whether a thread or process caused a pending lock because it exited while the database operation was in progress, or that a pending event caused an error in the event subsystem. The invocation of the operation is based on db_env->set_thread_id or db_env->set_isalive.
If you call the function to detect a deadlock or pending event, the operation will release the lock or ignore the pending events, and will report the process, thread number associated with this released lock or ignored event, and the relevant information will be printed to a specific output channel (db_env->set_ Msgfile) or a callback function (db_env-> Set_msgcall) passed to an application.
When the operation detects that an exiting thread is required for environmental recovery, it returns Db_runrecovery, which is no longer suitable for use.
This function needs to be used after Db_env->open is invoked. Parameter flags are generally 0.

Second, the Environment configuration function
1. int Db_env->set_alloc (db_env *dbenv, void * (*app_malloc) (size_t),
void * (*app_realloc) (void *, size_t), Void (*app_free) (void *));
Allocates and frees memory functions for the environment used by the program. BDB There are many interfaces that are allocated memory space by the link library to the program, such as the flags parameter in the DBT structure can be db_dbt_malloc or db_dbt_realloc, and many statistic functions such as BDB, such as: Db->stat, DB_ENV-&G T;lock_stat, Db_env->log_archive, Db_env->log_stat, Db_env->memp_stat and Db_env->txn_stat In addition, there is only one case where the program allocates memory space to the link library: Db-> associate. However, because the version of the link library may be different (mainly in WIN NT), we call this function to avoid this problem.
You do not have to specify a correlation function for all 3 callback function arguments. But the function you specify will be used in conjunction with the link library function, and the function you specify must conform to the ANSI C x3.159-1989 invocation rules based on compatibility with the standard link library interface. When the environment is open, use this function to return