View source for Expanded or reference

[[Category:Smarteiffel]]
In our opinion, it is essential to have a good understanding of how objects are represented in memory while an application is running.
The aim is not to make every one of us an expert in the subject, but
more simply to have sufficient knowledge to be able to make design choices.
Besides, it is often essential to be able to draw how objects appear in memory so as to be able to explain or think about the design of a new class.
The section which explains
[[#ExpandedBasics|the two categories of objects]] which exist during execution is essential.
Next, a summary of the
[[#ExpandedProperties|properties of <tt>expanded</tt> types]]
goes into detail about certain points that are characteristic of these types.

You have to realise that all variables are
[[#AutomaticInitialization|automatically initialised]]
in accordance with their declared type.
This too needs to be understood.

The last section is only of interest to those few users who wish to define their
[[#AvoidExpandedPitfall|own <tt>expanded</tt> class]].
This section can be skipped by most beginners.

<div id="ExpandedBasics">
==<tt>Expanded</tt> or reference objects, the choice==
</div>
The objects that are handled during the execution of an Eiffel
program are handled either with or without an intermediate reference.
Furthermore, when an object is handled through a reference, it can be handled only through a reference.
In the same way, when an object is handled without a reference, it can only be handled in that way, that is to say without any intermediate reference.

Thus there are two sorts of objects.
The most common classes correspond to objects that are handled through a reference.
Less often, classes correspond to objects that are handled without an intermediate pointer.
In this case, the class in question begins with the keyword
[[Syntax diagrams#ClassDeclaration|<tt>expanded</tt>]].
In Eiffel jargon, when we speak of an <tt>expanded</tt> class,
we are talking about a class whose objects are handled without an intermediate pointer, objects that are directly written, or ''expanded'', onto the memory area that they use.
In contrast, if we talk of a ''reference class'' or of a ''reference type'', it is to emphasise that the objects in question are not <tt>expanded</tt>.

The chief point of this dichotomy is to make it possible to integrate the most basic entities into the object model.
For example, a boolean value of the
[[library_class:BOOLEAN|<tt>BOOLEAN</tt>]] class corresponds to an <tt>expanded</tt> object.
Similarly, the classes [[library_class:INTEGER|<tt>INTEGER</tt>]]
and [[library_class:REAL|<tt>REAL</tt>]] are also <tt>expanded</tt>.
The following diagram shows what happens in memory; the classes 
<tt>POINT</tt> and <tt>TRIANGLE</tt> are ordinary classes, that is to say classes defined without the keyword <tt>expanded</tt>: 

[[Image:ExpandedVsReferenceBoolean.png|Expanded vs reference memory structure]]

In the figure above, the variable called <tt>a_boolean</tt> is declared as type [[library_class:BOOLEAN|<tt>BOOLEAN</tt>]].
Since the [[library_class:BOOLEAN|<tt>BOOLEAN</tt>]] class is <tt>expanded</tt>, 
the corresponding object is directly assigned to the memory area associated with the variable <tt>a_boolean</tt>.
As the diagram shows, the <tt>a_boolean</tt> variable currently contains an object <tt>True</tt> which corresponds to the boolean value true.
In the same way, the memory area associated with the variable <tt>a_integer</tt> of type [[library_class:INTEGER|<tt>INTEGER</tt>]] directly contains the object corresponding to the value <tt>1</tt> since the [[library_class:INTEGER|<tt>INTEGER</tt>]] class is also <tt>expanded</tt>.
Finally, the variable <tt>a_real</tt> declared in the example as type [[library_class:REAL|<tt>REAL</tt>]] also directly contains the value <tt>1.0</tt>.

In the diagram above, the variable <tt>point</tt> is declared as type <tt>POINT</tt>.
Since we are not dealing with an <tt>expanded</tt> class, the memory area associated with the variable <tt>point</tt> does not directly contain the <tt>POINT</tt> object, but a pointer to that object.
Thus the <tt>point</tt> variable does not directly contain an object of the <tt>POINT</tt> class; the <tt>point</tt> variable ''references'' a <tt>POINT</tt> object.
Note that the diagram also shows us that each object of class <tt>POINT</tt> is itself made up of two [[Glossary#Attribute|attributes]] <tt>x</tt> and <tt>y</tt> whose type is [[library_class:REAL|<tt>REAL</tt>]].
As in the case of the <tt>point</tt> variable, the variable <tt>triangle</tt> is a reference to an object of the class <tt>TRIANGLE</tt> since the <tt>TRIANGLE</tt> class is an ordinary class, not <tt>expanded</tt>.
Since the [[Glossary#Attribute|attributes]] <tt>p1</tt>, <tt>p2</tt> and <tt>p3</tt> are of the <tt>POINT</tt> type, in this case there are also pointers to the corresponding objects.

Whether or not an object is <tt>expanded</tt>, the syntax used to declare it is the same.  The fact that a class is <tt>expanded</tt>  or not depends only on the [[Syntax diagrams#ClassDeclaration|class definition]] itself.
For example, the declaration of the variables <tt>a_boolean</tt>, <tt>a_integer</tt>, <tt>a_real</tt>,
<tt>point</tt> and <tt>triangle</tt>  corresponds to the following Eiffel code:

 a_boolean: BOOLEAN; a_integer: INTEGER; a_real: REAL; point: POINT; triangle: TRIANGLE

Whether or not one is dealing with an <tt>expanded</tt> object, the notation is just the same.
For example, the following [[Glossary#Instruction|instruction]] copies into the variable <tt>a_real</tt> the value of the attribute <tt>y</tt> of the <tt>POINT</tt> object referenced by the variable <tt>point</tt>:

 a_real := point.y

The following [[Glossary#Instruction|instruction]] copies the pointer which points to the same <tt>POINT</tt> as the one referenced by the <tt>p1</tt> attribute of the <tt>TRIANGLE</tt> which is itself referenced by the variable <tt>triangle</tt>:

 point := triangle.p1

Without going into [[Assignment|all the details of assignments]], the effect of those two instructions in relation to the memory diagram above is to produce this memory configuration:

[[Image:ExpandedVsReferenceBooleanBis.png|Expanded vs reference memory structure]]

Applying a method to an <tt>expanded</tt> object uses the same syntax as for an ordinary (not <tt>expanded</tt>) object.
For example the following [[Glossary#Instruction|instruction]] applies the <tt>sqrt</tt> [[Glossary#Function|function]] to the [[library_class:INTEGER|<tt>INTEGER</tt>]] class object which is stored directly in the memory area associated with the variable <tt>a_integer</tt>.
The result of calling the <tt>sqrt</tt> function is a <tt>REAL</tt> which overwrites the old object which was formerly stored directly in the variable <tt>a_real</tt>:
 
 a_real := a_integer.sqrt

Having identical notation for handling ordinary (referenced) and <tt>expanded</tt> (not referenced) objects simplifies programming and provides consistency.

Being able to describe basic objects by a proper class is an important aid to consistency.
A simple object, such as a 32 bit signed integer, is described  by a proper class, the [[library_class:INTEGER|<tt>INTEGER</tt>]] class.
As with any class, it is possible to change or adapt the methods in the
[[library_class:INTEGER|<tt>INTEGER</tt>]] class. 
Of course, nearly all users only consult the list of available methods.
Since the [[library_class:INTEGER|<tt>INTEGER</tt>]] class is used by almost every program, altering it is more and more an uncommon event, and must be done with care.
Nevertheless, having a proper class lets users look up the list of available methods for [[library_class:INTEGER|<tt>INTEGER</tt>]]  in the same way as they can for all other classes.

Among the predefined <tt>expanded</tt> classes corresponding to basic objects that must be familiar to all users are:
[[library_class:BOOLEAN|<tt>BOOLEAN</tt>]],
[[library_class:INTEGER|<tt>INTEGER</tt>]],
[[library_class:REAL|<tt>REAL</tt>]]
and
[[library_class:CHARACTER|<tt>CHARACTER</tt>]].
A well-informed user should also be familiar with the following <tt>expanded</tt> classes:
[[library_class:INTEGER_8|<tt>INTEGER_8</tt>]],
[[library_class:INTEGER_16|<tt>INTEGER_16</tt>]],
[[library_class:INTEGER_32|<tt>INTEGER_32</tt>]],
[[library_class:INTEGER_64|<tt>INTEGER_64</tt>]],
[[library_class:REAL_32|<tt>REAL_32</tt>]],
[[library_class:REAL_64|<tt>REAL_64</tt>]],
[[library_class:REAL_80|<tt>REAL_80</tt>]],
[[library_class:REAL_128|<tt>REAL_128</tt>]],
[[library_class:REAL_EXTENDED|<tt>REAL_EXTENDED</tt>]]
and finally, for the most curious, there are the classes [[library_class:POINTER|<tt>POINTER</tt>]]
and [[library_class:NATIVE_ARRAY|<tt>NATIVE_ARRAY</tt>]].

<div id="ExpandedProperties">

==Principal characteristics of <tt>expanded</tt> type expressions==
</div>
An expanded type [[Glossary#Expression|expression]] has
properties which one needs to know.
As explained above, the object that corresponds to an
<tt>expanded</tt> type [[Glossary#Expression|expression]] cannot be referenced.
No other location can directly designate the object in question; in particular no pointer can point to it.
So if, for example, one is dealing with a variable of type
[[library_class:INTEGER|<tt>INTEGER</tt>]], the only way of operating on the corresponding object is to use the variable in question.

An <tt>expanded</tt> type [[Glossary#Expression|expression]] always designates an object.
In other words, an <tt>expanded</tt> expression is never [[Void|<tt>Void</tt>]].
What is more, an <tt>expanded</tt> type [[Glossary#Expression|expression]] always corresponds to one and only one category of object.
In consequence, [[Dynamic dispatch|dynamic dispatch]] is never involved when an <tt>expanded</tt> object is the target of a call (that is, on the left of a dot).
The invocation of a [[Glossary#Method|method]] with an <tt>expanded</tt> object as target corresponds to the most efficient possible direct call.

Without going into too much detail, since dynamic dispatch is not possible with an <tt>expanded</tt> object, it is useless to give such an object the information that lets you find its [[Glossary#DynamicType|dynamic type]].
Thus, the memory space required for an <tt>expanded</tt> object is limited exactly to that needed to accommodate its different [[Glossary#Attribute|attributes]].

<div id="AutomaticInitialization">

==Initialisation of variables and attributes==
</div>
In Eiffel, all variables are always initialised automatically.
This is the same for all kinds of variables:
[[Glossary#InstanceVariable|instance variables]],
[[Syntax diagrams#Routine|local variables]] and the
variable [[Syntax diagrams#Result|<tt>Result</tt>]] which is used to hold the result of a function.
The way in which a variable is initialised depends entirely on its declaration type, which is either reference or <tt>expanded</tt>.

===Initialisation of reference type variables===

A variable whose type is a ''reference type'' is always automatically initialised with [[Void|<tt>Void</tt>]].
For example, if you declare a variable of type
<tt>POINT</tt> or type <tt>TRIANGLE</tt>, the non-<tt>expanded</tt> classes of the example above, the variable is automatically initialised with [[Void|<tt>Void</tt>]].
For reference types, an object is never automatically created following the declaration of a variable.

Among the standard classes that correspond to reference types, let us consider the [[library_class:STRING|<tt>STRING</tt>]] class.
This class is in no way a special case.
A variable declared to be of type  [[library_class:STRING|<tt>STRING</tt>]] is automatically initialised with [[Void|<tt>Void</tt>]].
No object of the [[library_class:STRING|<tt>STRING</tt>]] class is created when a [[library_class:STRING|<tt>STRING</tt>]] type variable is declared.
To take another common example, declaring  a variable of type [[library_class:ARRAY|<tt>ARRAY[INTEGER]</tt>]] does not lead to the automatic creation of a table of <tt>INTEGER</tt>s, because the class [[library_class:ARRAY|<tt>ARRAY</tt>]] itself is still not an <tt>expanded</tt> class.
So this simple initialisation rule applies to the majority of classes, which, it should be remembered, are ordinary, non-<tt>expanded</tt> classes.


===Initialisation of <tt>expanded</tt> type variables===
Variables whose type is <tt>expanded</tt> are also initialised automatically.
For certain truly basic <tt>expanded</tt> types, the initialisation is done directly by the compiler.
After presenting all these special cases, we will deal with the general case of an <tt>expanded</tt> class.

For the family of <tt>INTEGER</tt>s, that is to say all the following types,
<tt>{</tt>[[library_class:INTEGER_8|<tt>INTEGER_8</tt>]], 
[[library_class:INTEGER_16|<tt>INTEGER_16</tt>]], 
[[library_class:INTEGER_32|<tt>INTEGER_32</tt>]], 
[[library_class:INTEGER|<tt>INTEGER</tt>]], 
[[library_class:INTEGER_64|<tt>INTEGER_64</tt>]]<tt>}</tt>,
the object used to initialise them corresponds to the value <tt>0</tt>.

For the group of types
<tt>{</tt>[[library_class:REAL_32|<tt>REAL_32</tt>]], 
[[library_class:REAL_64|<tt>REAL_64</tt>]],
[[library_class:REAL|<tt>REAL</tt>]], 
[[library_class:REAL_80|<tt>REAL_80</tt>]], 
[[library_class:REAL_128|<tt>REAL_128</tt>]], 
[[library_class:REAL_EXTENDED|<tt>REAL_EXTENDED</tt>]]<tt>}</tt>,
the object used to initialise them corresponds to the value <tt>0.0</tt>.

For the 
[[library_class:BOOLEAN|<tt>BOOLEAN</tt>]] type,
the value <tt>False</tt> is used to initialise an object.

For the 
[[library_class:CHARACTER|<tt>CHARACTER</tt>]] type, the character with the ASCII code 0 is used to initialise it. This character is denoted by <tt>'%U'</tt> in Eiffel. 

For the 
[[library_class:POINTER|<tt>POINTER</tt>]] type,
variable initialisation is done with the machine value that represents the <tt>null</tt> pointer.
Since this value is not in normal use, there is no Eiffel notation for  it.  It is necessary to use the <tt>is_null</tt> method of the [[library_class:POINTER|<tt>POINTER</tt>]] class to test whether an expression of this type corresponds to the <tt>null</tt> value.

In the general case, that is to say for an <tt>expanded</tt> class that is not one of the special cases above, the initialisation is programmed by the class designer.  In fact, an <tt>expanded</tt> class must either have no creation clause, or '''one and only one of its constructors must have no arguments'''.  This creation procedure is automatically run to effect initialisation.

<div id="AvoidExpandedPitfall">

==Some advice before you write an <tt>expanded</tt> class==
</div>
In general, it is not useful to define new <tt>expanded</tt> classes
and this applies to the great majority of applications.
As we have explained above, the principal use of <tt>expanded</tt> classes is to make it possible to integrate the most basic objects into the object model.
Having said that, it can perhaps be useful to resort to an <tt>expanded</tt> class, whether to make available a [[#RoutineTank|group of utility routines]], or to economise on memory in the special case when a [[#ManySmallObjects|large number of small objects]] is used.
Finally, we will present the [[#ExpandedPitfalls|traps to avoid]] when designing an <tt>expanded</tt> class.

<div id="RoutineTank">
===Grouping a collection of routines===
</div>
With an object-oriented language, it is always most convenient, if possible, to put the object-handling methods directly in the class of the objects to be handled.
In certain very special cases, it is not desirable, nor even possible, to keep to this basic rule.

The [[library_class:COLLECTION_SORTER|<tt>COLLECTION_SORTER</tt>]] class is a good example of an <tt>expanded</tt> class intended for grouping some [[Glossary#Routine|routines]] which cannot be placed directly in the classes that correspond to the idea of a 
[[library_class:COLLECTION|<tt>COLLECTION</tt>]].

Although all the routines of the 
[[library_class:COLLECTION_SORTER|<tt>COLLECTION_SORTER</tt>]]
class are used for sorting objects from the 
[[library_class:COLLECTION|<tt>COLLECTION</tt>]]s family, it is not possible to put these methods directly into the [[library_class:COLLECTION|<tt>COLLECTION</tt>]] class.
This is not possible for the simple reason that not all [[library_class:COLLECTION|<tt>COLLECTION</tt>]]s can be sorted.
Only [[library_class:COLLECTION|<tt>COLLECTION</tt>]]s whose elements are [[library_class:COMPARABLE|<tt>COMPARABLE</tt>]] can be sorted.
So the [[library_class:COLLECTION_SORTER|<tt>COLLECTION_SORTER</tt>]]
class lets us add this extra generic constraint.
The [[library_class:COLLECTION_SORTER|<tt>COLLECTION_SORTER</tt>]] class does not have any attribute; it is just a holder for methods.
Furthermore, this class is expanded.  So, to sort a whole table, for example, you can proceed in the following manner:
 local
    sorter: COLLECTION_SORTER[INTEGER]
    array: ARRAY[INTEGER]
 do
    array := <<1,3,2>>
    sorter.sort(array)
The point of using an <tt>expanded</tt> class in this case is that it is unnecessary to allocate space for an object of the 
[[library_class:COLLECTION_SORTER|<tt>COLLECTION_SORTER[INTEGER]</tt>]] class in the [[Glossary#Heap|heap]].
No doubt you have noticed in reading the above code that there is no creation instruction for the object associated with the variable <tt>sorter</tt>.
Furthermore, since the objects of this class have no attribute, the object corresponding to <tt>sorter</tt> is not even represented on the [[glossary#Stack|stack]]!
<br>
Here, using an <tt>expanded</tt> object lets us get better performance.

<div id="ManySmallObjects">

===Economising on memory for many small objects===
</div>
Another use for <tt>expanded</tt> classes is to let you economise on memory for small objects.
By ''small object'' we mean an object whose memory requirement is comparable to or slightly higher than the machine's pointer size.
If for argument's sake we assume that an object of class <tt>FOO</tt> is exactly the same size as a machine pointer and that the application uses ''n'' objects of class <tt>FOO</tt>, we then need at least ''2 * n'' memory locations of the size of a machine pointer.
If we change the definition of the <tt>FOO</tt> class to make it  <tt>expanded</tt>, we then save ''n'' memory locations of the size of a machine pointer.

Be careful, because to take advantage of this gain you must also be in the very special case where [[Dynamic dispatch|dynamic dispatch]] is not useful with a type <tt>FOO</tt> variable.
Indeed, as indicated above, as soon as an expression is <tt>expanded</tt> you can no longer take advantage of dynamic dispatch.

As in the foregoing example, using an <tt>expanded</tt> class instead of an ordinary class allows memory savings.
We should also note that the objects in question can no longer be identified by their memory address.  Indeed, when the <tt>FOO</tt> type is expanded, the comparison of two variables of this type with the [[Comparison of objects#EqNeq|<tt>=</tt> operator]] no longer compares two addresses but actually compares two objects.
You must also be aware of this final point before opting to define an <tt>expanded</tt> class.
<div id="ExpandedPitfalls">

===Traps to avoid with <tt>expanded</tt> classes===
</div>
The first trap to avoid is to do with classes with many attributes.
When an <tt>expanded</tt> object is very big, passing this object as a parameter to a [[Glossary#Routine|routine]] can turn out to be much more expensive than with an ordinary object.
Indeed, for an ordinary object, only its memory address is copied onto the stack.
For an <tt>expanded</tt> object, it is the object itself, that is to say all its [[Glossary#Attribute|attributes]], which is copied during parameter passing.
Note that the same can happen during the assignment of an <tt>expanded</tt> type variable.
For very big <tt>expanded</tt> objects, assignments can turn out to lower performance.

The second trap to avoid is much more dangerous, because it does not only risk slowing down the application's execution.
This trap is to do with the mistaken interpretation that one can give to a modifying procedure call applied to an <tt>expanded</tt> object obtained by means of an indirect reading of an attribute:

 bar.foo.set_attribute(zoo)

is in fact equivakent to the following sequence of instructions:

 temporary_foo := bar.foo             -- (1) copy expanded object foo
 temporary_foo.set_attribute(zoo)     -- (2) modify the copy of foo

In effect, even though <tt>foo</tt> is an [[Glossary#Attribute|attribute]], since <tt>foo</tt>'s class is <tt>expanded</tt>, the corresponding object is copied.  So the object that you thought you were modifying with the procedure <tt>set_attribute</tt> is not the one associated with the attribute <tt>foo</tt>, but a temporary copy in memory!
Note that when <tt>foo</tt> is a [[Glossary#Function|function]] call, the previously described transformation which introduces the variable <tt>temporary_foo</tt> does not change anything.  It is just the same as if <tt>foo</tt> were a reference type.

Unfortunately, the actual compiler does not yet warn of this pitfall.
We plan to change the compiler to make it able to flag up this trap by a warning message, but this is not yet implemented.
At the moment (August 2005) no implementation has yet been decided, but it is likely that, in the future, the compiler will ask you to add the temporary variable explicitly so that you can be aware of the real problem.
Since several solutions can be envisaged, including adding new restrictions on the definition of <tt>expanded</tt> classes, it is best for the moment to be cautious in defining new <tt>expanded</tt> classes.

To avoid falling into this subtle trap, it is preferable whenever possible to avoid exporting the modification methods of <tt>expanded</tt> classes.
Best of all is not to have any modification methods at all.
Note that all the following <tt>expanded</tt> basic classes respect this rule.
There are no modification procedures in the classes:
[[library_class:BOOLEAN|<tt>BOOLEAN</tt>]],
[[library_class:CHARACTER|<tt>CHARACTER</tt>]],
[[library_class:INTEGER_8|<tt>INTEGER_8</tt>]],
[[library_class:INTEGER_16|<tt>INTEGER_16</tt>]],
[[library_class:INTEGER_32|<tt>INTEGER_32</tt>]],
[[library_class:INTEGER|<tt>INTEGER</tt>]],
[[library_class:INTEGER_64|<tt>INTEGER_64</tt>]],
[[library_class:REAL_32|<tt>REAL_32</tt>]],
[[library_class:REAL_64|<tt>REAL_64</tt>]],
[[library_class:REAL|<tt>REAL</tt>]],
[[library_class:REAL_80|<tt>REAL_80</tt>]],
[[library_class:REAL_128|<tt>REAL_128</tt>]],
[[library_class:REAL_EXTENDED|<tt>REAL_EXTENDED</tt>]] and
[[library_class:POINTER|<tt>POINTER</tt>]].
So long as the compiler is unable to warn you of this possible problem, be careful when you use <tt>expanded</tt> classes.