1<!--Copyright 1999,2008 Oracle. All rights reserved.--> 2<HTML> 3<HEAD> 4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> 5 <META NAME="GENERATOR" CONTENT="Mozilla/4.08 [en] (X11; I; FreeBSD 2.2.8-19990120-SNAP i386) [Netscape]"> 6</HEAD> 7<BODY> 8 9<H2> 10<A NAME="Memory Pool Commands"></A>Memory Pool Commands</H2> 11Memory pools are used in a manner similar to the other subsystems. 12We create a handle to the pool and then use it for a variety of operations. 13Some of the memory pool commands use the environment instead. Those are 14presented first. 15<P><B>> <env> mpool_stat</B> 16<P>This command returns the statistics associated with the memory 17pool subsystem. It is a direct call to the <A HREF="../../docs/api_c/memp_stat.html">memp_stat</A> 18function. It returns a list of name/value pairs of the DB_MPOOL_STAT 19structure. 20<BR> 21<HR WIDTH="100%"> 22<BR><B>> <env> mpool_sync <I>lsn</I></B> 23<P>This command flushes the memory pool for all pages with a log sequence 24number 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> 25function. It returns either a 0 (for success), a DB error message 26or it throws a Tcl error with a system message. 27<BR> 28<HR WIDTH="100%"> 29<BR><B>> <env> mpool_trickle <I>percent</I></B> 30<P>This command tells DB to ensure that at least <B><I>percent</I></B> 31percent of the pages are clean by writing out enough to dirty pages to 32achieve that percentage. It is a direct call to the <A HREF="../../docs/api_c/memp_trickle.html">memp_trickle</A> 33function. The command will return the number of pages actually written. 34It returns either the number of pages on success, or it throws a Tcl error 35with a system message. 36<BR> 37<HR WIDTH="100%"> 38<P><B>> <env> mpool [-create] [-nommap] [-rdonly] [-mode <I>mode</I>] 39-pagesize <I>size</I> [<I>file</I>]</B> 40<P>This command creates a new memory pool. It invokes the <A HREF="../../docs/api_c/memp_fopen.html">memp_fopen</A> 41function. After it successfully gets a handle to a memory pool, we 42bind it to a new Tcl command of the form <B><I>$env.mpX</I></B>, where 43X is an integer starting at 0 (e.g. <B>$env.mp0, $env.mp1, </B>etc). 44We use the <I>Tcl_CreateObjCommand()</I> to create the top level memory 45pool functions. It is through this handle that the user can manipulate 46the pool. Internally, the handle we get back from DB will be stored 47as the <I>ClientData</I> portion of the new command set so that future 48memory pool calls will have that handle readily available. Additionally, 49we need to maintain this handle in relation to the environment so that 50if the user calls <A HREF="../../docs/api_tcl/env_close.html"><env> close</A> without closing 51the memory pool we can properly clean up. The arguments are: 52<UL> 53<LI> 54<B><I>file</I></B> is the name of the file to open</LI> 55 56<LI> 57<B>-create </B>selects the DB_CREATE flag to create underlying file</LI> 58 59<LI> 60<B>-mode <I>mode </I></B>sets the permissions of created file to <B><I>mode</I></B></LI> 61 62<LI> 63<B>-nommap</B> selects the DB_NOMMAP flag to disallow using mmap'ed files</LI> 64 65<LI> 66<B>-pagesize</B> sets the underlying file page size to <B><I>size</I></B></LI> 67 68<LI> 69<B>-rdonly </B>selects the DB_RDONLY flag for read only access</LI> 70</UL> 71 72<HR WIDTH="100%"> 73<BR><B>> <mp> close</B> 74<P>This command closes the memory pool. It is a direct call to the 75<A HREF="../../docs/api_c/memp_fclose.html">memp_close</A> 76function. It returns either a 0 (for success), a DB error message 77or it throws a Tcl error with a system message. 78<P>Additionally, since the handle is no longer valid, we will call 79<I>Tcl_DeleteCommand() 80</I>so 81that further uses of the handle will be dealt with properly by Tcl itself. 82We must also remove the reference to this handle from the environment. 83We will go through the list of pinned pages that were acquired by the <A HREF="#> <mp> get">get</A> 84command and 85<A HREF="#> <pg> put">put</A> them back. 86<HR WIDTH="100%"> 87<BR><B>> <mp> fsync</B> 88<P>This command flushes all of the file's dirty pages to disk. It 89is a direct call to the <A HREF="../../docs/api_c/memp_fsync.html">memp_fsync</A> 90function. It returns either a 0 (for success), a DB error message 91or it throws a Tcl error with a system message. 92<HR WIDTH="100%"> 93<BR><A NAME="> <mp> get"></A><B>> <mp> get [-create] [-last] [-new] 94[<I>pgno</I>]</B> 95<P>This command gets the <B><I>pgno </I></B>page from the memory 96pool. It invokes the <A HREF="../../docs/api_c/memp_fget.html">memp_fget</A> 97function and possibly the <A HREF="../../docs/api_c/memp_fset.html">memp_fset</A> 98function if any options are chosen to set the page characteristics. 99After it successfully gets a handle to a page, we bind it to and 100return a new Tcl command of the form <B><I>$env.mpN.pX</I></B>, where X 101is an integer starting at 0 (e.g. <B>$env.mp0.p0, $env.mp1.p0, </B>etc). 102We use the <I>Tcl_CreateObjCommand()</I> to create the top level page functions. 103It is through this handle that the user can manipulate the page. 104Internally, the handle we get back from DB will be stored as the <I>ClientData</I> 105portion of the new command set. We need to store this handle in 106relation to the memory pool handle so that if the memory pool is closed, 107we will <A HREF="#> <pg> put">put</A> back the pages (setting the discard 108flag) and delete that set of commands. 109<P>The arguments are: 110<UL> 111<LI> 112<B>-create </B>selects the DB_MPOOL_CREATE flag to create the page 113if it does not exist.</LI> 114 115<LI> 116<B>-last</B> selects the DB_MPOOL_LAST flag to return the last page in 117the file</LI> 118 119<LI> 120<B>-new</B> selects the DB_MPOOL_NEW flag to create a new page</LI> 121</UL> 122 123<HR WIDTH="100%"> 124<BR><B>> <pg> pgnum</B> 125<P>This command returns the page number associated with this memory pool 126page. Primarily it will be used after an <A HREF="#> <mp> get"><mp> 127get</A> call. 128<BR> 129<HR WIDTH="100%"><B>> <pg> pgsize</B> 130<P>This command returns the page size associated with this memory pool 131page. Primarily it will be used after an <A HREF="#> <mp> get"><mp> 132get</A> call. 133<BR> 134<HR WIDTH="100%"><B>> <pg> set [-clean] [-dirty] [-discard]</B> 135<P>This command sets the characteristics of the page. It is a direct 136call to the <A HREF="../../docs/api_c/memp_fset.html">memp_fset</A> function. 137It returns either a 0 (for success), a DB error message or it throws a 138Tcl error with a system message. The arguments are: 139<UL> 140<LI> 141<B>-clean</B> selects the DB_MPOOL_CLEAN flag to indicate this is a clean 142page</LI> 143 144<LI> 145<B>-dirty</B> selects the DB_MPOOL_DIRTY flag to indicate this page should 146be flushed before eviction</LI> 147 148<LI> 149<B>-discard</B> selects the DB_MPOOL_DISCARD flag to indicate this page 150is unimportant</LI> 151</UL> 152 153<HR WIDTH="100%"> 154<BR><A NAME="> <pg> put"></A><B>> <pg> put [-clean] [-dirty] [-discard]</B> 155<P>This command will put back the page to the memory pool. It is 156a direct call to the <A HREF="../../docs/api_c/memp_fput.html">memp_fput</A> 157function. It returns either a 0 (for success), a DB error message 158or it throws a Tcl error with a system message. Additionally, since the 159handle is no longer valid, we will call 160<I>Tcl_DeleteCommand() 161</I>so that 162further uses of the handle will be dealt with properly by Tcl itself. 163We must also remove the reference to this handle from the memory pool. 164<P>The arguments are: 165<UL> 166<LI> 167<B>-clean</B> selects the DB_MPOOL_CLEAN flag to indicate this is a clean 168page</LI> 169 170<LI> 171<B>-dirty</B> selects the DB_MPOOL_DIRTY flag to indicate this page should 172be flushed before eviction</LI> 173 174<LI> 175<B>-discard</B> selects the DB_MPOOL_DISCARD flag to indicate this page 176is unimportant</LI> 177</UL> 178 179<HR WIDTH="100%"> 180<BR><B>> <pg> init <I>val|string</I></B> 181<P>This command initializes the page to the <B><I>val</I></B> given or 182places the <B><I>string</I></B> given at the beginning of the page. 183It returns a 0 for success or it throws a Tcl error with an error message. 184<P> 185<HR WIDTH="100%"> 186<BR><B>> <pg> is_setto <I>val|string</I></B> 187<P>This command verifies the page contains the <B><I>val</I></B> given 188or checks that the <B>string</B> given is at the beginning of the page. 189It returns a 1 if the page is correctly set to the value and a 0 otherwise. 190