Simulavr uses a simple object oriented system for handling the data structure creation and destruction. Since simulavr is written in C, a class system must be manually implemented and the basis for this class system is the AvrClass structure. All higher level structures are ultimately based on the AvrClass structure.
How the AvrClass structure is defined is not as import as how it is used as a base or parent class structure. A concrete example of simulavr's object system will be discussed (see Derived Class Example), but before jumping into the example, the AvrClass method functions will be introduced.
The following functions provide the user interfaces to the AvrClass structure.
All classes must provide their own creation function, <klass>_new(). The purpose of the creation function is to:
Simulavr's inheritance mechanism is a little more complicated than that of C++, but is still relatively easy to use once it is understood. An example should make it clear how the system works.
First we need to create some objects. Assume that we need to add two new objects to simulavr, foo
and bar
. To keep things simple, they are both integers. Another requirement is that any time we need to access a foo
, we'll also need to access a bar
, but sometimes we only need a bar
without a foo
. Thus, we will have a class hierarchy FooClass->BarClass->AvrClass
, or FooClass
derives from BarClass
which derives from AvrClass
. To achieve this, we create the following two data structures:
Notice that in both struct definitions, the parent element is not a pointer. When you allocate memory for a BarClass
, you automatically allocate memory for an AvrClass
at the same time. It's important that the parent is always the first element of any derived class structure.
The trick here is that once we have a class object, we can get at any object in it's class hierarchy with a simple type-cast.
Although the example above works, it assumes that the programmer knows what the FooClass
and BarClass
structures look like. The programmer has broken the encapsulation of both FooClass
and BarClass
objects. To solve this problem, we need to write method functions for both classes.
Here's the methods for BarClass:
And here's the methods for FooClass:
Take a good look at the *_new
(), *_construct
() and *_destroy
() functions in the above examples and make sure you understand what's going on. Of particluar importance is how the constructor and destructor functions are chained up along the various classes. This pattern is used extensively throughout the simulavr source code and once understood, makes some complicated concepts incredibly easy to implement.
Now that we have the method functions, we can rewrite our original example function without the broken encapsulation.
Now that's better, but you might think that we are breaking encapsulation when we cast Foo
to AvrClass
. Well, in a way we are, but since all class objects must be derived from AvrClass
either directly or indirectly, this is acceptable.
You may have noticed by this point that we haven't called avr_free() to free the memory we allocated for our objects. We called class_unref() instead. This mechanism allows us to store many references to a single object without having to keep track of all of them.
The only thing we must do when we store a reference to an object in a new variable, is call class_ref() on the object. Then, when that stored reference is no longer needed, we simply call class_unref() on the object. Once the reference count reaches zero, the object's destroy method is automatically called for us. The only hard part for us is knowing when to ref and unref the object.
Here's an example from the simulavr code for callbacks:
Notice that data
is a pointer to AvrClass
and thus can be any class defined by simulavr. CallBack
is another class which happens to store a reference to data
and must therefore call class_ref() on the data
object. When the callback is destroyed (because the reference count reached zero), the callback destroy method calls class_unref() on the data
object. It is assumed that the original reference to data
still exists when the callback is created, but may or may not exist when the callback is destroyed.