Version 31 of itcl internals

Updated 2008-10-12 12:11:24 by apw

apw 2008-10-04: This page is intended for collecting some of the internals of itcl for being able to discuss some wanted enhancements in Tcl core for use by itcl.

At the moment I am just dumping my ideas.

Classes in itcl are always handled as namespaces, that means every class in itcl corresponds to a namespace with the same name.

Example for classes used later on:

 ::itcl::class ::ns1::cl1 {
     # class commons
     public common c1pub c1pub
     protected common c1pro c1pro
     private common c1pri c1pri

     # class variables
     public variable v1pub v1pub
     protected variable v1pro v1pro
     private variable v1pri v1pri

     # class procs
     public proc p1pub {args} { puts stderr "p1pub" }
     protected proc p1pro {args} { puts stderr "p1pro" }
     private proc p1pri {args} { puts stderr "p1pri" }

     # class methods
     public method m1pub {args} { puts stderr "m1pub" }
     protected method m1pro {args} { puts stderr "m1pro" }
     private method m1pri {args} { puts stderr "m1pri" }
 }

 ::itcl::class cl2 {
    inherit ::ns1::cl1

     # class commons
     public common c2pub c2pub
     protected common c2pro c2pro
     private common c2pri c2pri

     # class variables
     public variable v2pub v2pub
     protected variable v2pro v2pro
     private variable v2pri v2pri

     # class procs
     public proc p2pub {args} { puts stderr "p2pub" }
     protected proc p2pro {args} { puts stderr "p2pro" }
     private proc p2pri {args} { puts stderr "p2pri" }

     # class methods
     public method m2pub {args} { puts stderr "m2pub" }
     protected method m2pro {args} { puts stderr "m2pro" }
     private method m2pri {args} { puts stderr "m2pri" }

 }

 ::itcl::class cl3 {
    inherit cl2

     # class commons
     public common c3pub c3pub
     protected common c3pro c3pro
     private common c3pri c3pri

     # class variables
     public variable v3pub v3pub
     protected variable v3pro v3pro
     private variable v3pri v3pri

     # class procs
     public proc p3pub {args} { puts stderr "p3pub" }
     protected proc p3pro {args} { puts stderr "p3pro" }
     private proc p3pri {args} { puts stderr "p3pri" }

     # class methods
     public method m3pub {args} { puts stderr "m3pub" }
     protected method m3pro {args} { puts stderr "m3pro" }
     private method m3pri {args} { puts stderr "m3pri" }

 }

 cl1 obja
 cl2 objb
 cl3 objc

The example code above will create namespaces (and classes) ::cl1, ::cl2 and ::cl3

The inherit command determines how the class hierarchy is built. In the above case cl3 inherits cl2 (has a "superclass" cl2) and cl2 inherits cl1.

So the hierarchy from base class to most specific class is: cl1 -> cl2 -> cl3.

Or to say it differently class cl2 is derived from class cl1 and class cl3 is derived from class cl2.

This is mostly equivalent with setting namespace path for class (namespace) cl3 to: [list cl3 cl2 cl1].

We have also created 3 itcl objects obja, objb, objc with the last 3 leines in the example code.

Methods in itcl classes are similar to procs with the difference, that they only can be called from an object created for a class and they have a protection level (see below).

It is also possible to have procs in a class, these procs can be called like procs in a namespace depending on the protection level.

Variables in itcl classes are similar to namespace variables with the difference, that they only can be accessed from an object created for a class when calling a method and they have a protection level (see below).

Commons in itcl classes are similar to namespace variables and they can be accessed like namespace variables depending on the protection level. So the lookup of methods and variables is done starting in namespace cl3, then cl2 and then cl1.

As every method in itcl is called in the namespace of its class lookup for variables and methods for a method in class cl2 starts in cl2 and continues in cl1.

Calling a method in cl3 starts lookup in cl3, then cl2 and then cl1.

Protection levels:

Itcl has 3 protection levels:

  • public
  • protected
  • private.

public protection level allows to access a variable from every method or proc tied to an itcl object and from the outside using the special methods configure and cget of an itcl object.

protected protection level allows to access a variable from every method or proc tied to an itcl object in the class where it is defined and in all derived classes.

