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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<!--Copyright 1999-2002 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.08 [en] (X11; I; FreeBSD 2.2.8-19990120-SNAP i386) [Netscape]">
</HEAD>
<BODY>
<H2>
<A NAME="Memory Pool Commands"></A>Memory Pool Commands</H2>
Memory pools are used in a manner similar to the other subsystems.
We create a handle to the pool and then use it for a variety of operations.
Some of the memory pool commands use the environment instead. Those are
presented first.
<P><B>> <env> mpool_stat</B>
<P>This command returns the statistics associated with the memory
pool subsystem. It is a direct call to the <A HREF="../../docs/api_c/memp_stat.html">memp_stat</A>
function. It returns a list of name/value pairs of the DB_MPOOL_STAT
structure.
<BR>
<HR WIDTH="100%">
<BR><B>> <env> mpool_sync <I>lsn</I></B>
<P>This command flushes the memory pool for all pages with a log sequence
number less than <B><I>lsn</I></B>. It is a direct call to the <A HREF="../../docs/api_c/memp_sync.html">memp_sync </A>
function. It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.
<BR>
<HR WIDTH="100%">
<BR><B>> <env> mpool_trickle <I>percent</I></B>
<P>This command tells DB to ensure that at least <B><I>percent</I></B>
percent of the pages are clean by writing out enough to dirty pages to
achieve that percentage. It is a direct call to the <A HREF="../../docs/api_c/memp_trickle.html">memp_trickle</A>
function. The command will return the number of pages actually written.
It returns either the number of pages on success, or it throws a Tcl error
with a system message.
<BR>
<HR WIDTH="100%">
<P><B>> <env> mpool [-create] [-nommap] [-rdonly] [-mode <I>mode</I>]
-pagesize <I>size</I> [<I>file</I>]</B>
<P>This command creates a new memory pool. It invokes the <A HREF="../../docs/api_c/memp_fopen.html">memp_fopen</A>
function. After it successfully gets a handle to a memory pool, we
bind it to a new Tcl command of the form <B><I>$env.mpX</I></B>, where
X is an integer starting at 0 (e.g. <B>$env.mp0, $env.mp1, </B>etc).
We use the <I>Tcl_CreateObjCommand()</I> to create the top level memory
pool functions. It is through this handle that the user can manipulate
the pool. Internally, the handle we get back from DB will be stored
as the <I>ClientData</I> portion of the new command set so that future
memory pool calls will have that handle readily available. Additionally,
we need to maintain this handle in relation to the environment so that
if the user calls <A HREF="../../docs/api_tcl/env_close.html"><env> close</A> without closing
the memory pool we can properly clean up. The arguments are:
<UL>
<LI>
<B><I>file</I></B> is the name of the file to open</LI>
<LI>
<B>-create </B>selects the DB_CREATE flag to create underlying file</LI>
<LI>
<B>-mode <I>mode </I></B>sets the permissions of created file to <B><I>mode</I></B></LI>
<LI>
<B>-nommap</B> selects the DB_NOMMAP flag to disallow using mmap'ed files</LI>
<LI>
<B>-pagesize</B> sets the underlying file page size to <B><I>size</I></B></LI>
<LI>
<B>-rdonly </B>selects the DB_RDONLY flag for read only access</LI>
</UL>
<HR WIDTH="100%">
<BR><B>> <mp> close</B>
<P>This command closes the memory pool. It is a direct call to the
<A HREF="../../docs/api_c/memp_fclose.html">memp_close</A>
function. It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.
<P>Additionally, since the handle is no longer valid, we will call
<I>Tcl_DeleteCommand()
</I>so
that further uses of the handle will be dealt with properly by Tcl itself.
We must also remove the reference to this handle from the environment.
We will go through the list of pinned pages that were acquired by the <A HREF="#> <mp> get">get</A>
command and
<A HREF="#> <pg> put">put</A> them back.
<HR WIDTH="100%">
<BR><B>> <mp> fsync</B>
<P>This command flushes all of the file's dirty pages to disk. It
is a direct call to the <A HREF="../../docs/api_c/memp_fsync.html">memp_fsync</A>
function. It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.
<HR WIDTH="100%">
<BR><A NAME="> <mp> get"></A><B>> <mp> get [-create] [-last] [-new]
[<I>pgno</I>]</B>
<P>This command gets the <B><I>pgno </I></B>page from the memory
pool. It invokes the <A HREF="../../docs/api_c/memp_fget.html">memp_fget</A>
function and possibly the <A HREF="../../docs/api_c/memp_fset.html">memp_fset</A>
function if any options are chosen to set the page characteristics.
After it successfully gets a handle to a page, we bind it to and
return a new Tcl command of the form <B><I>$env.mpN.pX</I></B>, where X
is an integer starting at 0 (e.g. <B>$env.mp0.p0, $env.mp1.p0, </B>etc).
We use the <I>Tcl_CreateObjCommand()</I> to create the top level page functions.
It is through this handle that the user can manipulate the page.
Internally, the handle we get back from DB will be stored as the <I>ClientData</I>
portion of the new command set. We need to store this handle in
relation to the memory pool handle so that if the memory pool is closed,
we will <A HREF="#> <pg> put">put</A> back the pages (setting the discard
flag) and delete that set of commands.
<P>The arguments are:
<UL>
<LI>
<B>-create </B>selects the DB_MPOOL_CREATE flag to create the page
if it does not exist.</LI>
<LI>
<B>-last</B> selects the DB_MPOOL_LAST flag to return the last page in
the file</LI>
<LI>
<B>-new</B> selects the DB_MPOOL_NEW flag to create a new page</LI>
</UL>
<HR WIDTH="100%">
<BR><B>> <pg> pgnum</B>
<P>This command returns the page number associated with this memory pool
page. Primarily it will be used after an <A HREF="#> <mp> get"><mp>
get</A> call.
<BR>
<HR WIDTH="100%"><B>> <pg> pgsize</B>
<P>This command returns the page size associated with this memory pool
page. Primarily it will be used after an <A HREF="#> <mp> get"><mp>
get</A> call.
<BR>
<HR WIDTH="100%"><B>> <pg> set [-clean] [-dirty] [-discard]</B>
<P>This command sets the characteristics of the page. It is a direct
call to the <A HREF="../../docs/api_c/memp_fset.html">memp_fset</A> function.
It returns either a 0 (for success), a DB error message or it throws a
Tcl error with a system message. The arguments are:
<UL>
<LI>
<B>-clean</B> selects the DB_MPOOL_CLEAN flag to indicate this is a clean
page</LI>
<LI>
<B>-dirty</B> selects the DB_MPOOL_DIRTY flag to indicate this page should
be flushed before eviction</LI>
<LI>
<B>-discard</B> selects the DB_MPOOL_DISCARD flag to indicate this page
is unimportant</LI>
</UL>
<HR WIDTH="100%">
<BR><A NAME="> <pg> put"></A><B>> <pg> put [-clean] [-dirty] [-discard]</B>
<P>This command will put back the page to the memory pool. It is
a direct call to the <A HREF="../../docs/api_c/memp_fput.html">memp_fput</A>
function. It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message. Additionally, since the
handle is no longer valid, we will call
<I>Tcl_DeleteCommand()
</I>so that
further uses of the handle will be dealt with properly by Tcl itself.
We must also remove the reference to this handle from the memory pool.
<P>The arguments are:
<UL>
<LI>
<B>-clean</B> selects the DB_MPOOL_CLEAN flag to indicate this is a clean
page</LI>
<LI>
<B>-dirty</B> selects the DB_MPOOL_DIRTY flag to indicate this page should
be flushed before eviction</LI>
<LI>
<B>-discard</B> selects the DB_MPOOL_DISCARD flag to indicate this page
is unimportant</LI>
</UL>
<HR WIDTH="100%">
<BR><B>> <pg> init <I>val|string</I></B>
<P>This command initializes the page to the <B><I>val</I></B> given or
places the <B><I>string</I></B> given at the beginning of the page.
It returns a 0 for success or it throws a Tcl error with an error message.
<P>
<HR WIDTH="100%">
<BR><B>> <pg> is_setto <I>val|string</I></B>
<P>This command verifies the page contains the <B><I>val</I></B> given
or checks that the <B>string</B> given is at the beginning of the page.
It returns a 1 if the page is correctly set to the value and a 0 otherwise.
|
