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 │
       -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   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_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 uninitialized 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