<!-- Title = C Code Generated by SmartEiffel -->

<table border="0" cellspacing="5" cellpadding="5" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td>
<center><font color="#FFFFFF" size="+3"><b>About the Generated C Code</b></font></center>
</td>
</tr>
</table>

<br><br><br>
<p>
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 
<a href="../man/cecil.html">Cecil</a> or the <a href="../man/external.html">external</a> 
mechanism. This page mentions some facts you should be aware of before you start.
</p>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="generated-type-ids">Generated Type Identifiers</a></font></td>
</tr>
</table>
<p>
First and above all, SmartEiffel generates one unique numeric identifier for
each living type<a name="ref_note1"></a><a
href="#note1"><font="-2"><sup>1</sup></font></a> present in the Eiffel code. A
lot of symbols in the generated C code depend on that identifier.
</p>

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

<p>
If <tt><i>xyz</i></tt> is the identifier, then:
</p>

<ul>

<li>The type of an Eiffel object is <tt><b>T</b><i>xyz</i></tt>;</li>

<li>The corresponding structure is <tt><b>S</b><i>xyz</i></tt>; in that structure,
the names of the attributes are prefixed with an underscore (there may be some
other fields, usually the first being <tt>id</tt> used by SmartEiffel for bookkeeping);</li>

<li>Each reference type can be cast in <tt>T0</tt> (but some reference type
may not have the <tt>id</tt> field):
<blockquote><pre>
typedef int Tid;
typedef struct S0 T0;
struct S0{Tid id;};
</pre></blockquote></pre>

<li>Each method is named <tt><b>r</b><i>xyz</i>methodname()</tt>;</li>

<li>Each prefix method is named <tt><b>r</b><i>xyz</i>_px_methodname()</tt>;
</li>

<li>Each infix method is named <tt><b>r</b><i>xyz</i>_ix_methodname()</tt>;
</li>

<li>Each late-binding method is named <tt><b>X</b><i>xyz</i>methodname()</tt>;
</li>

<li>The creation procedures (which exist only if the Garbage Collector is
used) are named <tt><b>new</b><i>xyz</i>()</tt>.</li>

<li>The model for objects of type <i>xyz</i> are named
<tt><b>M</b><i>xyz</i></tt>. Models are used for initialisation. Example:
<blockquote><pre>
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);
...
</pre></blockquote></pre>
</li>

</ul>
Some characters in method names such as "&lt;" or "+" will be replaced with
relative ASCII number written as decimal.

</p>

<p>
For example: <tt>STRING</tt> has the indentifier <b>7</b><a
name="ref_note2"></a><a href="#note2"><font="-2"><sup>2</sup></font></a>.
Then:
</p>

<ul>

<li>The object type is <tt>T7</tt>
<blockquote><pre>
typedef struct S7 T7;
</pre></blockquote></li>

<li>The structure may be defined in <tt>S7</tt>
<blockquote><pre>
struct S7{Tid id;T9 _storage;T2 _count;T2 _capacity;};
</pre></blockquote></li>

<li>The <tt>append</tt> is defined like this:
<blockquote><pre>
void r7append(se_dump_stack*caller,T7* C,T0* a1);
</pre></blockquote><i>(more on the dump stack below)</i></li>

</ul>

When you compile your application, you can find those identifiers in a file
name after the name of the root class, suffixed by <tt>.id</tt>; the file is
structured in <i>entries</i>, each entry being separated from others by a hash
character ('#'). This file looks like this:

<blockquote><pre>
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:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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
#
.&nbsp;.&nbsp;.
</pre></blockquote>
</p>

<p>
You must not depend on the indentifiers 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 <tt>T145</tt> now may become
<tt>T234</tt> the next time you compile...<a
name="ref_note3"></a><a href="#note3"><font="-2"><sup>3</sup></font></a>
</p>

<p>
Consequently, <B>do not, ever, rely on the type numbers  in the 
generated C code, because they are not constant!</B> (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 <tt>new123</tt> or <tt>T456</tt>, because the only thing we guarantee 
in this case is that your code <b>shall</b> break someday.
</p>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="naming-convention">The Naming Convention</a></font></td>
</tr>
</table>
<p>
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:
<ul>

<li>
Current is named <b>C</b> 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
<b>C1</b>, <b>C2</b>...
</li>

<li>
Arguments are named <b>a1</b>, <b>a2</b>...
</li>

<li>
Inside functions, a local variable named <b>R</b> is defined. This is the
Result value.
</li>

<li>
Local variables names are Eiffel names prefixed with underscore character.
</li>
</ul>
<p>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="mangling-table">The Mangling Table</a></font></td>
</tr>
</table>
<p>
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. :-)
</p> 
<p>
First, a big caveat. Although it hasn't changed a lot and has been very stable
for quite some time now, <b>the mangling table coding may change</b> 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.
</p>

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

