<!--Copyright 1999,2008 Oracle. 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.