/*

 * tclInt.h --

 *

 *	Declarations of things used internally by the Tcl interpreter.

 *

 * Copyright (c) 1987-1993 The Regents of the University of California.

 * Copyright (c) 1993-1997 Lucent Technologies.

 * Copyright (c) 1994-1998 Sun Microsystems, Inc.

 * Copyright (c) 1998-1999 by Scriptics Corporation.

 * Copyright (c) 2001, 2002 by Kevin B. Kenny.  All rights reserved.

 * Portions Copyright (c) 2007 Nokia Corporation and/or its subsidiaries. All rights reserved.  

 *

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

 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.

 *

 * RCS: @(#) $Id: tclInt.h,v 1.118.2.28 2007/05/10 21:32:17 dgp Exp $

 */

#ifndef _TCLINT

#define _TCLINT

/*

 * Common include files needed by most of the Tcl source files are

 * included here, so that system-dependent personalizations for the

 * include files only have to be made in once place.  This results

 * in a few extra includes, but greater modularity.  The order of

 * the three groups of #includes is important.	For example, stdio.h

 * is needed by tcl.h, and the _ANSI_ARGS_ declaration in tcl.h is

 * needed by stdlib.h in some configurations.

 */

#ifndef _TCL

#include "tcl.h"

#endif

#include <stdio.h>

#include <ctype.h>

#ifdef NO_LIMITS_H

#   include "../compat/limits.h"

#else

#   include <limits.h>

#endif

#ifdef NO_STDLIB_H

#   include "../compat/stdlib.h"

#else

#   include <stdlib.h>

#endif

#ifdef NO_STRING_H

#include "../compat/string.h"

#else

#include <string.h>

#endif

/*

 * Ensure WORDS_BIGENDIAN is defined correcly:

 * Needs to happen here in addition to configure to work with fat compiles on

 * Darwin (where configure runs only once for multiple architectures).

 */

#ifdef HAVE_SYS_TYPES_H

#    include <sys/types.h>

#endif

#ifdef HAVE_SYS_PARAM_H

#    include <sys/param.h>

#endif

#ifdef BYTE_ORDER

#    ifdef BIG_ENDIAN

#        if BYTE_ORDER == BIG_ENDIAN

#            undef WORDS_BIGENDIAN

#            define WORDS_BIGENDIAN

#        endif

#    endif

#    ifdef LITTLE_ENDIAN

#        if BYTE_ORDER == LITTLE_ENDIAN

#            undef WORDS_BIGENDIAN

#        endif

#    endif

#endif

/*

 * Used to tag functions that are only to be visible within the module being

 * built and not outside it (where this is supported by the linker).

 */

#ifndef MODULE_SCOPE

#   ifdef __cplusplus

#	define MODULE_SCOPE extern "C"

#   else

#	define MODULE_SCOPE extern

#   endif

#endif

#undef TCL_STORAGE_CLASS

#ifdef BUILD_tcl

# define TCL_STORAGE_CLASS DLLEXPORT

#else

# ifdef USE_TCL_STUBS

#  define TCL_STORAGE_CLASS

# else

#  define TCL_STORAGE_CLASS DLLIMPORT

# endif

#endif

/*

 * The following procedures allow namespaces to be customized to

 * support special name resolution rules for commands/variables.

 * 

 */

struct Tcl_ResolvedVarInfo;

typedef Tcl_Var (Tcl_ResolveRuntimeVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, struct Tcl_ResolvedVarInfo *vinfoPtr));

typedef void (Tcl_ResolveVarDeleteProc) _ANSI_ARGS_((

    struct Tcl_ResolvedVarInfo *vinfoPtr));

/*

 * The following structure encapsulates the routines needed to resolve a

 * variable reference at runtime.  Any variable specific state will typically

 * be appended to this structure.

 */

typedef struct Tcl_ResolvedVarInfo {

    Tcl_ResolveRuntimeVarProc *fetchProc;

    Tcl_ResolveVarDeleteProc *deleteProc;

} Tcl_ResolvedVarInfo;