<blockquote><pre>
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:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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
#
.&nbsp;.&nbsp;.
</pre></blockquote>
</p>

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

<p>
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.
</p>

<p>
The first line contains the type number, and its name (as would return
<tt>generating_type</tt>).
</p>

<p>
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:
</p>

<blockquote>
<table width="100%" cols="2" border="1">
<tbody>
<tr>
<td width="20%" valign="top"><b>class-path</b></td>
<td>
The path to the file containing the source of the class.  May be omitted if
the class has no associated file (e.g., <tt>TUPLE</tt> or <tt>PROCEDURE</tt>).
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>class-name</b></td>
<td>
The name of the class, as would return <tt>generator</tt>.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>parent-count</b></td>
<td>
The number of parents.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>parents</b></td>
<td>
On the same line as <b>parent-count</b> if the latter is not null; it gives
the parent class identifiers.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>c-type</b></td>
<td>
The C type, usually in the form <tt><b>T</b><i>xyz</i></tt>. If omitted, the
class has no runnable type.<br><i>In that case, the following fields do not
appear either.</i>
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>reference</b></td>
<td>
On the same line as <b>c-type</b>, <tt>yes</tt> for a reference type or
<tt>no</tt> for an expanded type.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>ref-status</b></td>
<td>
Either <tt>live</tt> for a living type (i.e. whether instances of this type
are ever created at run-time), or <tt>dead</tt> otherwise.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>id-field</b></td>
<td>
On the same line as <b>ref-status</b>, <tt>yes</tt> if the <tt>id</tt> field
is in the generated C structure (as its first element), <tt>no </tt>
otherwise. This field is present if one of these confitions is true:
<ul>
<li>some late binding may occur on targets of that type,</li>
<li>or the struct may be accessed by external or Cecil code.</li>
</ul>
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
<tt>id</tt> field.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>run-time-set-count</b></td>
<td>
The number of concrete, live descendants of the type (including itself). It is
thus the number of items in the <b>run-time-set</b> below.
</td>
</tr>
<tr>
<td width="20%" valign="top"><b>run-time-set</b></td>
<td>
Contains the live heirs with their identifier. There is one such class per
line.
</td>
</tr>
</tbody>
</table>
</blockquote>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="run-time-stack">The Dump Stack</a></font></td>
</tr>
</table>

<p>
<b>When not in boost mode</b>, 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 (<a href="sedb.html">sedb</a>).
</p>

<p>
Technically, the SmartEiffel stack is built upon the native (C) stack. It is a
<tt>se_dump_stack</tt><a name="ref_note4"></a><a
href="#note4"><font="-2"><sup>4</sup></font></a> usually allocated on the
stack. It is made up of several parts:
</p>

<ul>

<li>a <i>frame descriptor</i>, of type <tt>se_frame_descriptor</tt><a
href="#note4"><font="-2"><sup>4</sup></font></a> which is a static description
of the feature: run type, does it use <i>Current</i>, number and type of the
locals (parameters and local variables), and an anti-recursion flag (when
testing contracts);</li>

