+I)Berkeley DB: DbMpool::open[P

DbMpool::open





#include <db_cxx.h>

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





Description



The DbMpool::openPmethod copies a pointer, to the "memory pool" identified by the directoryBdir, into the memory location referenced by regionp.

HIf the dir pathname argument is NULL or the DB_MPOOL_PRIVATE flagFis 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.

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

[

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

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

DB_NOMMAP
Always copy files in this memory pool into the local cache instead of<mapping them into process memory (see the description of theemp_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 befree-threaded.


OAll 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 describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

'The memory pool subsystem is configuredEbased on the dbenv argument. It is expected that applicationsiwill use a single DbEnv object as the argument to all of thessubsystems in the Berkeley DB package. The fields of the DbEnv object*used by DbMpool::open are described below.pReferences to the DbEnv object are maintained by Berkeley DB, so itDis necessary that the object and memory it references be valid untilthe object is destroyed.mAny of the DbEnv fields that are not explicitly set will defaultto appropriate values.

oThe following fields in the DbEnv object may be initialized, using9the 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;
y
int db_verbose;
The error fields of the DbEnv behave as described for>DbEnv::appinit.g

size_t mp_mmapsize;
Files that are opened read-only in the pool (and that satisfy a few otherHcriteria) are, by default, mapped into the process address space insteadKof being copied into the local cache. This can result in better-than-usualIperformance, as available virtual memory is normally much larger than theJlocal cache, and page faults are faster than page copying on many systems.HHowever, in the presence of limited virtual memory it can cause resourceLstarvation, and in the presence of large databases, it can result in immenseKprocess sizes. If mp_mmapsize is non-zero, it specifies the maximumLfile size, in bytes, for a file to be mapped into the process address space.By default, it is set to 10Mb.b

size_t mp_size;
The suggested size of the shared memory buffer pool, i.e., the cache, inEbytes. This should be the size of the normal working data set of theDapplication, with some small amount of additional memory for unusualDsituations. (Note, the working set is not the same as the number ofGsimultaneously referenced pages, and should be quite a bit larger!) TheGdefault cache size is 128K bytes, and may not be specified as less than 20K bytes.

9For information on tuning the Berkeley DB cache size, seeASelecting 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

U

DB_HOME
If the dbenv argument to DbMpool::open was initialized usingiDbEnv::appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation ofthe dir argument.


Z

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




Errors

TIf a fatal error occurs in Berkeley DB, the DbMpool::open method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

The DbMpool::open&method may fail and throw an exceptionKfor 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 exceptionor return errnofor the following conditions:

R

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

EINVAL
An invalid flag value or parameter was specified.

mFThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.

t@A NULL pathname was specified without the DB_MPOOL_PRIVATE flag.

.The specified cache size was impossibly small.

r

i

Class

6DbMpool

g

See Also

s>DbMpool::close,DbMpool::open,JDbMpool::db_register,<DbMpool::stat,<DbMpool::sync,ADbMpool::tricklelandn@DbMpool::unlink.
r<<˙˙>.

HIf the dir pathname argument is NULL or the DB_MPOOL_PRIVATE flagFis set, any necessary temporary