Tcl_SaveInterpState(3tcl)
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 dis-
carded.
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. |
Tcl Last change: 8.1 1
Tcl_SaveResult(3) Tcl Library Procedures Tcl_SaveResult(3)
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 inter- |
preter 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 struc- |
ture can be allocated on the stack of the calling procedure. |
These routines do not save the state of any error informa- |
tion 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 rou- |
tines. 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 -errorcode 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 pre- |
viously 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 |
Tcl Last change: 8.1 2
Tcl_SaveResult(3) Tcl Library Procedures Tcl_SaveResult(3)
or Tcl_DiscardInterpState 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 interpreter 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 unin-
itialized state and cannot 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 Last change: 8.1 3
Man(1) output converted with
man2html