1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
<?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>
|
