<\/a> <\/h2>\nThese 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<\/b> or some other routine that modifies the interpreter state. There are two triplets of routines meant to work together.<\/p>\n
The first triplet stores the snapshot of interpreter state in an opaque token returned by Tcl_SaveInterpState<\/b>. That token value may then be passed back to one of Tcl_RestoreInterpState<\/b> or Tcl_DiscardInterpState<\/b>, 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.<\/p>\n
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 Tcl_SavedResult<\/b> that is used to store enough information to restore the interpreter result. Tcl_SavedResult<\/b> 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 \u2212errorcode<\/b> or \u2212errorinfo<\/b> return options, when an error is in progress).<\/p>\n
Because the routines Tcl_SaveInterpState<\/b>, Tcl_RestoreInterpState<\/b>, and Tcl_DiscardInterpState<\/b> 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<\/b>, Tcl_RestoreResult<\/b>, and Tcl_DiscardResult<\/b> continue to exist only for the sake of existing programs that may already be using them.<\/p>\n
Tcl_SaveInterpState<\/b> 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<\/i> argument, and any return options, including \u2212errorinfo<\/b> and \u2212errorcode<\/b> when an error is in progress. This snapshot is returned as an opaque token of type Tcl_InterpState<\/b>. The call to Tcl_SaveInterpState<\/b> does not itself change the state of the interpreter. Unlike Tcl_SaveResult<\/b>, it does not reset the interpreter.<\/p>\n
Tcl_RestoreInterpState<\/b> accepts a Tcl_InterpState<\/b> token previously returned by Tcl_SaveInterpState<\/b> and restores the state of the interp to the state held in that snapshot. The return value of Tcl_RestoreInterpState<\/b> is the status value originally passed to Tcl_SaveInterpState<\/b> when the snapshot token was created.<\/p>\n
Tcl_DiscardInterpState<\/b> is called to release a Tcl_InterpState<\/b> token previously returned by Tcl_SaveInterpState<\/b> when that snapshot is not to be restored to an interp.<\/p>\n
The Tcl_InterpState<\/b> token returned by Tcl_SaveInterpState<\/b> must eventually be passed to either Tcl_RestoreInterpState<\/b> or Tcl_DiscardInterpState<\/b> to avoid a memory leak. Once the Tcl_InterpState<\/b> token is passed to one of them, the token is no longer valid and should not be used anymore.<\/p>\n
Tcl_SaveResult<\/b> moves the string and value results of interp<\/i> into the location specified by statePtr<\/i>. Tcl_SaveResult<\/b> clears the result for interp<\/i> and leaves the result in its normal empty initialized state.<\/p>\n
Tcl_RestoreResult<\/b> moves the string and value results from statePtr<\/i> back into interp<\/i>. Any result or error that was already in the interpreter will be cleared. The statePtr<\/i> is left in an uninitialized state and cannot be used until another call to Tcl_SaveResult<\/b>.<\/p>\n
Tcl_DiscardResult<\/b> releases the saved interpreter state stored at statePtr<\/b>. The state structure is left in an uninitialized state and cannot be used until another call to Tcl_SaveResult<\/b>.<\/p>\n
Once Tcl_SaveResult<\/b> is called to save the interpreter result, either Tcl_RestoreResult<\/b> or Tcl_DiscardResult<\/b> must be called to properly clean up the memory associated with the saved state.<\/p>\n