DbMpool
import com.sleepycat.db.*;
public static DbMpool open(String dir, int flags,
int mode, DbEnv dbenv)
throws DbException;
public void close()
throws DbException;
public static void unlink(String dir, int force, DbEnv dbenv)
throws DbException;
public void sync(DbLsn lsn)
throws DbException;
public DbMpoolStat stat()
throws DbException;
public DbMpoolFStat[] fstat()
throws DbException;
DESCRIPTION
The DB library is a family of classes that provides a
modular programming interface to transactions and record-
oriented file access. The library includes support for
transactions, locking, logging and file page caching, as
well as various indexed access methods. Many of the
classes (e.g., the file page caching class) are useful
independent of the other DB classes, although some classes
are explicitly based on other classes (e.g., transactions
and logging). For a general description of the DB
package, see db_intro(3).
This manual page describes the specific details of the
memory pool interface.
The DbMpool(3) and DbMpoolFile(3) classes are the library
interface intended to provide general-purpose, page-
oriented buffer management of one or more files. While
designed to work with the other Db functions, these
functions are also useful for more general purposes. The
memory pools (DbMpool's) are referred to in this document
as simply ``pools''. Pools may be shared between
processes. Pools are usually filled by pages from one or
more files (DbMpoolFile's). Pages in the pool are
replaced in LRU (least-recently-used) order, with each new
page replacing the page that has been unused the longest.
Pages retrieved from the pool using DbMpoolFile.get are
``pinned'' in the pool, by default, until they are
returned to the pool's control using the DbMpoolFile.put
method.
DbMpool.open
The DbMpool.open method returns a memory pool identified
by the directory dir.
If the dbenv argument to DbMpool.open was initialized
using DbEnv.appinit, dir is interpreted as described by
DbEnv(3).
Otherwise, if dir is not null, it is interpreted relative
to the current working directory of the process. If dir
is null, the following environment variables are checked
in order: ``TMPDIR'', ``TEMP'', and ``TMP''. If one of
them is set, memory pool files are created relative to the
directory it specifies. If none of them are set, the
first possible one of the following directories is used:
/var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.
All files associated with the memory pool are created in
this directory. This directory must already exist when
DbMpool.open is called. If the memory pool already
exists, the process must have permission to read and write
the existing files. If the memory pool does not already
exist, it is optionally created and initialized.
The flags and mode arguments specify how files will be
opened and/or created when they don't already exist. The
flags value is specified by or'ing together one or more of
the following values:
Db.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.DB_MPOOL_PRIVATE
Create a private MPOOL that is not shared with any
other process (although it may be shared with other
threads).
Db.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.DB_THREAD
Cause the DbMpool handle returned by the DbMpool.open
method to be useable by multiple threads within a
single address space, i.e., to be ``free-threaded''.
Threading is assumed in the Java API, so no special
flags are required, and DB functions will always
behave as if the DB_THREAD flag was specified.
All files created by the memory pool subsystem (other than
files created by the memp_fopen 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 DB.
The memory pool subsystem is configured based on which set
methods have been used. It is expected that applications
will use a single DbEnv object as the argument to all of
the subsystems in the DB package. The fields of the DbEnv
object used by DbMpool.open are described below. As
references to the DbEnv object may be maintained by
DbMpool.open, it is necessary that the DbEnv 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:
DbErrcall db_errcall;
String db_errpfx;
int db_verbose;
The error fields of the DbEnv behave as described for
DbEnv(3).
long 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.
long mp_size;
The suggested size of the pool, 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 (16 8K byte
pages), and may not be less than 20K bytes.
The DbMpool.open method throws a DbException(3) that
encapsulates an errno on failure.
DbMpool.close
The DbMpool.close method closes the pool indicated by the
DbMpool object, as returned by DbMpool.open. This method
does not imply a call to DbMpoolFile.sync (or to
DbMpoolFile.close) i.e. no pages are written to the source
file as as a result of calling DbMpool.close.
In addition, if the dir argument to DbMpool.open was null
and dbenv was not initialized using DbEnv.appinit, all
files created for this shared region will be removed, as
if DbMpool.unlink were called.
When multiple threads are using the DbMpool handle
concurrently, only a single thread may call the
DbMpool.close method.
The DbMpool.close method throws a DbException(3) that
encapsulates an errno on failure.
DbMpool.unlink
The DbMpool.unlink method destroys the memory pool
identified by the directory dir, removing all files used
to implement the memory pool. (The directory dir is not
removed.) If there are processes that have called
DbMpool.open without calling DbMpool.close (i.e., there
are processes currently using the memory pool),
DbMpool.unlink will fail without further action, unless
the force flag is set, in which case DbMpool.unlink will
attempt to remove the memory pool files regardless of any
processes still using the memory pool.
The result of attempting to forcibly destroy the region
when a process has the region open is unspecified.
Processes using a shared memory region maintain an open
file descriptor for it. On UNIX systems, the region
removal should succeed and processes that have already
joined the region should continue to run in the region
without change, however processes attempting to join the
memory pool will either fail or attempt to create a new
region. On other systems, e.g., WNT, where the unlink(2)
system call will fail if any process has an open file
descriptor for the file, the region removal will fail.
In the case of catastrophic or system failure, database
recovery must be performed (see db_recover(1) or the
DB_RECOVER flags to DbEnv.appinit(3)). Alternatively, if
recovery is not required because no database state is
maintained across failures, it is possible to clean up a
memory pool by removing all of the files in the directory
specified to the DbMpool.open method, as memory pool files
are never created in any directory other than the one
specified to DbMpool.open. Note, however, that this has
the potential to remove files created by the other DB
subsystems in this database environment.
The DbMpool.unlink method throws a DbException(3) that
encapsulates an errno on failure.
The DbMpool.db_register method throws a DbException(3)
that encapsulates an errno on failure.
DbMpool.trickle
The DbMpool.trickle method ensures that at least pct
percent of the pages in the shared memory pool are clean
by writing dirty pages to their backing files. If the
nwrotep argument is non-null, the number of pages that
were written to reach the correct percentage is returned
in the memory location it references.
The purpose of the DbMpool.trickle method is to enable a
memory pool manager to ensure that a page is always
available for reading in new information without having to
wait for a write.
The DbMpool.trickle method throws a DbException(3) that
encapsulates an errno on failure.
DbMpool.sync
The DbMpool.sync method ensures that all the modified
pages in the pool with log sequence numbers (LSNs) less
than the lsn argument are written to disk.
The DbMpool.sync method throws a DbException(3) that
encapsulates an errno on failure, and DB_INCOMPLETE if
there were pages which need to be written but which
DbMpool.sync was unable to write immediately. In
addition, if DbMpool.sync returns success, the value of
lsn will be overwritten with the largest LSN from any page
which was written by DbMpool.sync to satisfy this request.
The purpose of the DbMpool.sync method is to enable a
transaction manager to ensure, as part of a checkpoint,
that all pages modified by a certain time have been
written to disk. Pages in the pool which cannot be
written back to disk immediately (e.g., are currently
pinned) are written to disk as soon as it is possible to
do so. The expected behavior of the transaction manager
is to call the DbMpool.sync method and then, if the return
indicates that some pages could not be written
immediately, to wait briefly and retry again with the same
LSN until the DbMpool.sync method returns that all pages
have been written.
To support the DbMpool.sync functionality, it is necessary
that the pool functions know the location of the LSN on
the page for each file type. This location should be
specified when the file is opened using the
DbMpoolFile.open method. (Note, it is not required that
the LSN be aligned on the page in any way.)
DbMpool.stat
DbMpool.fstat
The DbMpool.stat and DbMpool.fstat methods create
statistical structures and return to the caller. The
statistics include the number of files participating in
the pool, the active pages in the pool, and information as
to how effective the cache has been.
The stat method creates a DbMpoolStat object containing
global statistics. The fields can be accessed via
methods:
long get_st_cachesize();
Cache size in bytes.
long get_st_cache_hit;();
Requested pages found in the cache.
long get_st_cache_miss;();
Requested pages not found in the cache.
long get_st_map;();
Requested pages mapped into the process' address
space (there is no available information as to
whether or not this request caused disk I/O, although
examining the application page fault rate may be
helpful).
long get_st_page_create;();
Pages created in the cache.
long get_st_page_in;();
Pages read into the cache.
long get_st_page_out;();
Pages written from the cache to the backing file.
long get_st_ro_evict;();
Clean pages forced from the cache.
long get_st_rw_evict;();
Dirty pages forced from the cache.
long get_st_hash_buckets;();
Number of hash buckets in buffer hash table.
long get_st_hash_searches;();
Total number of buffer hash table lookups.
long get_st_hash_longest;();
The longest chain ever encountered in buffer hash
table lookups.
long get_st_hash_examined;();
Total number of hash elements traversed during hash
table lookups.
long get_st_page_clean;();
Clean pages currently in the cache.
long get_st_page_dirty;();
Dirty pages currently in the cache.
long get_st_page_trickle;();
Dirty pages written using the memp_trickle interface.
The fstat method creates an array of DbMpoolFStat objects
containing statistics for individual files in the pool.
Each DbMpoolFStat object contains statistics for an
individual DbMpoolFile, and the statistics can be accessed
via methods:
String get_file_name();
The name of the file.
long get_st_pagesize();
Page size in bytes.
long get_st_cache_hit;();
Requested pages found in the cache.
long get_st_cache_miss;();
Requested pages not found in the cache.
long get_st_map;();
Requested pages mapped into the process' address
space.
long get_st_page_create;();
Pages created in the cache.
long get_st_page_in;();
Pages read into the cache.
long get_st_page_out;();
Pages written from the cache to the backing file.
The DbMpool.stat method throws a DbException(3) that
encapsulates an errno on failure.
ENVIRONMENT VARIABLES
The following environment variables affect the behavior of
DbMpoolFile:
DB_HOME
If the dbenv argument to DbMpool.open was initialized
using db_appinit, the environment variable DB_HOME
may be used as the path of the database home for the
interpretation of the dir argument to DbMpool.open,
as described in db_appinit(3).
TMPDIR
If the dbenv argument to DbMpool.open was null or not
initialized using db_appinit, the environment
variable TMPDIR may be used as the directory in which
to create the memory pool, as described in the
DbMpool.open section above.
ERRORS
The DbMpool.open method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: DBmemp->pgin(3),
DBmemp->pgout(3), DbLog.compare(3), DbLog.flush(3),
DbMpool.close(3), DbMpool.unlink(3), close(2),
db_version(3), fcntl(2), fflush(3), fsync(2), lseek(2),
malloc(3), memcmp(3), memcpy(3), memset(3), mmap(2),
munmap(2), open(2), sigfillset(3), sigprocmask(2),
stat(2), strcpy(3), strdup(3), strerror(3), strlen(3),
time(3), unlink(2), and write(2).
In addition, the DbMpool.open method may fail and throw a
DbException(3) encapsulating an 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.
The DbMpool.close method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: DbMpoolFile.close(3),
close(2), fcntl(2), fflush(3), munmap(2), and strerror(3).
The DbMpool.unlink method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: close(2), fcntl(2),
fflush(3), malloc(3), memcpy(3), memset(3), mmap(2),
munmap(2), open(2), sigfillset(3), sigprocmask(2),
stat(2), strcpy(3), strdup(3), strerror(3), strlen(3), and
unlink(2).
In addition, the DbMpool.unlink method may fail and throw
a DbException(3) encapsulating an errno for the following
conditions:
[EBUSY]
The shared memory region was in use and the force
flag was not set.
The DbMpool.db_register method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: fcntl(2), and
malloc(3).
The DbMpool.trickle method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: DBmemp->pgin(3),
DBmemp->pgout(3), DbLog.compare(3), DbLog.flush(3),
close(2), fcntl(2), fflush(3), fsync(2), lseek(2),
malloc(3), memcmp(3), memcpy(3), memset(3), mmap(2),
open(2), sigfillset(3), sigprocmask(2), stat(2),
strcpy(3), strdup(3), strerror(3), strlen(3), time(3),
unlink(2), and write(2).
In addition, the DbMpool.trickle method may fail and throw
a DbException(3) encapsulating an errno for the following
conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The DbMpool.sync method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: DBmemp->pgin(3),
DBmemp->pgout(3), DbLog.compare(3), DbLog.flush(3),
close(2), fcntl(2), fflush(3), fsync(2), lseek(2),
malloc(3), memcmp(3), memcpy(3), memset(3), mmap(2),
open(2), qsort(3), realloc(3), sigfillset(3),
sigprocmask(2), stat(2), strcpy(3), strdup(3),
strerror(3), strlen(3), time(3), unlink(2), and write(2).
In addition, the DbMpool.sync method may fail and throw a
DbException(3) encapsulating an errno for the following
conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The DbMpool.sync method was called without logging
having been initialized in the environment.
The DbMpool.stat method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: fcntl(2), malloc(3),
memcpy(3), and strlen(3).
SEE ALSO
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_load(1), db_recover(1), db_stat(1), db_intro(3),
db_internal(3), db_thread(3), Db(3), Dbc(3), DbEnv(3),
DbException(3), DbInfo(3), DbLock(3), DbLockTab(3), DbLog(3),
DbLsn(3), DbMpool(3), DbMpoolFile(3), Dbt(3), DbTxn(3),
DbTxnMgr(3)
Man(1) output converted with
man2html