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 19. 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 18.1.40</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 19. 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 19. 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