Scroll to navigation

Tcl_CreateInterp(3tcl) Tcl Library Procedures Tcl_CreateInterp(3tcl)
 


NAME

Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted - create and delete Tcl
  command interpreters

SYNOPSIS


#include <tcl.h>


Tcl_Interp *
Tcl_CreateInterp()


Tcl_DeleteInterp(interp)


int
Tcl_InterpDeleted(interp)



ARGUMENTS



  
Tcl_Interp *interp (in)

  
Token for interpreter to be destroyed.
    
    

    
 

    

  




DESCRIPTION

Tcl_CreateInterp creates a new interpreter structure and returns a token
  for it. The token is required in calls to most other Tcl procedures, such as
  Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp.
  Clients are only allowed to access a few of the fields of Tcl_Interp
  structures; see the Tcl_Interp and Tcl_CreateCommand man pages
  for details. The new interpreter is initialized with the built-in Tcl commands
  and with the variables documented in tclvars(3tcl). To bind in additional
  commands, call Tcl_CreateCommand.


Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will
  eventually be deleted when all calls to Tcl_Preserve for it have been
  matched by calls to Tcl_Release. At that time, all of the resources
  associated with it, including variables, procedures, and application-specific
  command bindings, will be deleted. After Tcl_DeleteInterp returns any
  attempt to use Tcl_Eval on the interpreter will fail and return
  TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to
  examine the interpreter's result, query or set the values of variables,
  define, undefine or retrieve procedures, and examine the runtime evaluation
  stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for
  details.


Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called
  with interp as its argument; this indicates that the interpreter will
  eventually be deleted, when the last call to Tcl_Preserve for it is
  matched by a call to Tcl_Release. If nonzero is returned, further calls
  to Tcl_Eval in this interpreter will return TCL_ERROR.


Tcl_InterpDeleted is useful in deletion callbacks to distinguish between
  when only the memory the callback is responsible for is being deleted and when
  the whole interpreter is being deleted. In the former case the callback may
  recreate the data being deleted, but this would lead to an infinite loop if
  the interpreter were being deleted.



INTERPRETERS AND MEMORY MANAGEMENT

Tcl_DeleteInterp can be called at any time on an interpreter that may be
  used by nested evaluations and C code in various extensions. Tcl implements a
  simple mechanism that allows callers to use interpreters without worrying
  about the interpreter being deleted in a nested call, and without requiring
  special code to protect the interpreter, in most cases. This mechanism ensures
  that nested uses of an interpreter can safely continue using it even after
  Tcl_DeleteInterp is called.


The mechanism relies on matching up calls to Tcl_Preserve with calls to
  Tcl_Release. If Tcl_DeleteInterp has been called, only when the
  last call to Tcl_Preserve is matched by a call to Tcl_Release,
  will the interpreter be freed. See the manual entry for Tcl_Preserve
  for a description of these functions.


The rules for when the user of an interpreter must call Tcl_Preserve and
  Tcl_Release are simple:


  
Interpreters Passed As Arguments

  
Functions that are passed an interpreter as an argument can safely use the
      interpreter without any special protection. Thus, when you write an
      extension consisting of new Tcl commands, no special code is needed to
      protect interpreters received as arguments. This covers the majority of
      all uses.





  
Interpreter Creation And Deletion

  
When a new interpreter is created and used in a call to Tcl_Eval,
      Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or
      Tcl_GetVar, a pair of calls to Tcl_Preserve and
      Tcl_Release should be wrapped around all uses of the interpreter.
      Remember that it is unsafe to use the interpreter once Tcl_Release
      has been called. To ensure that the interpreter is properly deleted when
      it is no longer needed, call Tcl_InterpDeleted to test if some
      other code already called Tcl_DeleteInterp; if not, call
      Tcl_DeleteInterp before calling Tcl_Release in your own
      code.





  
Retrieving An Interpreter From A Data Structure

  
When an interpreter is retrieved from a data structure (e.g. the client
      data of a callback) for use in Tcl_Eval, Tcl_VarEval,
      Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of
      calls to Tcl_Preserve and Tcl_Release should be wrapped
      around all uses of the interpreter; it is unsafe to reuse the interpreter
      once Tcl_Release has been called. If an interpreter is stored
      inside a callback data structure, an appropriate deletion cleanup
      mechanism should be set up by the code that creates the data structure so
      that the interpreter is removed from the data structure (e.g. by setting
      the field to NULL) when the interpreter is deleted. Otherwise, you may be
      using an interpreter that has been freed and whose memory may already have
      been reused.





All uses of interpreters in Tcl and Tk have already been protected. Extension
  writers should ensure that their code also properly protects any additional
  interpreters used, as described above.



SEE ALSO

Tcl_Preserve(3tcl), Tcl_Release(3tcl)



KEYWORDS

command, create, delete, interpreter



  

    7.5
    Tcl