Author:         Don Porter <dgp@users.sf.net>
State:          Final
Type:           Project
Vote:           Done
Created:        30-Oct-2004
Post-History:   
Keywords:       Tcl
Tcl-Version:    8.5

Abstract

This TIP proposes new public C routines to allow the dynamic state of an interp, including the return options, and error logging in progress as well as the interp result, to be saved and later restored.

Background

The Tcl C library has long recognized the need for some routines to be able to make use of a Tcl_Interp without leaving any lasting footprints behind, and without interfering with whatever operations that Tcl_Interp might be in the midst of performing. The longstanding routines used to address this need have been Tcl_SaveResult, Tcl_RestoreResult, and Tcl_DiscardResult.

These existing routines also have known limitations. The documentation warns that they should not be used when an error is in progress, because they are not able to preserve the extra error information in the Tcl_Interp, only the result.

The existing routines are also showing their age. Because they focus on the result of the Tcl_Interp, and because they date from at least the Tcl 7 days, they spend an inordinate amount of effort tending to the needs of the long-deprecated interp->result field. Also, they make use of the transparent definition of a public struct, Tcl_SavedResult, and expect the caller to allocate such structs itself, a practice now frowned upon, and replaced with the use of opaque structs.

The Itcl extension has long worked around the limitations of Tcl_SaveResult, etc. by defining its own set of routines that more completely save and restore the state of a Tcl_Interp. These routines are Itcl_SaveInterpState, Itcl_RestoreInterpState, and Itcl_DiscardInterpState. These routines are able to handle the case of an error in progress, and have an interface making use of an opaque struct, Itcl_InterpState. In order to create these routines, however, the Itcl extension makes direct access to some of the private fields of Tcl's Interp struct.

In Tcl 8.5, the proposal of [90] have already extended further the values that make up the state of a Tcl_Interp, including a return level, and a dictionary of return options. Also, some of the internal fields of the Interp struct have been reworked, so that the Itcl routines no longer function without modification.

It it time for Tcl to provide public interfaces that perform the functions of the Itcl_*InterpState routines, and in fact, Tcl should provide exactly those routines.

Proposal

Three new routines will be added to Tcl's public stub table:

Tcl_InterpState Tcl_SaveInterpState(Tcl_Interp *interp, int status)

int Tcl_RestoreInterpState(Tcl_Interp *interp, Tcl_InterpState state)

void Tcl_DiscardInterpState(Tcl_InterpState state)

Also an opaque struct will be declared in tcl.h:

typedef struct Tcl_InterpState_ *Tcl_InterpState;

These routines are to have the same function as their existing Itcl counterparts.

These declarations and routines already exist in the HEAD of Tcl's development sources, but as private routines. The Tcl source code itself has already had an upgrade to replace all uses of the old Tcl_SaveResult calls with these new routines. This TIP merely proposes making these routines available as part of the public interface.

Compatibility

Strictly speaking, there are no compatibility issues, since these are new additions to the public interface.

Callers of the Tcl_SaveResult family of routines should be encouraged to update to use the new routines, as they perform the same function and more. The Tcl_SaveResult family of routines should be kept in the public interface at least through the Tcl 8 series of releases, though. Consideration of their removal for Tcl 9 is left for another proposal.

Itcl will have compatibility issues with Tcl 8.5 because of the changes to the internal fields of Tcl's Interp struct. Itcl should make use of these new routines as the implementation of its corresponding routines whenever compiling against a Tcl 8.5 set of headers. When doing that, of course, version 8.5 of the Tcl stubs table will need to be required.

Reference Implementation

See Tcl Patch 1060579.

Comments

Please make any comments here.

Copyright

This document has been placed in the public domain.