2.10.1 Interface Declarations

In addition to the declarations allowed in class contexts, interface classes may contain so called interface declarations. An interface declaration describes a procedure contained in an extension object. Any number of interface procedures may be declared in a single IDECL statement:

IDECL proc_name(type, call_map), ...;

Proc_name is the name of an interface proecedure to declare and type is the number of arguments of that procedure. Call_map describes the types of the parameters passed to the interface procedure. It is a bit map where each bit is associated with a procedure argument as outlined in the following table.

Each bit with a zero value denotes an atomic (numeric) argument and each bit with a one value denotes a vector argument (a pointer in the argument list of a orresponding C function). For example, the C function system__spawn() implementing the _spawn() function of the system extension object could be defined as follows:

XCELL system__spawn S3(char *prog, char **args, XCELL wait) {
        /* code of system__spawn() */
}

The S3() macro is used to generate lists of three arguments. Similar macros exist for declarations of functions with up to 7 arguments. They are called S0(), ..., S7(). The Sn() macros reverse the supplied argument lists to meet the T3X calling conventions and supply a dummy argument to intercept the additional instance context parameter which T3X programs pass to each method.

The Sn() macros expect ANSI-style function defintions. K&R-style function definitions are no longer supported.

Do use the Sn() macros. Otherwise, interface procedures will not work.

XCELL is a macro expanding to the type of a signed cell (integer) of the same size as a pointer.

All macros discussed here are defined in the 'txx.h' header file. The 'txx.h' file also contains some other macros which are useful for implementing interface procedures.

The first and second argument of _spawn() are pointers and so the bits 0x0001 and 0x0002 in the call map have to be set. This leads to the following interface declaration:

CLASS system("system")
 ...
 IDECL _spawn(3,0x0003);
 ...
END

The call map is required to export vector addresses of Tcode programs to the global address space before passing them to interface procedures. Call maps are limited to 16 bits, so interface procedures may not have more than 16 arguments.

NOTE: when passing vectors of pointers to interface procedures, the pointers contained in the vector must be exported to the global address space, too. The T3X core method T3X.CVALIST performs this operation.