Objects

The MARTe2 Object is the root class of the framework and offers the following features:

  • Automatic life cycle management using a smart pointer mechanism (see References);

  • Data driven construction (in runtime) using the class name;

  • Standard initialisation and configuration interface (more information here);

  • Standard messaging interface (more information here);

  • Allocation on a user selectable heap.

../../_images/Objects-1.png

ClassRegistryDatabase

In order to automatically register a MARTe Object into the ClassRegistryDatabase, the following macros must be used:

  • CLASS_REGISTER_DECLARATION() in the class declaration and;

  • CLASS_REGISTER(NAME_OF_THE_CLASS) in the class definition, where NAME_OF_THE_CLASS is the name of the class where the CLASS_REGISTER_DECLARATION() has been declared;

class ControllerEx1: public MARTe::Object {
public:
   /**
    * Compulsory for the class to be automatically registered.
    */
   CLASS_REGISTER_DECLARATION()

       ControllerEx1() {
   }
   //Any other class methods
   ...
};

//Usually declared in the .cpp unit file.
CLASS_REGISTER(ControllerEx1, "")

When a MARTe application starts (or when one of the shared libraries is explicitly opened, see the configuration Class= parameter here ), these macros will force the relevant class to register in the ClassRegistryDatabase.

Note

The underlying mechanism is based on the fact that these macros create a ClassRegistryItem global static variable (per class type) which will then automatically add (i.e. register) itself to the class database (see Add in ClassRegistryDatabase).

../../_images/ClassRegistryDatabase-1.png

Once the class is registered the database can be queried and new object instances created.

Examples

The following examples show how to query the contents of a ClassRegistryDatabase…

ClassRegistryDatabase example (ObjectsExample1)
  1/**
  2 * @file ObjectsExample1.cpp
  3 * @brief Source file for class ObjectsExample1
  4 * @date 14/03/2018
  5 * @author Andre' Neto
  6 *
  7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
  8 * the Development of Fusion Energy ('Fusion for Energy').
  9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
 10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
 11 * You may not use this work except in compliance with the Licence.
 12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
 13 *
 14 * @warning Unless required by applicable law or agreed to in writing, 
 15 * software distributed under the Licence is distributed on an "AS IS"
 16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 17 * or implied. See the Licence permissions and limitations under the Licence.
 18
 19 * @details This source file contains the definition of all the methods for
 20 * the class ObjectsExample1 (public, protected, and private). Be aware that some
 21 * methods, such as those inline could be defined on the header file, instead.
 22 */
 23
 24#define DLL_API
 25
 26/*---------------------------------------------------------------------------*/
 27/*                         Standard header includes                          */
 28/*---------------------------------------------------------------------------*/
 29
 30/*---------------------------------------------------------------------------*/
 31/*                         Project header includes                           */
 32/*---------------------------------------------------------------------------*/
 33#include "AdvancedErrorManagement.h"
 34#include "ClassRegistryDatabase.h"
 35#include "ErrorLoggerExample.h"
 36#include "Object.h"
 37#include "StreamString.h"
 38
 39/*---------------------------------------------------------------------------*/
 40/*                           Static definitions                              */
 41/*---------------------------------------------------------------------------*/
 42
 43/*---------------------------------------------------------------------------*/
 44/*                           Method definitions                              */
 45/*---------------------------------------------------------------------------*/
 46namespace MARTe2Tutorial {
 47/**
 48 * @brief A MARTe::Object class will be automatically registered
 49 * into the ClassRegistryDatabase.
 50 */
 51class ControllerEx1: public MARTe::Object {
 52public:
 53    CLASS_REGISTER_DECLARATION()
 54
 55    /**
 56     * @brief NOOP.
 57     */
 58ControllerEx1    () {
 59        gain = 0u;
 60    }
 61
 62    /**
 63     * A property.
 64     */
 65    MARTe::uint32 gain;
 66};
 67
 68CLASS_REGISTER(ControllerEx1, "")
 69}
 70
 71int main(int argc, char **argv) {
 72    using namespace MARTe;
 73    SetErrorProcessFunction(&ErrorProcessExampleFunction);
 74
 75    //List all the classes that have been registered.
 76    uint32 i;
 77    ClassRegistryDatabase *crdSingleton = ClassRegistryDatabase::Instance();
 78    uint32 numberOfClasses = crdSingleton->GetSize();
 79    for (i = 0u; i < numberOfClasses; i++) {
 80        const ClassRegistryItem *classRegistryItem = crdSingleton->Peek(i);
 81        const ClassProperties *classProperties = classRegistryItem->GetClassProperties();
 82        CCString className = classProperties->GetName();
 83        uint14 classUID = classProperties->GetUniqueIdentifier();
 84        REPORT_ERROR_STATIC(ErrorManagement::Information, "Counter: %d | "
 85        		"Class: %s | UID : %d", i, className.GetList(), classUID);
 86    }
 87
 88    //Find the ControllerEx1 class
 89    CCString classNameToSearch = "ControllerEx1";
 90    const ClassRegistryItem *classRegistryItem = crdSingleton->Find(classNameToSearch);
 91    if (classRegistryItem != NULL) {
 92        const ClassProperties *classProperties = classRegistryItem->GetClassProperties();
 93        CCString className = classProperties->GetName();
 94        uint14 classUID = classProperties->GetUniqueIdentifier();
 95        REPORT_ERROR_STATIC(ErrorManagement::Information, "Found class: %s |"
 96        		" UID : %d", className.GetList(), classUID);
 97    }
 98    else {
 99        REPORT_ERROR_STATIC(ErrorManagement::FatalError, "Could not find class "
100        		"with name: %s", classNameToSearch.GetList());
101    }
102
103    return 0;
104}