private protection level allows to access a variable from every method or proc tied to an itcl object only in the class where it is defined.

The same definition as for variables holds for commons with the difference, that instead of an object the class(namespace) must be used.

Lookup rules for itcl:

In general for looking up methods/procs and variables/commons so called "virtual tables" are used. Virtual tables exist on a class base for methods/procs and variables/commons.

In the following command means an itcl class method or proc and variable means an itcl class variable or common. Member is the command or variable name.

The current rule is: These tables store every possible name for each command/variable (member, class::member, namesp::class::member, etc.). Members in a derived class may shadow members with the same name in a base class. In that case, the simple name in the resolution table will point to the most-specific member.

Example for the class cl2 methods/procs entries in a virtual table:

  • p1pub
  • cl1::p1pub
  • ns1::cl1::p1pub
  • ::ns1::cl1::p1pub
  • p1pro
  • cl1::p1pro
  • ns1::cl1::p1pro
  • ::ns1::cl1::p1pro
  • p1pri
  • cl1::p1pri
  • ns1::cl1::p1pri
  • ::ns1::cl1::p1pri
  • m1pub
  • cl1::m1pub
  • ns1::cl1::m1pub
  • ::ns1::cl1::m1pub
  • m1pro
  • cl1::m1pro
  • ns1::cl1::m1pro
  • ::ns1::cl1::m1pro
  • m1pri
  • cl1::m1pri
  • ns1::cl1::m1pri
  • ::ns1::cl1::m1pri
  • p2pub
  • cl2::p2pub
  • ::cl2::p2pub
  • p2pro
  • cl2::p2pro
  • ::cl2::p2pro
  • p2pri
  • cl2::p2pri
  • ::cl2::p2pri
  • m2pub
  • cl2::m2pub
  • ::cl2::m2pub
  • m2pro
  • cl2::m2pro
  • ::cl2::m2pro
  • m2pri
  • cl2::m2pri
  • ::cl2::m2pri

Example for the class cl2 variables/commons entries in a virtual table:

  • c1pub
  • cl1::c1pub
  • ns1::cl1::c1pub
  • ::ns1::cl1::c1pub
  • c1pro
  • cl1::c1pro
  • ns1::cl1::c1pro
  • ::ns1::cl1::c1pro
  • c1pri
  • cl1::c1pri
  • ns1::cl1::c1pri
  • ::ns1::cl1::c1pri
  • v1pub
  • cl1::v1pub
  • ns1::cl1::v1pub
  • ::ns1::cl1::v1pub
  • v1pro
  • cl1::v1pro
  • ns1::cl1::v1pro
  • ::ns1::cl1::v1pro
  • v1pri
  • cl1::v1pri
  • ns1::cl1::v1pri
  • ::ns1::cl1::v1pri
  • c2pub
  • cl2::c2pub
  • ::cl2::c2pub
  • c2pro
  • cl2::c2pro
  • ::cl2::c2pro
  • c2pri
  • cl2::c2pri
  • ::cl2::c2pri
  • v2pub
  • cl2::v2pub
  • ::cl2::v2pub
  • v2pro
  • cl2::v2pro
  • ::cl2::v2pro
  • v2pri
  • cl2::v2pri
  • ::cl2::v2pri

Wanted lookup for commands (methods/procs):

maybe similar to the handling of class variables, so I have already added most stuff there


Wanted lookup for variables (variables/commons):

The idea is to have an additional hash table (or whatever) for variables, which can be filled with a C-function like Tcl_RegisterClassVariable and Tcl_RegisterObjectVariable. There follows an example interface for such a functionality.

typedef int (TclCheckClassProtection)(Tcl_Interp *interp, Tcl_Namespace *nsPtr, const char *varName, ClientData clientData);

typedef void (*Tcl_ClassVariableDeleteProc)(ClientData clientData);

typedef void (*Tcl_ClassCommandDeleteProc)(ClientData clientData);

typedef void (*Tcl_ObjectVariableDeleteProc)(ClientData clientData);

typedef void (*Tcl_ObjectCommandDeleteProc)(ClientData clientData);

