#include <db_cxx.h>

static int
DbMpool::open(char *dir,
    u_int32_t flags, int mode, DbEnv *dbenv, DbMpool **regionp);

Description

The DbMpool::open method copies a pointer, to the "memory pool" identified by the directory dir, into the memory location referenced by regionp.

If the dir pathname argument is NULL or the DB_MPOOL_PRIVATE flag is set, any necessary temporary files are created as described for the DB_TMP_DIR value in Berkeley DB File Naming. Otherwise, the dir pathname argument is interpreted as described in Berkeley DB File Naming.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically OR'ing together one or more of the following values:

DB_CREATE

Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

DB_MPOOL_PRIVATE

Create a private MPOOL that is not shared with any other process (although it may be shared with other threads).

DB_NOMMAP

Always copy files in this memory pool into the local cache instead of mapping them into process memory (see the description of the mp_mmapsize field of the DbEnv object for further information).

DB_THREAD

Cause the m4_reg(DB_MPOOL) handle returned by DbMpool::open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

All files created by the memory pool subsystem (other than files created by the DbMpoolFile::open method, which are separately specified) are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)))). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

The memory pool subsystem is configured based on the dbenv argument. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the Berkeley DB package. The fields of the DbEnv object used by DbMpool::open are described below. References to the DbEnv object are maintained by Berkeley DB, so it is necessary that the object and memory it references be valid until the object is destroyed. Any of the DbEnv fields that are not explicitly set will default to appropriate values.

The following fields in the DbEnv object may be initialized, using the appropriate set method, before calling DbMpool::open:

void *(*db_errcall)(char *db_errpfx, char *buffer);

FILE *db_errfile;

const char *db_errpfx;

class ostream *db_error_stream;

int db_verbose;

The error fields of the DbEnv behave as described for DbEnv::appinit.

size_t mp_mmapsize;

Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. This can result in better-than-usual performance, as available virtual memory is normally much larger than the local cache, and page faults are faster than page copying on many systems. However, in the presence of limited virtual memory it can cause resource starvation, and in the presence of large databases, it can result in immense process sizes. If mp_mmapsize is non-zero, it specifies the maximum file size, in bytes, for a file to be mapped into the process address space. By default, it is set to 10Mb.

size_t mp_size;

The suggested size of the shared memory buffer pool, i.e., the cache, in bytes. This should be the size of the normal working data set of the application, with some small amount of additional memory for unusual situations. (Note, the working set is not the same as the number of simultaneously referenced pages, and should be quite a bit larger!) The default cache size is 128K bytes, and may not be specified as less than 20K bytes.

For information on tuning the Berkeley DB cache size, see Selecting a cache size.

The DbMpool::open method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Environment Variables

DB_HOME

If the dbenv argument to DbMpool::open was initialized using DbEnv::appinit the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir argument.

TMPDIR

If the dbenv argument to DbMpool::open was NULL or not initialized using DbEnv::appinit the environment variable TMPDIR may be used as the directory in which to create the memory pool, as described in DbMpool::open.

Errors

The DbMpool::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: DBmemp->pgin(3), DBmemp->pgout(3), abort(3), close(3), DbEnv::version, dbenv->db_paniccall(3), fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), DbLog::compare, DbLog::flush, lseek(3), malloc(3), memcmp(3), memcpy(3), DbMpool::close, DbMpool::unlink, memset(3), mmap(3), munmap(3), open(3), pread(3), pstat_getdynamic(3), pwrite(3), read(3), shmat(3), shmctl(3), shmdt(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), time(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3).

In addition, the DbMpool::open method may fail and throw an exception or return errno for the following conditions:

EAGAIN

The shared memory region was locked and (repeatedly) unavailable.

EINVAL

An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

A NULL pathname was specified without the DB_MPOOL_PRIVATE flag.

The specified cache size was impossibly small.

Class

See Also