Subversion Repositories or1k

'\"

'\" Copyright (c) 1989-1993 The Regents of the University of California.

'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.

'\"

'\" See the file "license.terms" for information on usage and redistribution

'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

'\"

'\" RCS: @(#) $Id: CrtInterp.3,v 1.1.1.1 2002-01-16 10:25:23 markom Exp $

'\"

.so man.macros

.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"

.BS

.SH NAME

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

.SH SYNOPSIS

.nf

\fB#include \fR

.sp

Tcl_Interp *

\fBTcl_CreateInterp\fR()

.sp

\fBTcl_DeleteInterp\fR(\fIinterp\fR)

.sp

int

\fBTcl_InterpDeleted\fR(\fIinterp\fR)

.SH ARGUMENTS

.AS Tcl_Interp *interp

.AP Tcl_Interp *interp in

Token for interpreter to be destroyed.

.BE

.SH DESCRIPTION

.PP

\fBTcl_CreateInterp\fR creates a new interpreter structure and returns

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

procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and

\fBTcl_DeleteInterp\fR.

Clients are only allowed to access a few of the fields of

Tcl_Interp structures;  see the Tcl_Interp

and \fBTcl_CreateCommand\fR man pages for details.

The new interpreter is initialized with no defined variables and only

the built-in Tcl commands.  To bind in additional commands, call

\fBTcl_CreateCommand\fR.

.PP

\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter

will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have

been matched by calls to \fBTcl_Release\fR. At that time, all of the

resources associated with it, including variables, procedures, and

application-specific command bindings, will be deleted.  After

\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the

interpreter will fail and return \fBTCL_ERROR\fR. After the call to

\fBTcl_DeleteInterp\fR it is safe to examine \fIinterp->result\fR, query or

set the values of variables, define, undefine or retrieve procedures, and

examine the runtime evaluation stack. See below, in the section

\fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.

.PP

\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was

called with \fIinterp\fR as its argument; this indicates that the

interpreter will eventually be deleted, when the last call to

\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If

nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter

will return \fBTCL_ERROR\fR.

.PP

\fBTcl_InterpDeleted\fR 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.

.SH "INTERPRETERS AND MEMORY MANAGEMENT"

.PP

\fBTcl_DeleteInterp\fR 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 \fBTcl_DeleteInterp\fR is called.

.PP

The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls

to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when

the last call to \fBTcl_Preserve\fR is matched by a call to

\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for

\fBTcl_Preserve\fR for a description of these functions.

.PP

The rules for when the user of an interpreter must call \fBTcl_Preserve\fR

and \fBTcl_Release\fR are simple:

.TP

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.

.TP

Interpreter Creation And Deletion

When a new interpreter is created and used in a call to \fBTcl_Eval\fR,

\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or

\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and

\fBTcl_Release\fR should be wrapped around all uses of the interpreter.

Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR

has been called. To ensure that the interpreter is properly deleted when

it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other

code already called \fBTcl_DeleteInterp\fR; if not, call

\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.

Do not call \fBTcl_DeleteInterp\fR on an interpreter for which

\fBTcl_InterpDeleted\fR returns nonzero.

.TP

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 \fBTcl_Eval\fR, \fBTcl_VarEval\fR,

\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of

calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around

all uses of the interpreter; it is unsafe to reuse the interpreter once

\fBTcl_Release\fR 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.

.PP

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.

.SH KEYWORDS

command, create, delete, interpreter

.SH "SEE ALSO"

Tcl_Preserve(3), Tcl_Release(3)