********************************
** Things we don't use in C++ **
********************************

We use a very restricted form of C++ for this project.  In particular we don't
use:


RTTI
   (run time type information - only works with virtual methods anyway)
Virtual methods
   (all methods are non-virtual, which means that dispatch IS ALWAYS BASED ON
    THE DECLARED TYPE OF A POINTER, not the dynamic subtype to which it may
    actually point at runtime.  This means there is no vtable, which means the
    layout of the object is straightforward with no 'hidden fields')
Constructors
   At the moment constructors and destructors are only used for handles (see
   below).
new/malloc/delete/free
   We don't use C/C++'s memory management, since we want everything on the
   garbage collected heap.
stack allocation
   We always declare local variables as pointers to a class rather than as
   the class itself.  This means that the object is not allocated on the
   C stack, which would complicate garbage collection beyond belief.
templates
   We prefer our compiler not to be Turing powerful...
STL
   ...is just too big for the release version of the VM.  It might be OK for
   the Debug version though.

********************************
** Tags                       **
********************************

Pointers can be tagged.  This means that they always point at some fixed offset
   to the actual location of the object.  This allows us to distinguish them
   from other things like integers.  The reason this can work is that if you
   never use virtual dispatch then the object pointer is never actually used
   for anything by the C++ runtime.  The object pointer in a method invocation
   is merely passed to the method as the invisible first parameter, 'this'.

   What this means is that you can't use this->instance_variable or it's
   implicit form, direct access to the instance variable by name.  This will
   fail horribly, since the this pointer is not pointing directly at the
   object concerned.  Instead some getter-setter functions have been defined,
   which we hope the compiler will inline almost out of existence.

   The getters and setters are named fieldGet() and fieldSet() for a given
   field name.  The objects are declared with fields in order to simplify
   the fieldGet and fieldSet macros and make sizeof work as expected, but
   it is not possible to use the field names directly.
   
   In fact, in order to get around the curious layout decisions of older
   versions of GCC it is possible (and default at the moment) to compile
   in such a way that none of the fields of an object are declared at all.
   Instead, access only takes place through pointer-mangling getters and
   setters.   This means that sizeof is always incorrect for the objects!
   For debugging purposes it may be useful to have the fields be present,
   though this would be no help on gcc2 platforms.

Small integers are also tagged in some way.  Usually this means that the
   last 1 or 2 bits of the integer are not part of the number, but represent
   type information.  In a similar way, the last 2 bits of pointers (normally
   00 in a system with 4 byte words) are 'abused' to include type info.
   The type 'SmallInteger *' has some functions for manipulating small
   integers.  Note that a small integer is declared as a pointer at the C++
   level.  It is in fact not a pointer at all, but this enables it to be a
   subclass of Object* and has other desirable properties.  As mentioned above
   the C++ runtime does not actually look at the pointers (if you have no
   virtual methods) so it never notices that the SmallInteger pointers don't
   point anywhere sensible.

For each type, a method called cast exists that will convert a more general
   class type to that type.  So for example the method Class::cast(Object *a)
   can take an Object pointer or a HeapObject pointer and convert it to a
   class pointer.  In the Debug configuraitons of the system it will also
   check at runtime that the pointer is in fact a Class pointer, throwing a
   wobbly if it is not.  This check is also performed when using the
   fieldGet and fieldSet macros.

I gather that all this is fairly standard stuff when implementing a VM in C++.
Some people make use of vtables and dynamic dispatch, which may buy some
convenience at the cost of more hoops to jump through when porting to a new
C++ compiler (you have to make sure the vtable is on the heap!).

********************************
** Garbage Collection         **
********************************

Due to the garbage collector it is very important that you don't have
references to a class on the C++ stack when an allocation occurs!  Of
course an allocation can occur at any point where the VM may suspend and
at any point where a new object may be created.  After such a point
you have to reload any object references you need from objects that are
on the heap and have had their pointers updated with the new locations
of objects.

In order to make it simpler to handle objects from C++ that might move
during a GC, a set of Handle classes has been created.  These are pointer
containers that can be stack allocated and are automatically chained and
unchained by the constructors and destructors.  The GC uses the chain to
find them.  So for example:

  foo() {
    Thing *thing = Thing::create();         // oops forgot to use handle
    Symbol *symbol = Symbol::get("Thingy"); // may cause GC creating symbol
    thing->nameSet(symbol);                 // !!! thing points at old location
  }

can be rewritten correctly as:

  foo() {
    ThingHandle thing = Thing::create();    // create handle and put it in chain
    Symbol *symbol = Symbol::get("Thingy"); // may cause GC creating symbol
    thing.ref()->nameSet(symbol);           // OK, gets updated ptr from handle
  }

or to be a little paranoid use a handle for the symbol too:

  foo() {
    ThingHandle thing = Thing::create();    // create handle and put it in chain
    SymbolHandle symbol = Symbol::get("Thingy"); // may cause GC creating symbol
    thing.ref()->nameSet(symbol.ref());     // OK, gets updated ptr from handle
  }

here's an example of a mistake due to not enough use of Handles:

       Method *run = main_class->lookupMethod(name.ref()); // run not in Handle 
       if(...) {
         ...
         Stack *stack = Stack::allocateInstance(1024);  // may cause GC
         stack->call(0, run, run->literalsGet());       // !! run used after GC
         ...
       }
    }

here's a more subtle example:

  foo(thing.ref(), jobbie.bar())     // bar() can allocate

In this case the problem is that C provides no guarantees as to the order
in which ref() and bar() are called.  If bar() is called after ref() then 
the reference may be out of date.  Solve with

  Bar *bar = jobbie.bar();
  foo(thing.ref(), bar);

You can catch/reproduce many GC errors if you run TestDebug with the
__CONSTANT_GC__ define on.  This makes the system very slow of course,
but it means it will crash out in literalsGet when it finds that its
'this' pointer is in the old pre-GC part of the heap.  Running under
gdb with a breakpoint in exit() means you can see approximately where
it is going wrong.

Allocation guards.

In order to debug problems with GC and missing handles it can be useful
to use allocation guards.  These are temporary GC blocks that give a
reasonably useful error message if allocation occurs where we have
assumed that no GC can happen.

Allocation guards are switched on in any __DEBUG__ configuration and are
much much faster than running with __CONSTANT_GC__ (which can still
be useful to find out the approximate area where a problem might be.).
An allocation guard guarantees that no GC will occur between the
allocation guard and the next } (nesting is respected since it is based
on C++ scope based destructors).  Thus:


  if (...) {
    Object *thing = thingGet();     // Not using a handle for thing
    ALLOC_GUARD;
    thing->foo();                   // The alloc guard asserts that this does
                                    // not allocate.
    thing->bar();                   // thing is not in a handle and we use it
  } // alloc guard ends here


********************************
** What's left of C++?        **
********************************

Overloading
    This is just syntactic sugar anyway
Encapsulation
    Perhaps it should be possible to make getters and setters protected/private
Neat -> syntax
    For the invocation of methods.  And the rest of the class syntax.
// comments
variables declared in the middle of a block
inlined methods
    Except C has that too now and anyway they are difficult to persuade the
    compiler to actually use

-- 
EC
