Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_InterpDeleted

TclCreateInterp(3) Tcl Library Procedures TclCreateInterp(3)

NAME

TclCreateInterp, TclDeleteInterp, TclInterpDeleted - create and

delete Tcl command interpreters

SYNOPSIS

##iinncclluuddee <>

TclInterp * TTccllCCrreeaatteeIInntteerrpp() TTccllDDeelleetteeIInntteerrpp(interp) int TTccllIInntteerrppDDeelleetteedd(interp) AARRGGUUMMEENNTTSS TclInterp *interp (in) Token for interpreter to be destroyed.

DESCRIPTION

TTccllCCrreeaatteeIInntteerrpp creates a new interpreter structure and returns a

token for it. The token is required in calls to most other Tcl proce-

dures, such as TTccllCCrreeaatteeCCoommmmaanndd, TTccllEEvvaall, and TTccllDDeelleetteeIInntteerrpp. Clients are only allowed to access a few of the fields of TclInterp structures; see the TTccllIInntteerrpp and TTccllCCrreeaatteeCCoommmmaanndd man pages for

details. The new interpreter is initialized with the built-in Tcl com-

mands and with the variables documented in tclvars(n). To bind in additional commands, call TTccllCCrreeaatteeCCoommmmaanndd. TTccllDDeelleetteeIInntteerrpp marks an interpreter as deleted; the interpreter will eventually be deleted when all calls to TTccllPPrreesseerrvvee for it have been matched by calls to TTccllRReelleeaassee. At that time, all of the resources

associated with it, including variables, procedures, and application-

specific command bindings, will be deleted. After TTccllDDeelleetteeIInntteerrpp returns any attempt to use TTccllEEvvaall on the interpreter will fail and return TTCCLLEERRRROORR. After the call to TTccllDDeelleetteeIInntteerrpp 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 evalu-

ation stack. See below, in the section IINNTTEERRPPRREETTEERRSS AANNDD MMEEMMOORRYY MMAANNAAGGEE-

MMEENNTT for details. TTccllIInntteerrppDDeelleetteedd returns nonzero if TTccllDDeelleetteeIInntteerrpp was called with

interp as its argument; this indicates that the interpreter will even-

tually be deleted, when the last call to TTccllPPrreesseerrvvee for it is matched by a call to TTccllRReelleeaassee. If nonzero is returned, further calls to TTccllEEvvaall in this interpreter will return TTCCLLEERRRROORR. TTccllIInntteerrppDDeelleetteedd 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. IINNTTEERRPPRREETTEERRSS AANNDD MMEEMMOORRYY MMAANNAAGGEEMMEENNTT TTccllDDeelleetteeIInntteerrpp 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 TTccllDDeelleetteeIInntteerrpp is called. The mechanism relies on matching up calls to TTccllPPrreesseerrvvee with calls to TTccllRReelleeaassee. If TTccllDDeelleetteeIInntteerrpp has been called, only when the last call to TTccllPPrreesseerrvvee is matched by a call to TTccllRReelleeaassee, will the interpreter be freed. See the manual entry for TTccllPPrreesseerrvvee for a description of these functions. The rules for when the user of an interpreter must call TTccllPPrreesseerrvvee and TTccllRReelleeaassee 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 argu-

ments. This covers the majority of all uses. Interpreter Creation And Deletion When a new interpreter is created and used in a call to

TTccllEEvvaall, TTccllVVaarrEEvvaall, TTccllGGlloobbaallEEvvaall, TTccllSSeettVVaarr, or TTccllGGeett-

VVaarr, a pair of calls to TTccllPPrreesseerrvvee and TTccllRReelleeaassee should be wrapped around all uses of the interpreter. Remember that it is unsafe to use the interpreter once TTccllRReelleeaassee has been called. To ensure that the interpreter is properly deleted when it is no longer needed, call TTccllIInntteerrppDDeelleetteedd to test if some other code already called TTccllDDeelleetteeIInntteerrpp; if not, call TTccllDDeelleetteeIInntteerrpp before calling TTccllRReelleeaassee 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 TTccllEEvvaall, TTccllVVaarrEEvvaall, TTccllGGlloobbaallEEvvaall, TTccllSSeettVVaarr, or TTccllGGeettVVaarr, a pair of calls to TTccllPPrreesseerrvvee and TTccllRReelleeaassee should be wrapped around all uses of the interpreter; it is unsafe to reuse the interpreter once TTccllRReelleeaassee has been called. If an interpreter is stored inside

a callback data structure, an appropriate deletion cleanup mech-

anism should be set up by the code that creates the data struc-

ture 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.