[INRIA]
[LORIA]




->Wiki
->FAQ
->Lib doc.
->Tools doc.
->Mailing list
->Bug reports
->Papers
->Download
->SCM Inria
->People
->Home (http)
->Home


About the Generated C Code



People who want or have to code part of their applications and/or libraries in C should really limit themselves to the clean interfaces provided by Cecil or the external mechanism. This page mentions some facts you should be aware of before you start.

Generated Type Identifiers

First and above all, SmartEiffel generates one unique numeric identifier for each living type1 present in the Eiffel code. A lot of symbols in the generated C code depend on that identifier.

Don't depend on those identifiers! The mangling table is only valid for one specific compilation of one specific application with one specific compiler version and specific libraries...

If xyz is the identifier, then:

  • The type of an Eiffel object is Txyz;
  • The corresponding structure is Sxyz; in that structure, the names of the attributes are prefixed with an underscore (there may be some other fields, usually the first being id used by SmartEiffel for bookkeeping);
  • Each reference type can be cast in T0 (but some reference type may not have the id field):
    typedef int Tid;
    typedef struct S0 T0;
    struct S0{Tid id;};
    
  • Each method is named rxyzmethodname();
  • Each prefix method is named rxyz_px_methodname();
  • Each infix method is named rxyz_ix_methodname();
  • Each late-binding method is named Xxyzmethodname();
  • The creation procedures (which exist only if the Garbage Collector is used) are named newxyz().
  • The model for objects of type xyz are named Mxyz. Models are used for initialisation. Example:
    T132 M132={132,NULL,NULL,0,0,NULL,0,0,0,0,0,0,0,0,0,NULL};
    ...
    {T132*n=((T132*)se_malloc(sizeof(*n)));
    *n=M132;
    r132make(n);
    ...
    
Some characters in method names such as "<" or "+" will be replaced with relative ASCII number written as decimal.

For example: STRING has the identifier 72. Then:

  • The object type is T7
    typedef struct S7 T7;
    
  • The structure may be defined in S7
    struct S7{Tid id;T9 _storage;T2 _count;T2 _capacity;};
    
  • The append is defined like this:
    void r7append(se_dump_stack*caller,T7* C,T0* a1);
    
    (more on the dump stack below)
When you compile your application, you can find those identifiers in a file name after the name of the root class, suffixed by .id; the file is structured in entries, each entry being separated from others by a hash character ('#'). This file looks like this:
4 "REAL"
#
12 "HELLO_WORLD"
class-path: "./hello_world.e"
class-name: HELLO_WORLD
parent-count: 0
c-type: T12 reference: yes
ref-status: live id-field: yes 
run-time-set-count: 1
run-time-set:
        HELLO_WORLD (12)
#
9 "NATIVE_ARRAY[CHARACTER]"
class-path: "/lib/se/lib/kernel/native_array.e"
class-name: NATIVE_ARRAY
parent-count: 1 parents: 26
c-type: T9 reference: no
#
21 "COMPARABLE"
class-path: "/lib/se/lib/kernel/comparable.e"
class-name: COMPARABLE
parent-count: 1 parents: 13
#
. . .

You must not depend on the identifiers values. Indeed, when computing an identifier, collisions may occur, and affect this process. Thus, the number (and name) corresponding to each type depends not only on the type name, but also on the order in which they are compiled. That is, on the application and libraries compiled... They also depend on the compilation mode used, and the version of the compiler you're using. So what is T145 now may become T234 the next time you compile...3

Consequently, do not, ever, rely on the type numbers in the generated C code, because they are not constant! (Except for a few ones which have a fixed, hard-coded name). So don't bother writing in your own C code things such as new123 or T456, because the only thing we guarantee in this case is that your code shall break someday.

The Naming Convention

The previous chapter explains how method names are generated. r7append prototype presented above as void r7append(se_dump_stack*caller,T7* C,T0* a1); shows Current and argument cases. Rules are as follow:

  • Current is named C when given as parameter to the procedure/function. This parameter may be omitted if Current is not used. In some cases (when inlining is done in boost mode), Current is copied in local variables named C1, C2...
  • Arguments are named a1, a2...
  • Inside functions, a local variable named R is defined. This is the Result value.
  • Local variables names are Eiffel names prefixed with underscore character.

The Mangling Table

OK, so now you understand why you cannot use type numbers, but you still want to know what those things in the mangling table mean. :-)

First, a big caveat. Although it hasn't changed a lot and has been very stable for quite some time now, the mangling table coding may change in the future! We currently have no plans to change it, and we prefer keeping it the way it is. But once again, we do not commit ourselves to the current representation.

Let's look again at the extract of a .id file. The shown part covers quite all the possible cases:

4 "REAL"
#
12 "HELLO_WORLD"
class-path: "./hello_world.e"
class-name: HELLO_WORLD
parent-count: 0
c-type: T12 reference: yes
ref-status: live id-field: yes 
run-time-set-count: 1
run-time-set:
        HELLO_WORLD (12)
#
9 "NATIVE_ARRAY[CHARACTER]"
class-path: "/lib/se/lib/kernel/native_array.e"
class-name: NATIVE_ARRAY
parent-count: 1 parents: 26
c-type: T9 reference: no
#
21 "COMPARABLE"
class-path: "/lib/se/lib/kernel/comparable.e"
class-name: COMPARABLE
parent-count: 1 parents: 13
#
. . .

