DbEnv::set_memory_init()

#include <db_cxx.h>

int
DbEnv::set_memory_init(DB_MEM_CONFIG type, u_int32_t count); 

This method sets the number of objects to allocate and initialize for a specified structure when an environment is created. Doing this helps avoid memory contention after startup. Using this method is optional; failure to use this method causes BDB to allocate a minimal number of structures that will grow dynamically. These structures are all allocated from the main environment region. The amount of memory in this region can be set via the DbEnv::set_memory_max() method. If this method is not called then memory will be limited to the initial settings or by the (deprecated) set maximum interfaces.

The database environment's initialization may also be configured using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_memory_init", one or more whitespace characters, followed by the struct specification, more white space and the count to be allocated. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv::set_memory_init() method must be called prior to opening the database environment. It may be called as often as needed to set the different configurations.

Parameters

type

The type parameter must be set to one of the following:

  • DB_MEM_DATABASE

    Initialize the number of databases in the environment. This should include each on-disk database and each named in-memory database. If using replication, use the same value on all sites in the replication group.

  • DB_MEM_DATABASE_LENGTH

    Initialize the maximum combined length of a database's directory and name strings. For an on-disk database, the database name is the file parameter to the DbEnv::open() method. For a named in-memory database, the database name is the database parameter to the DbEnv::open() method. If using replication, use the same value on all sites in the replication group.

  • DB_MEM_EXTFILE_DATABASE

    Initialize the number of database files and subdatabases using external files. This value should include the number of database files that use external files but do not contain subdatabases. This value should also include the number of subdatabases that use external files. It should be set in addition to the DB_MEM_DATABASE value. If using replication, use the same value on all sites in the replication group.

    Here are some examples of database files with different characteristics and how each database file should affect these values:

    • Not using external files, no subdatabases: add 1 to DB_MEM_DATABASE.
    • Not using external files, three subdatabases: add 1 to DB_MEM_DATABASE.
    • Using external files, no subdatabases: add 1 to DB_MEM_DATABASE and add 1 to DB_MEM_EXTFILE_DATABASE.
    • Using external files, three subdatabases: add 1 to DB_MEM_DATABASE and add 3 to DB_MEM_EXTFILE_DATABASE.
  • DB_MEM_LOCK

    Initialize locks. A thread uses this structure to lock a page (or record for the QUEUE access method) and hold it to the end of a transaction.

  • DB_MEM_LOCKOBJECT

    Initialize lock objects. For each page (or record) which is locked in the system, a lock object will be allocated.

  • DB_MEM_LOCKER

    Initialize lockers. Each thread which is active in a transactional environment will use a locker structure either for each transaction which is active, or for each non-transactional cursor that is active.

  • DB_MEM_LOGID

    Initialize the log fileid structures. For each database handle which is opened for writing in a transactional environment, a log fileid structure is used.

  • DB_MEM_REP_SITE

    If using replication, initialize the maximum number of sites in the replication group. Use the same value on all sites in the replication group.

  • DB_MEM_TRANSACTION

    Initialize transaction structures. Each active transaction uses a transaction structure until it either commits or aborts.

    Note

    Currently transaction structures are not preallocated. This setting will be used to preallocate memory and objects related to transactions such as locker structures and mutexes.

  • DB_MEM_THREAD

    Initialize thread identification structures. If thread tracking is enabled then each active thread will use a structure. Note that since a thread does not signal the BDB library that it will no longer be making calls, unused structures may accumulate until a cleanup is triggered either using a high water mark or by running DbEnv::failchk() .

count

The count parameter sets the number of specified objects to initialize.

The count specified for locks and lock objects should be at least 5 times the number of lock table partitions. You can examine the current number of lock table partitions configured for your environment using the DbEnv::get_lk_partitions() method.

Errors

The DbEnv::set_memory_init() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

If the method was called after DbEnv::open() was called; or if an invalid flag value or parameter was specified.

Class

DbEnv

See Also

Database Environments and Related Methods