<li>a pointer to <i>Current</i> (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 <tt>current</tt> field is
<tt>Void**</tt>. This field will be <tt>NULL</tt> if <i>Current</i> is not
used by the feature;</li>

<li>the position (used mainly by <a href="sedb.html">sedb</a>);</li>

<li>a pointer to the caller (i.e. the <tt>se_dump_stack</tt> of the calling
function);</li>

<li>a pointer to the exception origin: if not <tt>NULL</tt>, it means that
this <tt>se_dump_stack</tt> is <b>not</b> in the stack, but was malloc'ed to
preserve the exception stack trace;</li>

<li>an array of locals (with double indirection as for <i>Current</i>), hence
the type <tt>void***</tt>.</li>

</ul>

One macro handles the linking and unlinking of the dump stack frames by
setting the <tt>caller</tt> field of the dump stack top, then changing that
top.

<ul>

<li>Normally, the dump stack top is a global <tt>se_dst</tt> defined in
<tt>SmartEiffel/sys/runtime/no_check.c</tt>. The <tt>set_dump_stack_top</tt>
just affects the given argument to <tt>se_dst</tt>.</li>

<li>In SCOOP mode, things are a bit different since each processor has its own
stack. <tt>set_dump_stack_top</tt> has two arguments: the processor and the
new dump stack top.</li>

</ul>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="basic">The Basic Subsystem</a></font></td>
</tr>
</table>

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

<p>
Features named <tt>basic_something</tt> and declared as
<tt>external&nbsp;"SmartEiffel"</tt> are handled by the <i>basic
subsystem</i>.
</p>

<p>
The naming scheme is thus:
</p>

<pre>
feature

   <b>basic_topic_my_feature</b>(args) is
      external "SmartEiffel"
      end
</pre>

<p>
The C backend<a name="ref_note5"></a><a
href="#note5"><font="-2"><sup>5</sup></font></a> will then search for
<tt>basic_topic.c</tt> and <tt>basic_topic.h</tt> (those found will be
included in good place, one in the generated <tt>.c</tt>, other in the
<tt>.h</tt>). In those files, a function (or a macro) must be named
<tt>basic_topic_my_feature()</tt> (like the Eiffel feature), and accept the same
arguments as its Eiffel counterpart (that is, written the C
way). <i>Current</i> is never passed.
</p>

<p>
Indeed this is a kind of "plugin" system for the SmartEiffel libraries. Some
extensions may be foreseen in the future.
</p>

<p>
For some examples, one may look at <tt>BASIC_DIRECTORY</tt> and so on.
</p>

<table border="0" cols="1" width="100%" bgcolor="#3366FF">
<tr>
<td><font color="#FFFFFF" size="+2">
<a name="notes">Notes</a></font></td>
</tr>
</table>

<p><a name="note1"></a><a href="#ref_note1"><b>1</b></a>
<blockquote>
There is a bijection between the number and the <i>name</i> of the type,
including its parameters in the case of generic types. (My_Feature details about
this in our <a href="../papers/papers.html">research papers</a>).
</blockquote>
</p>

<p><a name="note2"></a><a href="#ref_note2"><b>2</b></a>
<blockquote>
There are some identifiers that are reserved for "basic" types. They are:
<ul>
<li>0 is the type any other can cast to;</li>
<li>1 is <tt>INTEGER_8</tt>;</li>
<li>2 is <tt>INTEGER_32</tt>;</li>
<li>3 is <tt>CHARACTER</tt>;</li>
<li>4 is <tt>REAL</tt>;</li>
<li>5 is <tt>DOUBLE</tt>;</li>
<li>6 is <tt>BOOLEAN</tt>;</li>
<li>7 is <tt>STRING</tt>;</li>
<li>8 is <tt>POINTER</tt>;</li>
<li>9 is <tt>NATIVE_ARRAY[CHARACTER]</tt> (used by <tt>STRING</tt>);</li>
<li>10 is <tt>INTEGER_16</tt>;</li>
<li>11 is <tt>INTEGER_64</tt>.</li>
</ul>

The root class of the system will then have the 12. Don't rely on that, though
(before all those <tt>INTEGER</tt>s revolution, it was 11).

</blockquote>
</p>

<p><a name="note3"></a><a href="#ref_note3"><b>3</b></a>
<blockquote>
The compiler will do its best not to change the identifiers uselessly. The
<tt>.id</tt> file is loaded at the beginning of the compilation process, and
saved again at its end. But <tt>clean</tt> erases that file.
</blockquote>
</p>

<p><a name="note4"></a><a href="#ref_note4"><b>4</b></a> <blockquote> You may
find the definition of those structures in the
<tt>SmartEiffel/sys/runtime/c/no_check.h</tt> file.  </blockquote>
</p>

<p><a name="note5"></a><a href="#ref_note5"><b>5</b></a> <blockquote> The Java
backend is similar. It looks for the class
<tt>fr.loria.SmartEiffelBasicTopic</tt> and the static function
<tt>basic_topic_my_feature()</tt> with the arguments quite similar to the C ones.
</blockquote>
</p>

<center><p><img src="../images/se-line.gif" alt="[Line]" height="16" width="550">
<br>
<i><font size="-1">Copyright &copy; Dominique COLNET and Suzanne COLLIN -
<a href="mailto:SmartEiffel@loria.fr">&lt;SmartEiffel@loria.fr&gt;</a> <br>
<!-- hhmts start -->
Last modified: Thu Jun 12 10:50:08 CEST 2003
<!-- hhmts end -->
<br>
</font></i><br></p></center>