Tcl_SaveResult(3) Tcl Library Procedures Tcl_SaveResult(3)
__________________________________________________________________________________________________________________________________________________
NAME
Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult - save and
restore an interpreter's state
SYNOPSIS
#include <tcl.h>
Tcl_InterpState
Tcl_SaveInterpState(interp, status)
int
Tcl_RestoreInterpState(interp, state)
Tcl_DiscardInterpState(state)
Tcl_SaveResult(interp, savedPtr)
Tcl_RestoreResult(interp, savedPtr)
Tcl_DiscardResult(savedPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter for which state should be saved.
int status (in) Return code value to save as part of interpreter state.
Tcl_InterpState state (in) Saved state token to be restored or discarded.
Tcl_SavedResult *savedPtr (in) Pointer to location where interpreter result should be saved or restored.
_________________________________________________________________
DESCRIPTION
These routines allows a C procedure to take a snapshot of the current state of an interpreter so that it can be restored after a call to |
Tcl_Eval or some other routine that modifies the interpreter state. There are two triplets of routines meant to work together. |
The first triplet stores the snapshot of interpreter state in an opaque token returned by Tcl_SaveInterpState. That token value may then |
be passed back to one of Tcl_RestoreInterpState or Tcl_DiscardInterpState, 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. |
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 Tcl_SavedResult 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 -errorcode or -errorinfo return options, when an error is in progress). |
Because the routines Tcl_SaveInterpState, Tcl_RestoreInterpState, and Tcl_DiscardInterpState 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 Tcl_SaveResult, |
Tcl_RestoreResult, and Tcl_DiscardResult continue to exist only for the sake of existing programs that may already be using them. |
Tcl_SaveInterpState 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 status argument, and any return options, including -errorinfo and -error- |
code when an error is in progress. This snapshot is returned as an opaque token of type Tcl_InterpState. The call to Tcl_SaveInterpState |
does not itself change the state of the interpreter. Unlike Tcl_SaveResult, it does not reset the interpreter. |
Tcl_RestoreInterpState accepts a Tcl_InterpState token previously returned by Tcl_SaveInterpState and restores the state of the interp to |
the state held in that snapshot. The return value of Tcl_RestoreInterpState is the status value originally passed to Tcl_SaveInterpState |
when the snapshot token was created. |
Tcl_DiscardInterpState is called to release a Tcl_InterpState token previously returned by Tcl_SaveInterpState when that snapshot is not to |
be restored to an interp. |
The Tcl_InterpState token returned by Tcl_SaveInterpState must eventually be passed to either Tcl_RestoreInterpState or Tcl_DiscardInterp- |
State to avoid a memory leak. Once the Tcl_InterpState token is passed to one of them, the token is no longer valid and should not be used |
anymore.
Tcl_SaveResult moves the string and object results of interp into the location specified by statePtr. Tcl_SaveResult clears the result for
interp and leaves the result in its normal empty initialized state.
Tcl_RestoreResult moves the string and object results from statePtr back into interp. Any result or error that was already in the inter-
preter will be cleared. The statePtr is left in an uninitialized state and cannot be used until another call to Tcl_SaveResult.
Tcl_DiscardResult releases the saved interpreter state stored at statePtr. The state structure is left in an uninitialized state and can-
not be used until another call to Tcl_SaveResult.
Once Tcl_SaveResult is called to save the interpreter result, either Tcl_RestoreResult or Tcl_DiscardResult must be called to properly
clean up the memory associated with the saved state.
KEYWORDS
result, state, interp
Tcl 8.1 Tcl_SaveResult(3)