Skip to content
Sébastien Doeraene edited this page Apr 13, 2012 · 8 revisions

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*. The type of the value is dependent on the actual type of the node. However, these are not accessible. Both StableNode and UnstableNode are "write-only" data structures. To access their content, they must be converted into a RichNode first (see later).

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, using the method init().

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

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

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);

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 and copy them. But you cannot do anything useful with a node without getting its value or its type. The class RichNode provides a way to read the type of a node, and call methods on its value. 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;
assert(richNode.is<SmallInt>());
cout << richNode.as<SmallInt>().value() << endl;

Note that the method as<T>() has is<T>() as precondition. is<T>() itself tests the following condition: richNode.type() == T::type(). It is invalid (i.e., it is a bug) to call as<T>() with the wrong static type parameter.

Attention! In this "tutorial", we are using RichNode::is<T>() and RichNode::as<T>() quite a lot. However, in real code, using these methods is prohibited by default (some rare cases need it). Indeed, to use these 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.is<Unbound>());
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"
Clone this wiki locally