Sindbad~EG File Manager
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Chapter 18. The Memory Pool Subsystem</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="prev" href="log_limits.html" title="Log file limits" />
<link rel="next" href="mp_config.html" title="Configuring the memory pool" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 11.2.5.3</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 18.
The Memory Pool Subsystem
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="log_limits.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="mp_config.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="mp"></a>Chapter 18.
The Memory Pool Subsystem
</h2>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="mp.html#mp_intro">Introduction to the memory pool subsystem</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="mp_config.html">Configuring the memory pool</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="mp_warm.html">Warming the memory pool</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2">
<a href="mp_warm.html#warm_cache">The warm_cache() function</a>
</span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="mp_intro"></a>Introduction to the memory pool subsystem</h2>
</div>
</div>
</div>
<p>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.)</p>
<p>A <span class="emphasis"><em>memory pool</em></span> is a memory cache shared among any number of
threads of control. The <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a> flag to the
<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method opens and optionally creates a memory pool. When
that pool is no longer in use, it should be closed using the
<a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> method.</p>
<p>The <a href="../api_reference/C/mempfcreate.html" class="olink">DB_ENV->memp_fcreate()</a> method returns a <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle on an
underlying file within the memory pool. The file may be opened using
the <a href="../api_reference/C/mempfopen.html" class="olink">DB_MPOOLFILE->open()</a> method. The <a href="../api_reference/C/mempfget.html" class="olink">DB_MPOOLFILE->get()</a> method is used to retrieve
pages from files in the pool. All retrieved pages must be subsequently
returned using the <a href="../api_reference/C/mempput.html" class="olink">DB_MPOOLFILE->put()</a> method. At the time pages are returned,
they may be marked <span class="bold"><strong>dirty</strong></span>, 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
<a href="../api_reference/C/mempfsync.html" class="olink">DB_MPOOLFILE->sync()</a> method. When the file handle is no longer in use, it
should be closed using the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE->close()</a> method.</p>
<p>There are additional configuration interfaces that apply when opening
a new file in the memory pool:</p>
<div class="itemizedlist">
<ul type="disc">
<li>The <a href="../api_reference/C/mempset_clear_len.html" class="olink">DB_MPOOLFILE->set_clear_len()</a> method specifies the number of bytes to clear
when creating a new page in the memory pool.</li>
<li>The <a href="../api_reference/C/mempset_fileid.html" class="olink">DB_MPOOLFILE->set_fileid()</a> method specifies a unique ID associated with the file.</li>
<li>The <a href="../api_reference/C/mempset_ftype.html" class="olink">DB_MPOOLFILE->set_ftype()</a> method specifies the type of file for the purposes of
page input and output processing.</li>
<li>The <a href="../api_reference/C/mempset_lsn_offset.html" class="olink">DB_MPOOLFILE->set_lsn_offset()</a> method specifies the byte offset of each page's
log sequence number (<a href="../api_reference/C/lsn.html" class="olink">DB_LSN</a>) for the purposes of transaction
checkpoints.</li>
<li>The <a href="../api_reference/C/mempset_pgcookie.html" class="olink">DB_MPOOLFILE->set_pgcookie()</a> method specifies an application provided argument
for the purposes of page input and output processing.</li>
</ul>
</div>
<p>There are additional interfaces for the memory pool as a whole:</p>
<div class="itemizedlist">
<ul type="disc">
<li>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 <a href="../api_reference/C/memptrickle.html" class="olink">DB_ENV->memp_trickle()</a> method.</li>
<li>Because special-purpose processing may be necessary when pages are read
or written (for example, endian conversion, or page checksums), the
<a href="../api_reference/C/mempregister.html" class="olink">DB_ENV->memp_register()</a> function allows applications to specify automatic
input and output processing in these cases.</li>
<li>The <a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility uses the <a href="../api_reference/C/mempstat.html" class="olink">DB_ENV->memp_stat()</a> method to display
statistics about the efficiency of the pool.</li>
<li>All dirty pages in the pool may be flushed using the <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV->memp_sync()</a> method.
In addition, <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV->memp_sync()</a> 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 (<a href="../api_reference/C/lsn.html" class="olink">DB_LSN</a>).</li>
<li>The entire pool may be discarded using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method.</li>
</ul>
</div>
<p>For more information on the memory pool subsystem methods, see the <a href="../api_reference/C/memp.html#memplist" class="olink">Memory Pools and Related Methods</a> section in the <em class="citetitle">Berkeley DB C API Reference Guide.</em> </p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="log_limits.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="mp_config.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Log file limits </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Configuring the memory pool</td>
</tr>
</table>
</div>
</body>
</html>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists