Chapter 17.
The Memory Pool Subsystem

Introduction to the memory pool subsystem

The Memory Pool subsystem is the general-purpose shared memory buffer
pool used by Berkeley DB. This module is useful outside of the Berkeley DB package
for processes that require page-oriented, shared and cached file
access. (However, such "use outside of Berkeley DB" is not supported
in replicated environments.)

A memory pool is a memory cache shared among any number of
threads of control. The DB_INIT_MPOOL flag to the
DB_ENV->open() method opens and optionally creates a memory pool. When
that pool is no longer in use, it should be closed using the
DB_ENV->close() method.

The DB_ENV->memp_fcreate() method returns a DB_MPOOLFILE handle on an
underlying file within the memory pool. The file may be opened using
the DB_MPOOLFILE->open() method. The DB_MPOOLFILE->get() method is used to retrieve
pages from files in the pool. All retrieved pages must be subsequently
returned using the DB_MPOOLFILE->put() method. At the time pages are returned,
they may be marked dirty, which causes them to be written to
the underlying file before being discarded from the pool. If there is
insufficient room to bring a new page in the pool, a page is selected
to be discarded from the pool using a least-recently-used algorithm.
All dirty pages in the pool from the file may be flushed using the
DB_MPOOLFILE->sync() method. When the file handle is no longer in use, it
should be closed using the DB_MPOOLFILE->close() method.

There are additional configuration interfaces that apply when opening
a new file in the memory pool:

It is possible to gradually flush buffers from the pool in order to
maintain a consistent percentage of clean buffers in the pool using
the DB_ENV->memp_trickle() method.

Because special-purpose processing may be necessary when pages are read
or written (for example, endian conversion, or page checksums), the
DB_ENV->memp_register() function allows applications to specify automatic
input and output processing in these cases.

All dirty pages in the pool may be flushed using the DB_ENV->memp_sync() method.
In addition, DB_ENV->memp_sync() takes an argument that is specific to
database systems, and which allows the memory pool to be flushed up to
a specified log sequence number (DB_LSN).