typedef int (Tcl_ResolveCompiledVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, CONST84 char* name, int length,

    Tcl_Namespace *context, Tcl_ResolvedVarInfo **rPtr));

typedef int (Tcl_ResolveVarProc) _ANSI_ARGS_((

    Tcl_Interp* interp, CONST84 char* name, Tcl_Namespace *context,

    int flags, Tcl_Var *rPtr));

typedef int (Tcl_ResolveCmdProc) _ANSI_ARGS_((Tcl_Interp* interp,

    CONST84 char* name, Tcl_Namespace *context, int flags,

    Tcl_Command *rPtr));

typedef struct Tcl_ResolverInfo {

    Tcl_ResolveCmdProc *cmdResProc;	/* Procedure handling command name

					 * resolution. */

    Tcl_ResolveVarProc *varResProc;	/* Procedure handling variable name

					 * resolution for variables that

					 * can only be handled at runtime. */

    Tcl_ResolveCompiledVarProc *compiledVarResProc;

					/* Procedure handling variable name

					 * resolution at compile time. */

} Tcl_ResolverInfo;

/*

 *----------------------------------------------------------------

 * Data structures related to namespaces.

 *----------------------------------------------------------------

 */

/*

 * The structure below defines a namespace.

 * Note: the first five fields must match exactly the fields in a

 * Tcl_Namespace structure (see tcl.h). If you change one, be sure to

 * change the other.

 */

typedef struct Namespace {

    char *name;			 /* The namespace's simple (unqualified)

				  * name. This contains no ::'s. The name of

				  * the global namespace is "" although "::"

				  * is an synonym. */

    char *fullName;		 /* The namespace's fully qualified name.

				  * This starts with ::. */

    ClientData clientData;	 /* An arbitrary value associated with this

				  * namespace. */

    Tcl_NamespaceDeleteProc *deleteProc;

				 /* Procedure invoked when deleting the

				  * namespace to, e.g., free clientData. */

    struct Namespace *parentPtr; /* Points to the namespace that contains

				  * this one. NULL if this is the global

				  * namespace. */

    Tcl_HashTable childTable;	 /* Contains any child namespaces. Indexed

				  * by strings; values have type

				  * (Namespace *). */

    long nsId;			 /* Unique id for the namespace. */

    Tcl_Interp *interp;		 /* The interpreter containing this

				  * namespace. */

    int flags;			 /* OR-ed combination of the namespace

				  * status flags NS_DYING and NS_DEAD

				  * listed below. */

    int activationCount;	 /* Number of "activations" or active call

				  * frames for this namespace that are on

				  * the Tcl call stack. The namespace won't

				  * be freed until activationCount becomes

				  * zero. */

    int refCount;		 /* Count of references by namespaceName *

				  * objects. The namespace can't be freed

				  * until refCount becomes zero. */

    Tcl_HashTable cmdTable;	 /* Contains all the commands currently

				  * registered in the namespace. Indexed by

				  * strings; values have type (Command *).

				  * Commands imported by Tcl_Import have

				  * Command structures that point (via an

				  * ImportedCmdRef structure) to the

				  * Command structure in the source

				  * namespace's command table. */

    Tcl_HashTable varTable;	 /* Contains all the (global) variables

				  * currently in this namespace. Indexed

				  * by strings; values have type (Var *). */

    char **exportArrayPtr;	 /* Points to an array of string patterns

				  * specifying which commands are exported.

				  * A pattern may include "string match"

				  * style wildcard characters to specify

				  * multiple commands; however, no namespace

				  * qualifiers are allowed. NULL if no

				  * export patterns are registered. */

    int numExportPatterns;	 /* Number of export patterns currently

				  * registered using "namespace export". */

    int maxExportPatterns;	 /* Mumber of export patterns for which

				  * space is currently allocated. */

    int cmdRefEpoch;		 /* Incremented if a newly added command

				  * shadows a command for which this

				  * namespace has already cached a Command *

				  * pointer; this causes all its cached

				  * Command* pointers to be invalidated. */

    int resolverEpoch;		 /* Incremented whenever (a) the name resolution

				  * rules change for this namespace or (b) a 

				  * newly added command shadows a command that

				  * is compiled to bytecodes.

				  * This invalidates all byte codes compiled

				  * in the namespace, causing the code to be

				  * recompiled under the new rules.*/

    Tcl_ResolveCmdProc *cmdResProc;

				 /* If non-null, this procedure overrides

				  * the usual command resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within Tcl_FindCommand to resolve all

				  * command references within the namespace. */

    Tcl_ResolveVarProc *varResProc;

				 /* If non-null, this procedure overrides

				  * the usual variable resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within Tcl_FindNamespaceVar to resolve all

				  * variable references within the namespace

				  * at runtime. */

    Tcl_ResolveCompiledVarProc *compiledVarResProc;

				 /* If non-null, this procedure overrides

				  * the usual variable resolution mechanism

				  * in Tcl.  This procedure is invoked

				  * within LookupCompiledLocal to resolve

				  * variable references within the namespace

				  * at compile time. */

} Namespace;

