Berkeley DB Reference Guide: Memory Pool Subsystem

Berkeley DB and the memory pool

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, cached, shared file access.

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 interface opens, optionally creating a memory pool. When that pool is no longer in use, it should be closed using the DB_ENV->close interface.

The memp_fopen interface returns a DB_MPOOLFILE handle on an underlying file within the memory pool. When that handle is no longer in use, it should be closed using the memp_fclose interface. The memp_fget interface is used to retrieve pages from files in the pool. All retrieved pages must be subsequently returned using the memp_fput interface. 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. Pages in files may also be explicitly marked clean or dirty using the memp_fset interface. All dirty pages in the pool may be flushed using the memp_sync interface. All dirty pages in the pool from a single underlying file may be flushed using the memp_fsync interface.

There are additional interfaces related to 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 memp_trickle interface.
• The db_stat utility uses the memp_stat interface to display statistics about the efficiency of the pool.
• Because some processing may be necessary when pages are read or written (for example, endian conversion), the memp_register function allows applications to specify automatic input and output processing in these cases.
• Although the memp_sync interface can be used to simply flush the entire pool, it also takes an argument that is specific to database systems. This argument allows the pool to be flushed up to a specified log sequence number.
• Finally, the entire pool may be discarded using the DB_ENV->remove interface.

Copyright Sleepycat Software