* doc/SaveResult.3: Documentation for Tcl_*InterpState (TIP 226).

2 files changed, 74 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index e1ba325..f817768 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,7 @@
 2004-11-18  Don Porter  <dgp@users.sourceforge.net>
 
+	* doc/SaveResult.3:	Documentation for Tcl_*InterpState (TIP 226).
+
 	* generic/tclEvent.c (HandleBgErrors):	Simplified program flow.
 
 	* tests/basic.test:	Updated functional (not testing) uses of
diff --git a/doc/SaveResult.3 b/doc/SaveResult.3
index 6a0a051..b2bb744 100644
--- a/doc/SaveResult.3
+++ b/doc/SaveResult.3
@@ -1,45 +1,106 @@
 '\"
 '\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SaveResult.3,v 1.2 1999/04/16 00:46:33 stanton Exp $
+'\" RCS: @(#) $Id: SaveResult.3,v 1.3 2004/11/18 22:04:39 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's result
+Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-\fBTcl_SaveResult(\fIinterp, statePtr\fB)\fR
+Tcl_InterpState
+\fBTcl_SaveInterpState(\fIinterp, status\fB)\fR
 .sp
-\fBTcl_RestoreResult(\fIinterp, statePtr\fB)\fR
+int
+\fBTcl_RestoreInterpState(\fIinterp, state\fB)\fR
 .sp
-\fBTcl_DiscardResult(\fIstatePtr\fB)\fR
+\fBTcl_DiscardInterpState(\fIstate\fB)\fR
+.sp
+\fBTcl_SaveResult(\fIinterp, savedPtr\fB)\fR
+.sp
+\fBTcl_RestoreResult(\fIinterp, savedPtr\fB)\fR
+.sp
+\fBTcl_DiscardResult(\fIsavedPtr\fB)\fR
 .SH ARGUMENTS
-.AS Tcl_SavedResult statePtr
+.AS Tcl_InterpState savedPtr
 .AP Tcl_Interp *interp in
 Interpreter for which state should be saved.
-.AP Tcl_SavedResult *statePtr in
+.AP int status in
+Return code value to save as part of interpreter state.
+.AP Tcl_InterpState state in
+Saved state token to be restored or discarded.
+.AP Tcl_SavedResult *savedPtr in
 Pointer to location where interpreter result should be saved or restored.
 .BE
 
 .SH DESCRIPTION
 .PP
+.VS 8.5
 These routines allows a C procedure to take a snapshot of the current
-interpreter result so that it can be restored after a call
+state of an interpreter so that it can be restored after a call
 to \fBTcl_Eval\fR or some other routine that modifies the interpreter
-result.  These routines are passed a pointer to a structure that is
-used to store enough information to restore the interpreter result
-state.  This structure can be allocated on the stack of the calling
+state.  There are two triplets of routines meant to work together.
+.PP
+The first triplet stores the snapshot of interpreter state in
+an opaque token returned by \fBTcl_SaveInterpState\fR.  That token
+value may then be passed back to one of \fBTcl_RestoreInterpState\fR
+or \fBTcl_DiscardInterpState\fR, depending on whether the interp
+state is to be restored.  So long as one of the latter two routines
+is called, Tcl will take care of memory management.
+.PP
+The second triplet stores the snapshot of only the interpreter
+result (not its complete state) in memory allocated by the caller.
+These routines are passed a pointer to a \fBTcl_SavedResult\fR structure
+that is used to store enough information to restore the interpreter result.
+This structure can be allocated on the stack of the calling
 procedure.  These routines do not save the state of any error
 information in the interpreter (e.g. the \fBerrorCode\fR or
 \fBerrorInfo\fR variables).
 .PP
+Because the routines \fBTcl_SaveInterpState\fR,
+\fBTcl_RestoreInterpState\fB, and \fBTcl_DiscardInterpState\fR perform
+a superset of the functions provided by the other routines,
+any new code should only make use of the more powerful routines.
+The older, weaker routines \fBTcl_SaveResult\fB, \fBTcl_RestoreResult\fB,
+and \fBTcl_DiscardResult\fB continue to exist only for the sake
+of existing programs that may already be using them.  
+.PP
+\fBTcl_SaveInterpState\fR takes a snapshot of those portions of
+interpreter state that make up the full result of script evaluation.
+This include the interpreter result, the return code (passed in
+as the \fIstatus\fR argument, and any return options, including
+the errorInfo and errorCode information when an error is in progress.
+This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
+The call to \fBTcl_SaveInterpState\fR does not itself change the
+state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
+not reset the interpreter.
+.PP
+\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
+previously returned by \fBTcl_SaveInterpState\fR and restores the
+state of the interp to the state held in that snapshot.  The return
+value of \fBTcl_RestoreInterpState\fR is the status value originally
+passed to \fBTcl_SaveInterpState\fR when the snapshot token was
+created.
+.PP
+\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
+token previously returned by \fBTcl_SaveInterpState\fR when that
+snapshot is not to be restored to an interp.
+.PP
+The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
+must eventually be passed to either \fBTcl_RestoreInterpState\fR
+or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
+the \fBTcl_InterpState\fR token is passed to one of them, the
+token is no longer valid and should not be used anymore.
+.VE
+.PP
 \fBTcl_SaveResult\fR moves the string and object results
 of \fIinterp\fR into the location specified by \fIstatePtr\fR.
 \fBTcl_SaveResult\fR clears the result for \fIinterp\fR and