/*

 * Flags used to represent the status of a namespace:

 *

 * NS_DYING -	1 means Tcl_DeleteNamespace has been called to delete the

 *		namespace but there are still active call frames on the Tcl

 *		stack that refer to the namespace. When the last call frame

 *		referring to it has been popped, it's variables and command

 *		will be destroyed and it will be marked "dead" (NS_DEAD).

 *		The namespace can no longer be looked up by name.

 * NS_DEAD -	1 means Tcl_DeleteNamespace has been called to delete the

 *		namespace and no call frames still refer to it. Its

 *		variables and command have already been destroyed. This bit

 *		allows the namespace resolution code to recognize that the

 *		namespace is "deleted". When the last namespaceName object

 *		in any byte code code unit that refers to the namespace has

 *		been freed (i.e., when the namespace's refCount is 0), the

 *		namespace's storage will be freed.

 * NS_KILLED    1 means that TclTeardownNamespace has already been called on

 *              this namespace and it should not be called again [Bug 1355942]

 */

#define NS_DYING	0x01

#define NS_DEAD		0x02

#define NS_KILLED       0x04

/*

 * Flag passed to TclGetNamespaceForQualName to have it create all namespace

 * components of a namespace-qualified name that cannot be found. The new

 * namespaces are created within their specified parent. Note that this

 * flag's value must not conflict with the values of the flags

 * TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY, and FIND_ONLY_NS (defined in

 * tclNamesp.c).

 */

#define CREATE_NS_IF_UNKNOWN 0x800

/*

 *----------------------------------------------------------------

 * Data structures related to variables.   These are used primarily

 * in tclVar.c

 *----------------------------------------------------------------

 */

/*

 * The following structure defines a variable trace, which is used to

 * invoke a specific C procedure whenever certain operations are performed

 * on a variable.

 */

typedef struct VarTrace {

    Tcl_VarTraceProc *traceProc;/* Procedure to call when operations given

				 * by flags are performed on variable. */

    ClientData clientData;	/* Argument to pass to proc. */

    int flags;			/* What events the trace procedure is

				 * interested in:  OR-ed combination of

				 * TCL_TRACE_READS, TCL_TRACE_WRITES,

				 * TCL_TRACE_UNSETS and TCL_TRACE_ARRAY. */

    struct VarTrace *nextPtr;	/* Next in list of traces associated with

				 * a particular variable. */

} VarTrace;

/*

 * The following structure defines a command trace, which is used to

 * invoke a specific C procedure whenever certain operations are performed

 * on a command.

 */

