diff options
Diffstat (limited to 'db/tcl/docs/test.html')
| -rw-r--r-- | db/tcl/docs/test.html | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/db/tcl/docs/test.html b/db/tcl/docs/test.html new file mode 100644 index 000000000..10cf09efb --- /dev/null +++ b/db/tcl/docs/test.html @@ -0,0 +1,149 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<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="Debugging"></A>Debugging and Testing</H2> +We have imported the debugging system from the old test suite into the +new interface to aid in debugging problems. There are several variables +that are available both in gdb as globals to the C code, and variables +in Tcl that the user can set. These variables are linked together +so that changes in one venue are reflected in the other. The names +of the variables have been modified a bit to reduce the likelihood +<BR>of namespace trampling. We have added a double underscore to +all the names. +<P>The variables are all initialized to zero (0) thus resulting in debugging +being turned off. The purpose of the debugging, fundamentally, is +to allow the user to set a breakpoint prior to making a DB call. +This breakpoint is set in the <I>__db_loadme() </I>function. The +user may selectively turn on various debugging areas each controlled by +a separate variable (note they all have two (2) underscores prepended to +the name): +<UL> +<LI> +<B>__debug_on</B> - Turns on the debugging system. This must be on +for any debugging to occur</LI> + +<LI> +<B>__debug_print - </B>Turns on printing a debug count statement on each +call</LI> + +<LI> +<B>__debug_test -</B> Hits the breakpoint in <I>__db_loadme</I> on the +specific iteration</LI> + +<LI> +<B>__debug_stop </B>- Hits the breakpoint in <I>__db_loadme</I> on every +(or the next) iteration</LI> +</UL> +<B>Note to developers:</B> Anyone extending this interface must place +a call to <B>_debug_check()</B> (no arguments) before every call into the +DB library. +<P>There is also a command available that will force a call to the _debug_check +function. +<P><B>> berkdb debug_check</B> +<P> +<HR WIDTH="100%"> +<BR>For testing purposes we have added several hooks into the DB library +and a small interface into the environment and/or database commands to +manipulate the hooks. This command interface and the hooks and everything +that goes with it is only enabled when the test option is configured into +DB. +<P><B>> <env> test copy <I>location</I></B> +<BR><B>> <db> test copy <I>location</I></B> +<BR><B>> <env> test abort <I>location</I></B> +<BR><B>> <db> test abort <I>location</I></B> +<P>In order to test recovery we need to be able to abort the creation or +deletion process at various points. Also we want to invoke a copy +function to copy the database file(s) at various points as well so +that we can obtain before/after snapshots of the databases. The interface +provides the test command to specify a <B><I>location</I></B> where we +wish to invoke a <B>copy</B> or an <B>abort</B>. The command is available +from either the environment or the database for convenience. The +<B><I>location</I></B> +can be one of the following: +<UL> +<LI> +<B>none -</B> Clears the location</LI> + +<LI> +<B>preopen -</B> Sets the location prior to the __os_open call in the creation +process</LI> + +<LI> +<B>postopen</B> - Sets the location to immediately following the __os_open +call in creation</LI> + +<LI> +<B>postlogmeta</B> - Sets the location to immediately following the __db_log_page +call to log the meta data in creation. Only valid for Btree.</LI> + +<LI> +<B>postlog</B> - Sets the location to immediately following the last (or +only) __db_log_page call in creation.</LI> + +<LI> +<B>postsync</B> - Sets the location to immediately following the sync of +the log page in creation.</LI> + +<LI> +<B>prerename</B> - Sets the location prior to the __os_rename call in the +deletion process.</LI> + +<LI> +<B>postrename</B> - Sets the location to immediately following the __os_rename +call in deletion</LI> +</UL> + +<HR WIDTH="100%"> +<BR><B>> <env> mutex <I>mode nitems</I></B> +<P>This command creates a mutex region for testing. It sets the mode +of the region to <B><I>mode</I></B> and sets up for <B><I>nitems</I></B> +number of mutex entries. After we successfully get a handle to a +mutex we create a command of the form <B><I>$env.mutexX</I></B>, where +X is an integer starting at 0 (e.g. <B>$env.mutex0, $env.mutex1, +</B>etc). +We use the <I>Tcl_CreateObjCommand() </I> to create the top level +mutex function. It is through this handle that the user can access +all of the commands described below. Internally, the mutex handle +is sent as the <I>ClientData</I> portion of the new command set so that +all future mutex calls access the appropriate handle. +<P> +<HR WIDTH="100%"><B>> <mutex> close</B> +<P>This command closes the mutex and renders the handle invalid. +This command directly translates to the __db_r_detach function call. +It returns either a 0 (for success), 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. +<HR WIDTH="100%"><B>> <mutex> get <I>id</I></B> +<P>This command locks the mutex identified by <B><I>id</I></B>. It +returns either a 0 (for success), or it throws a Tcl error with a +system message. +<BR> +<HR WIDTH="100%"><B>> <mutex> release <I>id</I></B> +<P>This command releases the mutex identified by <B><I>id</I></B>. +It returns either a 0 (for success), or it throws a Tcl error with +a system message. +<BR> +<HR WIDTH="100%"><B>> <mutex> getval <I>id</I></B> +<P>This command gets the value stored for the mutex identified by <B><I>id</I></B>. +It returns either the value, or it throws a Tcl error with a system +message. +<BR> +<HR WIDTH="100%"><B>> <mutex> setval <I>id val</I></B> +<P>This command sets the value stored for the mutex identified by <B><I>id +</I></B>to +<B><I>val</I></B>. +It returns either a 0 (for success), or it throws a Tcl error with +a system message. +<BR> +<HR WIDTH="100%"> +<BR> +</BODY> +</HTML> |