There is one entry per type (live or not); each entry spans on many lines and finished by a hash symbol ('#').

Each entry comprises many informations. All of them are not always present (in that case, they have default values). Only the first line is compulsory.

The first line contains the type number, and its name (as would return generating_type).

The next lines contain different fields, marked as a keyword, a colon and a value. There may be one or more fields on one line. Those fields are:

class-path The path to the file containing the source of the class. May be omitted if the class has no associated file (e.g., TUPLE or PROCEDURE).
class-name The name of the class, as would return generator.
parent-count The number of parents.
parents On the same line as parent-count if the latter is not null; it gives the parent class identifiers.
c-type The C type, usually in the form Txyz. If omitted, the class has no runnable type.
In that case, the following fields do not appear either.
reference On the same line as c-type, yes for a reference type or no for an expanded type.
ref-status Either live for a living type (i.e. whether instances of this type are ever created at run-time), or dead otherwise.
id-field On the same line as ref-status, yes if the id field is in the generated C structure (as its first element), no otherwise. This field is present if one of these confitions is true:
  • some late binding may occur on targets of that type,
  • or the struct may be accessed by external or Cecil code.
Note that a lot of calls are statically computed; the type inference algorithm used in SmartEiffel increases the number of such types that don't need the id field.
run-time-set-count The number of concrete, live descendants of the type (including itself). It is thus the number of items in the run-time-set below.
run-time-set Contains the live heirs with their identifier. There is one such class per line.
The Dump Stack

When not in boost mode, a stack is managed by the SmartEiffel runtime. This stack can be displayed when an exception not caught is raised. It is also used by the debugger (sedb).

Technically, the SmartEiffel stack is built upon the native (C) stack. It is a se_dump_stack4 usually allocated on the stack. It is made up of several parts:

  • a frame descriptor, of type se_frame_descriptor4 which is a static description of the feature: run type, does it use Current, number and type of the locals (parameters and local variables), and an anti-recursion flag (when testing contracts);
  • a pointer to Current (i.e. either a pointer to an expanded object, or a pointer to a reference object, it being a pointer to the object itself). That's why the type of the current field is Void**. This field will be NULL if Current is not used by the feature;
  • the position (used mainly by sedb);
  • a pointer to the caller (i.e. the se_dump_stack of the calling function);
  • a pointer to the exception origin: if not NULL, it means that this se_dump_stack is not in the stack, but was malloc'ed to preserve the exception stack trace;
  • an array of locals (with double indirection as for Current), hence the type void***.
One macro handles the linking and unlinking of the dump stack frames by setting the caller field of the dump stack top, then changing that top.
  • Normally, the dump stack top is a global se_dst defined in SmartEiffel/sys/runtime/no_check.c. The set_dump_stack_top just affects the given argument to se_dst.
  • In SCOOP mode, things are a bit different since each processor has its own stack. set_dump_stack_top has two arguments: the processor and the new dump stack top.
The Plugin Subsystem

That "plugin" subsystem is used by SmartEiffel libraries to provide, at the same time, facility of extension and independance from the backend (C, Java).

Features declared as external "plug_in" are handled by the plugin subsystem. They must have an alias with the following informations:

  • location: the location of the plug_in source (may depend on environment variables, even those provided by the configuration file---more details here).
  • module_name: the name or the plugin. For a C plugin, it is the name of the C files (without the .c or .h extensions). For a Java plugin, this system is not yet supported (indeed compile_to_jvm will surely not ship with 2.0, but should resurect like the Phoenix in a later version).
  • feature_name: the name of the C (or Java) function to call.

The naming scheme is thus:

feature

   my_plugin_feature(args) is
      external "plug_in"
      alias "{
         location: "${my_plugin}"
         module_name: "myplug"
         feature_name: "feature"
      }"
      end

The C backend will then search for myplug.c and myplug.h (those found will be included in good place, one in the generated .c, other in the .h). In those files, a function (or a macro) must be named feature(), and accept the same arguments as its Eiffel counterpart (that is, written the C way). Note: Current is never passed.

For some examples, one may look at BASIC_DIRECTORY and so on.

Notes

1

There is a bijection between the number and the name of the type, including its parameters in the case of generic types. (My_Feature details about this in our research papers).

2

There are some identifiers that are reserved for "basic" types. They are:
  • 0 is the type any other can cast to;
  • 1 is INTEGER_8;
  • 2 is INTEGER_32;
  • 3 is CHARACTER;
  • 4 is REAL;
  • 5 is DOUBLE;
  • 6 is BOOLEAN;
  • 7 is STRING;
  • 8 is POINTER;
  • 9 is NATIVE_ARRAY[CHARACTER] (used by STRING);
  • 10 is INTEGER_16;
  • 11 is INTEGER_64.
The root class of the system will then have the 12. Don't rely on that, though (before all those INTEGERs revolution, it was 11).

3

The compiler will do its best not to change the identifiers uselessly. The .id file is loaded at the beginning of the compilation process, and saved again at its end. But clean erases that file.

4

You may find the definition of those structures in the SmartEiffel/sys/runtime/c/no_check.h file.

[Line]
Copyright © Dominique COLNET and Suzanne COLLIN - <SmartEiffel@loria.fr>
Last modified: Thu Jun 12 10:50:08 CEST 2003