Manipulating Nodes

Manipulating Nodes, aka VM objects

This page describes the main classes involved in the Object Model, which are nodes.

Nodes

A VM object is represented by a node. There are two types of nodes: StableNode and UnstableNode, representing respectively stable and unstable objects. Internally, both these classes have a single field node of type Node, but this type is private to the object model implementation. These classes are located in the source file store-decl.hh.

A node has a type and a value. The type is a const Type* and is accessible through the method type() of nodes. The value, however, is inaccessible.

Unstable nodes can be created using the method make<T>(), and can be copied from other nodes using the overloads of the method copy(). Stable nodes can only be initialized once out of another node.

For example, the following code creates an unstable node containing an integer, copies it into another unstable node, then prints the type of this node:

UnstableNode A, B;
A.make<SmallInt>(vm, 5);
B.copy(vm, A);
cout << B.type()->getName() << endl;

The static build<T>() method and the "copy constructor" of UnstableNode allow to write the above a little bit shorter.

UnstableNode A = UnstableNode::build<SmallInt>(vm, 5);
UnstableNode B(vm, A);
cout << B.type()->getName() << endl;

At this point, this shortcut might seem of little importance. But building a new value or copying an existing value into a temporary UnstableNode are such common operations that it is worth it.

Types

The class Type is defined in file type-decl.hh. It contains information about a type. Two important flags are isCopiable() and isTransient().

A type is copiable if, when copying a node of this type, it is sufficient to copy the two words of the node. A SmallInt is copiable, e.g. Big types and transients cannot be copiable. E.g., Tuple is not copiable, nor is Unbound.

A type is transient if it is meant to be mutated later. The most important example of transients are Unbound variables.

References

The type Reference is somewhat special, and used to encode aliasing. Its value is a StableNode* which is the node it points to. Because of this, the C++ type system will prevent us from making references to unstable nodes.

We illustrate this with the encoding of the following Oz code:

local A B in
   A = B
end

It can be written in C++, with our model, as:

UnstableNode A, B;
StableNode* stable = new (vm) StableNode;
stable->make<Unbound>(vm);
A.make<Reference>(vm, stable);
B.make<Reference>(vm, stable);

This code first allocate a new StableNode in the VM memory space (subject to garbage-collection). UnstableNode's can be declared statically and allocated on the stack, because it is impossible to create a reference to them. However, StableNode's must always be allocated in the VM memory space.

After having allocated the StableNode, we create an unbound variable in it. Afterwards, we create explicitly two Reference's to stable. Hence, A and B effectively refer to the same Unbound variable.

Actually, because the copy() methods of UnstableNode take care of copiable and non-copiable types, as well as ensuring that Reference's point to stable nodes only, this can be simplified as:

UnstableNode A, B;
A.make<Unbound>(vm);
B.copy(vm, A);

or, using the shortcuts presented earlier, as:

UnstableNode A = UnstableNode::build<Unbound>(vm);
UnstableNode B(vm, A);

The call to copy() (or the copy constructor) from an UnstableNode into an UnstableNode, of a value of a non-copiable type, will automatically eject that value into a newly allocated StableNode, and turn both A and B into Reference's to that stable node.

Because of this, it is very rare that you need to worry about allocating a StableNode or building Reference's yourself. It gets done automatically.

Rich nodes

With StableNode and UnstableNode, it is possible to create nodes in the store, copy them, and read their types. But you cannot do anything useful with a node without getting its value.

Actually, it is never possible to access directly the value of a node. However, the class RichNode provides a way to call methods on the value of a node. Actually, it calls (through several layers of indirection) methods of the class Implementation<T> corresponding to the type.

For example, the following code creates an unstable node with an integer. Then, it uses a RichNode to call the method value() inside class Implementation<SmallInt>. The layers of indirection make sure the method is called in the context of the actual value stored in the node, but you cannot see that.

UnstableNode node = UnstableNode::build<SmallInt>(vm, 5);
RichNode richNode = node;
cout << richNode.as<SmallInt>().value() << endl;

Note that the as<T>() has the following precondition: richNode.type() == T::type(). It is invalid (bug) to call this method with the wrong static type parameter.

Attention! In this "tutorial", we are using RichNode::as<T>() quite a lot. However, in real code, using this method is prohibited by default (some rare cases need it). Indeed, to use this method, it is necessary to know the exact data type behind a node. Now, it is generally impossible to know that, because several data types implement the same set of methods. Instead, we will use interfaces in real code.

In addition to providing an interface to actual values, rich nodes take care of following chains of Reference's. Since rich nodes are the only interface to actual values, you need never worry about references!

As an illustration, consider the following Oz code:

local A B in
   B = A
   A = 5
   {Show B}
end

This is translated into C++ as:

UnstableNode A = UnstableNode::build<Unbound>(vm);
UnstableNode B(vm, A); // remember: this ejects the Unbound into a StableNode
UnstableNode five = UnstableNode::build<SmallInt>(vm, 5);
RichNode richA = A; // follows the references
assert(richA.type() == Unbound::type());
richA.as<Unbound>().bind(vm, five); // implicit conversion of five to a RichNode
RichNode richB = B;
cout << richB.type()->getName() << endl; // displays "SmallInt"
cout << richB.as<SmallInt>().value() << endl; // displays "5"