typedef struct CommandTrace {

    Tcl_CommandTraceProc *traceProc;/* Procedure to call when operations given

				     * by flags are performed on command. */

    ClientData clientData;	    /* Argument to pass to proc. */

    int flags;			    /* What events the trace procedure is

				     * interested in:  OR-ed combination of

				     * TCL_TRACE_RENAME, TCL_TRACE_DELETE. */

    struct CommandTrace *nextPtr;   /* Next in list of traces associated with

				     * a particular command. */

    int refCount;                   /* Used to ensure this structure is

                                     * not deleted too early.  Keeps track

                                     * of how many pieces of code have

                                     * a pointer to this structure. */

} CommandTrace;

/*

 * When a command trace is active (i.e. its associated procedure is

 * executing), one of the following structures is linked into a list

 * associated with the command's interpreter.  The information in

 * the structure is needed in order for Tcl to behave reasonably

 * if traces are deleted while traces are active.

 */

typedef struct ActiveCommandTrace {

    struct Command *cmdPtr;	/* Command that's being traced. */

    struct ActiveCommandTrace *nextPtr;

				/* Next in list of all active command

				 * traces for the interpreter, or NULL

				 * if no more. */

    CommandTrace *nextTracePtr;	/* Next trace to check after current

				 * trace procedure returns;  if this

				 * trace gets deleted, must update pointer

				 * to avoid using free'd memory. */

    int reverseScan;		/* Boolean set true when the traces

				 * are scanning in reverse order. */

} ActiveCommandTrace;

/*

 * When a variable trace is active (i.e. its associated procedure is

 * executing), one of the following structures is linked into a list

 * associated with the variable's interpreter.	The information in

 * the structure is needed in order for Tcl to behave reasonably

 * if traces are deleted while traces are active.

 */

typedef struct ActiveVarTrace {

    struct Var *varPtr;		/* Variable that's being traced. */

    struct ActiveVarTrace *nextPtr;

				/* Next in list of all active variable

				 * traces for the interpreter, or NULL

				 * if no more. */

    VarTrace *nextTracePtr;	/* Next trace to check after current

				 * trace procedure returns;  if this

				 * trace gets deleted, must update pointer

				 * to avoid using free'd memory. */

} ActiveVarTrace;

/*

 * The following structure describes an enumerative search in progress on

 * an array variable;  this are invoked with options to the "array"

 * command.

 */

typedef struct ArraySearch {

    int id;			/* Integer id used to distinguish among

				 * multiple concurrent searches for the

				 * same array. */

    struct Var *varPtr;		/* Pointer to array variable that's being

				 * searched. */

    Tcl_HashSearch search;	/* Info kept by the hash module about

				 * progress through the array. */

    Tcl_HashEntry *nextEntry;	/* Non-null means this is the next element

				 * to be enumerated (it's leftover from

				 * the Tcl_FirstHashEntry call or from

				 * an "array anymore" command).	 NULL

				 * means must call Tcl_NextHashEntry

				 * to get value to return. */

    struct ArraySearch *nextPtr;/* Next in list of all active searches

				 * for this variable, or NULL if this is

				 * the last one. */

} ArraySearch;

/*

 * The structure below defines a variable, which associates a string name

 * with a Tcl_Obj value. These structures are kept in procedure call frames

 * (for local variables recognized by the compiler) or in the heap (for

 * global variables and any variable not known to the compiler). For each

 * Var structure in the heap, a hash table entry holds the variable name and

 * a pointer to the Var structure.

 */

