通讯编程

开发平台：
Visual C++

CrtInterp.3：源码内容
							'"
'" 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.7 2002/06/26 11:50:52 msofer 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 <tcl.h>fR
.sp
Tcl_Interp *
fBTcl_CreateInterpfR()
.sp
fBTcl_DeleteInterpfR(fIinterpfR)
.sp
int
fBTcl_InterpDeletedfR(fIinterpfR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Token for interpreter to be destroyed.
.BE
.SH DESCRIPTION
.PP
fBTcl_CreateInterpfR 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_CreateCommandfR, fBTcl_EvalfR, and
fBTcl_DeleteInterpfR.
Clients are only allowed to access a few of the fields of
Tcl_Interp structures;  see the fBTcl_InterpfR
and fBTcl_CreateCommandfR man pages for details.
The new interpreter is initialized with the built-in Tcl commands
and with the variables documented in tclvars(n).  To bind in
additional commands, call fBTcl_CreateCommandfR.
.PP
fBTcl_DeleteInterpfR marks an interpreter as deleted; the interpreter
will eventually be deleted when all calls to fBTcl_PreservefR for it have
been matched by calls to fBTcl_ReleasefR. At that time, all of the
resources associated with it, including variables, procedures, and
application-specific command bindings, will be deleted.  After
fBTcl_DeleteInterpfR returns any attempt to use fBTcl_EvalfR on the
interpreter will fail and return fBTCL_ERRORfR. After the call to
fBTcl_DeleteInterpfR 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 fBINTERPRETERS AND MEMORY MANAGEMENTfR for details.
.PP
fBTcl_InterpDeletedfR returns nonzero if fBTcl_DeleteInterpfR was
called with fIinterpfR as its argument; this indicates that the
interpreter will eventually be deleted, when the last call to
fBTcl_PreservefR for it is matched by a call to fBTcl_ReleasefR. If
nonzero is returned, further calls to fBTcl_EvalfR in this interpreter
will return fBTCL_ERRORfR.
.PP
fBTcl_InterpDeletedfR 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_DeleteInterpfR 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_DeleteInterpfR is called.
.PP
The mechanism relies on matching up calls to fBTcl_PreservefR with calls
to fBTcl_ReleasefR. If fBTcl_DeleteInterpfR has been called, only when
the last call to fBTcl_PreservefR is matched by a call to
fBTcl_ReleasefR, will the interpreter be freed. See the manual entry for
fBTcl_PreservefR for a description of these functions.
.PP
The rules for when the user of an interpreter must call fBTcl_PreservefR
and fBTcl_ReleasefR 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_EvalfR,
fBTcl_VarEvalfR, fBTcl_GlobalEvalfR, fBTcl_SetVarfR, or
fBTcl_GetVarfR, a pair of calls to fBTcl_PreservefR and
fBTcl_ReleasefR should be wrapped around all uses of the interpreter.
Remember that it is unsafe to use the interpreter once fBTcl_ReleasefR
has been called. To ensure that the interpreter is properly deleted when
it is no longer needed, call fBTcl_InterpDeletedfR to test if some other
code already called fBTcl_DeleteInterpfR; if not, call
fBTcl_DeleteInterpfR before calling fBTcl_ReleasefR in your own code.
.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_EvalfR, fBTcl_VarEvalfR,
fBTcl_GlobalEvalfR, fBTcl_SetVarfR, or fBTcl_GetVarfR, a pair of
calls to fBTcl_PreservefR and fBTcl_ReleasefR should be wrapped around
all uses of the interpreter; it is unsafe to reuse the interpreter once
fBTcl_ReleasefR 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 "SEE ALSO"
Tcl_Preserve(3), Tcl_Release(3)
.SH KEYWORDS
command, create, delete, interpreter

						