mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
160 lines
8.9 KiB
HTML
160 lines
8.9 KiB
HTML
<?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.2</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>
|