typedef struct Var {

    union {

	Tcl_Obj *objPtr;	/* The variable's object value. Used for 

				 * scalar variables and array elements. */

	Tcl_HashTable *tablePtr;/* For array variables, this points to

				 * information about the hash table used

				 * to implement the associative array. 

				 * Points to malloc-ed data. */

	struct Var *linkPtr;	/* If this is a global variable being

				 * referred to in a procedure, or a variable

				 * created by "upvar", this field points to

				 * the referenced variable's Var struct. */

    } value;

    char *name;			/* NULL if the variable is in a hashtable,

				 * otherwise points to the variable's

				 * name. It is used, e.g., by TclLookupVar

				 * and "info locals". The storage for the

				 * characters of the name is not owned by

				 * the Var and must not be freed when

				 * freeing the Var. */

    Namespace *nsPtr;		/* Points to the namespace that contains

				 * this variable or NULL if the variable is

				 * a local variable in a Tcl procedure. */

    Tcl_HashEntry *hPtr;	/* If variable is in a hashtable, either the

				 * hash table entry that refers to this

				 * variable or NULL if the variable has been

				 * detached from its hash table (e.g. an

				 * array is deleted, but some of its

				 * elements are still referred to in

				 * upvars). NULL if the variable is not in a

				 * hashtable. This is used to delete an

				 * variable from its hashtable if it is no

				 * longer needed. */

    int refCount;		/* Counts number of active uses of this

				 * variable, not including its entry in the

				 * call frame or the hash table: 1 for each

				 * additional variable whose linkPtr points

				 * here, 1 for each nested trace active on

				 * variable, and 1 if the variable is a 

				 * namespace variable. This record can't be

				 * deleted until refCount becomes 0. */

    VarTrace *tracePtr;		/* First in list of all traces set for this

				 * variable. */

    ArraySearch *searchPtr;	/* First in list of all searches active

				 * for this variable, or NULL if none. */

    int flags;			/* Miscellaneous bits of information about

				 * variable. See below for definitions. */

} Var;

/*

 * Flag bits for variables. The first three (VAR_SCALAR, VAR_ARRAY, and

 * VAR_LINK) are mutually exclusive and give the "type" of the variable.

 * VAR_UNDEFINED is independent of the variable's type. 

 *

 * VAR_SCALAR -			1 means this is a scalar variable and not

 *				an array or link. The "objPtr" field points

 *				to the variable's value, a Tcl object.

 * VAR_ARRAY -			1 means this is an array variable rather

 *				than a scalar variable or link. The

 *				"tablePtr" field points to the array's

 *				hashtable for its elements.

 * VAR_LINK -			1 means this Var structure contains a

 *				pointer to another Var structure that

 *				either has the real value or is itself

 *				another VAR_LINK pointer. Variables like

 *				this come about through "upvar" and "global"

 *				commands, or through references to variables

 *				in enclosing namespaces.

 * VAR_UNDEFINED -		1 means that the variable is in the process

 *				of being deleted. An undefined variable

 *				logically does not exist and survives only

 *				while it has a trace, or if it is a global

 *				variable currently being used by some

 *				procedure.

 * VAR_IN_HASHTABLE -		1 means this variable is in a hashtable and

 *				the Var structure is malloced. 0 if it is

 *				a local variable that was assigned a slot

 *				in a procedure frame by	the compiler so the

 *				Var storage is part of the call frame.

 * VAR_TRACE_ACTIVE -		1 means that trace processing is currently

 *				underway for a read or write access, so

 *				new read or write accesses should not cause

 *				trace procedures to be called and the

 *				variable can't be deleted.

 * VAR_ARRAY_ELEMENT -		1 means that this variable is an array

 *				element, so it is not legal for it to be

 *				an array itself (the VAR_ARRAY flag had

 *				better not be set).

 * VAR_NAMESPACE_VAR -		1 means that this variable was declared

 *				as a namespace variable. This flag ensures

 *				it persists until its namespace is

 *				destroyed or until the variable is unset;

 *				it will persist even if it has not been

 *				initialized and is marked undefined.

 *				The variable's refCount is incremented to

 *				reflect the "reference" from its namespace.

 *

 * The following additional flags are used with the CompiledLocal type

 * defined below:

 *

 * VAR_ARGUMENT -		1 means that this variable holds a procedure

 *				argument. 

 * VAR_TEMPORARY -		1 if the local variable is an anonymous

 *				temporary variable. Temporaries have a NULL

 *				name.

 * VAR_RESOLVED -		1 if name resolution has been done for this

 *				variable.

 */

#define VAR_SCALAR		0x1

#define VAR_ARRAY		0x2

#define VAR_LINK		0x4

#define VAR_UNDEFINED		0x8

#define VAR_IN_HASHTABLE	0x10