… and how to instantiate a new object. Note that the Build method requires as an input an HeapI implementation (this is particularly useful for embedded systems).

Object instantation example (ObjectsExample2)
  1/**
  2 * @file ObjectsExample2.cpp
  3 * @brief Source file for class ObjectsExample2
  4 * @date 14/03/2018
  5 * @author Andre' Neto
  6 *
  7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
  8 * the Development of Fusion Energy ('Fusion for Energy').
  9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
 10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
 11 * You may not use this work except in compliance with the Licence.
 12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
 13 *
 14 * @warning Unless required by applicable law or agreed to in writing, 
 15 * software distributed under the Licence is distributed on an "AS IS"
 16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 17 * or implied. See the Licence permissions and limitations under the Licence.
 18
 19 * @details This source file contains the definition of all the methods for
 20 * the class ObjectsExample2 (public, protected, and private). Be aware that some
 21 * methods, such as those inline could be defined on the header file, instead.
 22 */
 23
 24#define DLL_API
 25
 26/*---------------------------------------------------------------------------*/
 27/*                         Standard header includes                          */
 28/*---------------------------------------------------------------------------*/
 29
 30/*---------------------------------------------------------------------------*/
 31/*                         Project header includes                           */
 32/*---------------------------------------------------------------------------*/
 33#include "AdvancedErrorManagement.h"
 34#include "ClassRegistryDatabase.h"
 35#include "ErrorLoggerExample.h"
 36#include "Object.h"
 37#include "StreamString.h"
 38
 39/*---------------------------------------------------------------------------*/
 40/*                           Static definitions                              */
 41/*---------------------------------------------------------------------------*/
 42
 43/*---------------------------------------------------------------------------*/
 44/*                           Method definitions                              */
 45/*---------------------------------------------------------------------------*/
 46namespace MARTe2Tutorial {
 47/**
 48 * @brief A MARTe::Object class will be automatically registered
 49 * into the ClassRegistryDatabase.
 50 */
 51class ControllerEx1: public MARTe::Object {
 52public:
 53    CLASS_REGISTER_DECLARATION()
 54
 55    /**
 56     * @brief NOOP.
 57     */
 58    ControllerEx1() {
 59        gain = 0xffu;
 60    }
 61
 62    /**
 63     * A property.
 64     */
 65    MARTe::uint32 gain;
 66};
 67
 68CLASS_REGISTER(ControllerEx1, "")
 69}
 70
 71int main(int argc, char **argv) {
 72    using namespace MARTe;
 73    using namespace MARTe2Tutorial;
 74    SetErrorProcessFunction(&ErrorProcessExampleFunction);
 75
 76    //Find the ControllerEx1 class
 77    ClassRegistryDatabase *crdSingleton = ClassRegistryDatabase::Instance();
 78    CCString classNameToSearch = "ControllerEx1";
 79    const ClassRegistryItem *classRegistryItem = crdSingleton->Find(classNameToSearch);
 80    if (classRegistryItem != NULL) {
 81        //Get the object builder (which knows how to build classes of this type).
 82        const ObjectBuilder *builder = classRegistryItem->GetObjectBuilder();
 83        if (builder != NULL) {
 84            //Build the class using the specified memory heap
 85            Object *obj = builder->Build(GlobalObjectsDatabase::Instance()->GetStandardHeap());
 86            if (obj != NULL) {
 87                ControllerEx1 *obj2 = dynamic_cast<ControllerEx1 *>(obj);
 88                if (obj2 != NULL) {
 89                    obj2->SetName("ControllerInstance1");
 90                    REPORT_ERROR_STATIC(ErrorManagement::Information, "Successfully managed "
 91                    		"to create an instance of: %s and to set "
 92                    		"its name to %s", classNameToSearch.GetList(), obj2->GetName());
 93                }
 94            }
 95        }
 96        else {
 97            REPORT_ERROR_STATIC(ErrorManagement::FatalError, "Could not find the ObjectBuilder "
 98            		"for the class with name: %s", classNameToSearch.GetList());
 99        }
100    }
101    else {
102        REPORT_ERROR_STATIC(ErrorManagement::FatalError, "Could not find class "
103        		"with name: %s", classNameToSearch.GetList());
104    }
105
106    return 0;
107}

Instructions on how to compile and execute the examples can be found here.