# Objects

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.

## AvrClass Methods

The following functions provide the user interfaces to the AvrClass structure.

- class_new()
- class_construct()
- class_destroy()
- class_overload_destroy()
- class_ref()
- class_unref()

All classes must provide their own creation function, <klass>_new(). The purpose of the creation function is to:

- Allocate memory for the class's data structure.
- Call class_overload_destroy() to install the class's own destroy method.
- Call the class's constructor method to fill in the data structure information.

## Derived Class Example

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:

    // Define BarClass with AvrClass as parent

    typedef struct _BarClass BarClass;
    struct _BarClass {
        AvrClass parent;
        int      bar;
    };

    // Define FooClass with BarClass as parent

    typedef struct _FooClass FooClass;
    struct _FooClass {
        BarClass parent;
        int      foo;
    };

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.

    void func( void )
    {
        int num;
        FooClass *Foo = foo_new( 12, 21 );

        // get foo from FooClass
        num = Foo->foo;

        // get bar from BarClass
        num = ((BarClass *)Foo)->bar;

        class_unref( (AvrClass *)Foo );
    }

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:`

    // BarClass allocator
    BarClass *bar_new( int bar )
    {
        BarClass *bc;

        bc = avr_new( BarClass, 1 );
        bar_construct( bc, bar );
        class_overload_destroy( (AvrClass *)bc, bar_destroy );

        return bc;
    }

    // BarClass constructor
    void bar_construct( BarClass *bc, int bar )
    {
        class_construct( (AvrClass *)bc );
        bc->bar = bar;
    }

    // BarClass destructor
    void bar_destroy( void *bc )
    {
        if (bc == NULL)
            return;

        class_destroy( bc );
    }

    // BarClass public data access methods
    int  bar_get_bar( BarClass *bc )          { return bc->bar; }
    void bar_set_bar( BarClass *bc, int val ) { bc->bar = val;  }

And here's the methods for `FooClass:`

    // FooClass allocator
    FooClass *foo_new( int foo, int bar )
    {
        FooClass *fc;

        fc = avr_new( FooClass, 1 );
        foo_construct( fc, foo, bar );
        class_overload_destroy( (AvrClass *)fc, foo_destroy );

        return fc;
    }

    // FooClass constructor
    void foo_construct( FooClass *fc, int foo, bar )
    {
        bar_construct( (BarClass *)fc, bar );
        fc->foo = foo;
    }

    // FooClass destructor
    void foo_destroy( void *fc )
    {
        if (fc == NULL)
            return;

        class_destroy( fc );
    }

    // FooClass public data access methods

    int  foo_get_foo( FooClass *fc )          { return fc->foo; }
    void foo_set_foo( FooClass *fc, int val ) { fc->foo = val;  }

    int  foo_get_bar( FooClass *fc )
    {
        return bar_get_bar( (BarClass *)fc );
    }

    void foo_set_bar( FooClass *fc, int val )
    {
        bar_set_bar( (BarClass *)fc, val );
    }

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.

    void func( void )
    {
        int num;
        FooClass *Foo = foo_new( 12, 21 );

        num = foo_get_foo( Foo );
        num = foo_get_bar( Foo );

        class_unref( (AvrClass *)Foo );
    }

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.

## Object Referencing

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:

    void callback_construct( CallBack *cb,
                             CallBack_FP func,
                             AvrClass *data )
    {
        if (cb == NULL)
            avr_error( "passed null ptr");

        class_construct( (AvrClass *)cb );

        cb->func = func;

        cb->data = data;
        class_ref( data );
    }

    void callback_destroy( void *cb )
    {
        CallBack *_cb = (CallBack *)cb;

        if (cb == NULL)
            return;

        class_unref( _cb->data );

        class_destroy( cb );
    }

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.

Automatically generated by Doxygen 1.5.5 on 7 Nov 2008.