ClientData Tcl_RegisterClassVariable(Tcl_Interp *interp, Tcl_Namespace *nsPtr, const char *varName, ClientData clientData);

ClientData Tcl_RegisterClassMethod(Tcl_Interp *interp, Tcl_Namespace *nsPtr, const char *cmdName, ClientData clientData);

Tcl_Var Tcl_RegisterObjectVariable(TclInterp *interp, ClientData objectPtr, const char *varName, ClientData clientData, Tcl_Var varPtr);

Tcl_Command Tcl_RegisterObjectMethod(TclInterp *interp, ClientData objectPtr, const char *cmdName, Tcl_Command cmdPtr, ClientData clientData);

int Tcl_CheckClassVariableProtection(Tcl_interp *interp, Tcl_Namespace *nsPtr, const char *varName, ClientData clientData)

int Tcl_CheckClassCommandProtection(Tcl_interp *interp, Tcl_Namespace *nsPtr, const char *commandName, ClientData clientData)

int Tcl_SetCallFrameObject(Tcl_Interp *interp, ClientData objectPtr);

void Tcl_UnregisterClassVariable(Tcl_Interp *interp, Tcl_Namespace *nsPtr, const char *varName, Tcl_ClassVariableDeleteProc delProc);

void Tcl_UnregisterClassCommand(Tcl_Interp *interp, Tcl_Namespace *nsPtr, const char *cmdName, Tcl_ClassCommandDeleteProc delProc);

void Tcl_UnregisterObjectVariable(Tcl_Interp *interp, ClientData objectPtr, const char *varName, Tcl_ObjectVariableDeleteProc delProc);

void Tcl_UnregisterObjectCommand(Tcl_Interp *interp, ClientData objectPtr, const char *cmdName, Tcl_ObjectCommandDeleteProc delProc);

int Tcl_SetNamespaceVariableProtectionCallback(Tcl_interp *interp, Tcl_Namespace *nsPtr, TclCheckNamespaceProtection *fcnPtr)

int Tcl_SetNamespaceCommandProtectionCallback(Tcl_interp *interp, Tcl_Namespace *nsPtr, TclCheckNamespaceProtection *fcnPtr)
  • nsPtr is the class namespace to add the variable to or where the variable is declared
  • varName is the name of the variable like cl1::v1pri or v1pri (that could also be an Tcl_Obj)
  • clientData some data to be used in Tcl_CheckClassVariableProtection
  • varPtr == NULL for itcl variables, so a new variable should be created. For itcl commons varPtr != NULL, in that case the varPtr should be used instead of creating a variable.

The above interfaces are only an example how the interfaces could look like and also include some for commands, because they could be analogous.

Tcl_RegisterClassVariable makes the variables which are reachable in an Itcl class known to variable lookup per namespace (a namespace is an itcl class).

Tcl_RegisterObjectVariable creates physically variables for the Itcl class variables on a per (itcl) object base. The Tcl_HashTable or whatever is used for it has to be CallFrame dependent (calling a method must also provide that information in the CallFrame structure/environment.

Also a special CallFrame flag should be set calling an itcl method (as side effect of using Tcl_SetCallFrameObject or by having CallFrame object != NULL), to make use of the mechanism above on a CallFrame basis.

If the CallFrame flag is set, then this variable hash table, or however it is implemented, should be searched for the variable info first and if a reference is found, then the object variable table should be looked up with the reference information for the corresponding Tcl_Var and then a callback (like Tcl_CheckClassVariableProtection) should be called (if it is set). The object variables should not be visible directly in a namespace! The check call allows the caller to do a check for protection/type specific stuff. The callback either returns TCL_OK or TCL_ERROR (in that case with possibly leaving an appropriate error message in the interpreter). If the variable is not found here or the special flag in the call frame is not set, then the normal variable lookup should be done.

The callback can be set using Tcl_SetClassVariableProtectionCallback/Tcl_SetClassCommandProtectionCallback.

That would allow it to make a fast variable lookup for itcl and leave all the details to Tcl core and would additionally allow this:

  • No need for variable/command namespace/interp resolvers for itcl any longer.

I have done a prototype implementation for variables (still using namespace resolvers, but in there using the described interfaces from above) for itcl-ng which is passing the tests as before.