Memory Pool Commands

> <env> mpool_stat

This command returns  the statistics associated with the memory pool subsystem.  It is a direct call to the memp_stat function.  It returns a list of name/value pairs of the DB_MPOOL_STAT structure.

This command flushes the memory pool for all pages with a log sequence number less than lsn.  It is a direct call to the memp_sync  function.  It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message.

This command tells DB to ensure that at least percent percent of the pages are clean by writing out enough to dirty pages to achieve that percentage.  It is a direct call to the memp_trickle 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.

> <env> mpool [-create] [-nommap] [-rdonly] [-mode mode] -pagesize size [file]

This command creates a new memory pool.  It invokes the memp_fopen function.  After it successfully gets a handle to a memory pool, we bind it to a new Tcl command of the form $env.mpX, where X is an integer starting at  0 (e.g. $env.mp0, $env.mp1, etc).  We use the Tcl_CreateObjCommand() 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 ClientData 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 <env> close without closing the memory pool we can properly clean up.  The arguments are:

• file is the name of the file to open
• -create selects the DB_CREATE flag to create underlying file
• -mode mode sets the permissions of created file to mode
• -nommap selects the DB_NOMMAP flag to disallow using mmap'ed files
• -pagesize sets the underlying file page size to size
• -rdonly selects the DB_RDONLY flag for read only access

This command closes the memory pool.  It is a direct call to the memp_close 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 Tcl_DeleteCommand() 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 get command and put them back.

This command flushes all of the file's dirty pages to disk.  It is a direct call to the memp_fsync function.  It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message.

This command gets the  pgno page from the memory pool.  It invokes the memp_fget function and possibly the memp_fset 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 $env.mpN.pX, where X is an integer starting at  0 (e.g. $env.mp0.p0, $env.mp1.p0, etc).  We use the Tcl_CreateObjCommand() 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 ClientData 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 put back the pages (setting the discard flag) and delete that set of commands.

The arguments are:

• -create selects the DB_MPOOL_CREATE flag  to create the page if it does not exist.
• -last selects the DB_MPOOL_LAST flag to return the last page in the file
• -new selects the DB_MPOOL_NEW flag to create a new page

This command returns the page number associated with this memory pool page.  Primarily it will be used after an <mp> get call.

This command returns the page size associated with this memory pool page.  Primarily it will be used after an <mp> get call.

This command sets the characteristics of the page.  It is a direct call to the memp_fset 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:

• -clean selects the DB_MPOOL_CLEAN flag to indicate this is a clean page
• -dirty selects the DB_MPOOL_DIRTY flag to indicate this page should be flushed before eviction
• -discard selects the DB_MPOOL_DISCARD flag to indicate this page is unimportant

This command will put back the page to the memory pool.  It is a direct call to the memp_fput 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 Tcl_DeleteCommand() 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.

The arguments are:

• -clean selects the DB_MPOOL_CLEAN flag to indicate this is a clean page
• -dirty selects the DB_MPOOL_DIRTY flag to indicate this page should be flushed before eviction
• -discard selects the DB_MPOOL_DISCARD flag to indicate this page is unimportant

This command initializes the page to the val given or places the string given at the beginning of the page.  It returns a 0 for success or it throws a Tcl error with an error message.

This command verifies the page contains the val given or checks that the string 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.