-
Notifications
You must be signed in to change notification settings - Fork 98
Manipulating Nodes
This page describes the main classes involved in the Object Model, which are 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.
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.
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.
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"