Writing a super-simple component

Note:: Reviewed for release 2.13.0.

This page describes the basic structure of a typical Orca component. We use Brick component as an example. When you are done, go to the next tutorial: Running a super-simple component

Source files

Go to the top directory of the Orca distribution and type the following:

$ ls src/examples/brick
brick.def  doc.dox  CMakeLists.txt  mainthread.cpp  mainthread.h

What are all these files? Here we'll just list their purpose, click on the links for the line-by-line explanation of the source.

CMakeLists.txt -- A special text file used by the CMake build system. Based on the CMakeLists.txt in the current directory and the similar files in all directories above, CMake will generate Makefiles (or equivalents for non make-based systems, e.g. MS Visual Studio)

mainthread.h and mainthread.cpp -- The one and only thread of our component.

brick.def -- The component definition file. It contains information about the component's provided and required interfaces, configuration parameters, etc. During compilation a special utility Def2Cfg is automatically called to convert brick.def file into a sample brick.cfg file which is later installed into [ORCA_INSTALL]/cfg directory. The format of .def file is described in the documentation for the Def2Cfg utility.

doc.dox -- Component documentation in Doxygen format. This documentation is generated from doc.dox. For the details of the format, see Doxygen documentation.

Each directory has a CMakeLists.txt which describes how to compile sources in that directory. CMake uses its own language to describe what needs to be done. Orca project uses standard CMake keywords and a few custom macros which we borrow from the GearBox project. Here's how you can tell where the macros are defined:

All GearBox macros start with "GBX_"
All Orca macros start with "ORCA_"
The rest are standard CMake commands and macros.

ORCA_SET_COMPONENT_NAME ( Brick )

Sets component name and 3 other related CMake variables which we'll use later in this file.

COMP_NAME -- component name.
APP_NAME -- application executable name (defaults to the component name converted to lower case)
SERVICE_NAME -- service library name (defaults to the component name prepended with project name and appended with "Service")
COMP_NAMESPACE -- component namespace (defaults to the component name converted to lower case)
COMP_INTERFACE_FLAG -- which standard interfaces the autognerated component will initialize?
COMP_ADAPTER_POLICY -- how will the component's adapter be activated: automatically or manually? This variable must contain one of the values of orcaice::ComponentInterfaceFlag. Default value assigned by this CMake macro is orcaice::AllStandardInterfaces.

Also sets APP_CTRLC_HANDLER=1 -- instructs application to install Ctrl-C Handler.

For custom values, call this function first and then override some or all of the variables manually. For example:

      ORCA_SET_COMPONENT_NAME( MyComponent )
      SET( COMP_NAMESPACE mycomp )

SET( build TRUE )

This and the following few lines determine whether we are going to build this component or not. We start with the assumption that we will and then check a few requirements sequentially. We define a variable called BUILD and set it to TRUE, i.e. "this library will be built". Failure to meet any one of the requirements will assign FALSE to this "cumulative variable".

# Check for human input
GBX_REQUIRE_OPTION( build EXE ${APP_NAME} ON )

This line calls a CMake macro which defines a user-configurable compilation option. It will be called BUILD_BRICK (BUILD + the name of our component in upper case). This option can be used as a variable to implement conditional compilation. The default value of this variable is ON, equivalent to TRUE. CMake comes with a configuration tool called ccmake. In Linux, when you type "ccmake ." in the top directory of the Orca distribution, you will see a list of all compilation options. Scroll down to BUILD_BRICK and press ENTER, the value of the option will change to OFF. Now configure (press c) and generate (press g). The build options have now been adjusted such that the Brick example will not be compiled. Repeat the process to turn the compilation back on or delete CMakeCache.txt to go back to defaults.

# libs on which our code depends would go here
# SET( dep_libs ??? )
# GBX_REQUIRE_TARGETS( build EXE ${APP_NAME} ${dep_libs} )

Pound sign marks comments. Here we comment out a line which would normally be used to specify library dependencies on one of the Orca targets (typically libraries but could be executables as well). This example does not need to be linked to any library besides the typical ones specified by UseComponentRules.cmake script.

IF( build)

Do not compile this example if any of requirements are not satisfied. In this case we only have one requirement: the wish of the user. Typically, there will be several, e.g. the OS, required libraries, etc.

    INCLUDE( ${ORCA_CMAKE_DIR}/UseComponentRules.cmake )

Most components are compiled with the same compiler options, include the same type of header files and are linked to the same libraries. These common settings are defined in a CMake file called UseComponentRules.cmake and located in [ORCA-SRC]/cmake directory. The CMake INCLUDE command imports all the commands from that file as if we typed them in here by hand.

Because the UseComponentRules.cmake script is installed with the rest of the Orca files, satellite projects which use Orca can use this script file as well. The CMake variable ORCA_CMAKE_DIR works out the correct location of Orca CMake scripts.

    FILE( GLOB srcs *.cpp )

Search for file in the current directory which fit the specified pattern and assign the list to the variables COMP_SRCS.

Instead of searching you can just list the files you need.
```
SET( srcs mainthread.cpp )
```

    ORCA_WRAP_MAINTHREAD_INTO_APP( ${srcs} )

This macro wraps an Orca component around a single thread and places that component into an Orca application. It expects to find

files named mainthread.h/cpp
which define a class ${COMP_NAMESPACE}MainThread
which derives from gbxiceutilacfr::Thread or its derivatives

If your component is non-standard (e.g. has several threads or needs to do something special in the constructor) you can create a custom Orca component. There's a macro for this case as well called WRAP_COMPONENT_INTO_APP which will place the custom component into an Orca application. If your main.cpp file needs to be nonstandard, then you have to write it by hand without the help of the macros. When writing custom component.h/cpp and main.cpp files it may be useful to take a look at the automatically generated versions. Look at the contents of brick/autogen directory (it is generated during the cmake process).

#     TARGET_LINK_LIBRARIES( ${APP_NAME} ${dep_libs} )

This would be uncommented in case we had dependencies.

    IF( ORCA_BUILD_SERVICES )
        ORCA_WRAP_MAINTHREAD_INTO_SERVICE( ${srcs} )
#         TARGET_LINK_LIBRARIES( ${SERVICE_NAME} ${dep_libs} )    
    ENDIF( ORCA_BUILD_SERVICES )

If the global option called BUILD_SERVICES is ON, create a shared library called libOrcaBrick.so (default value for ${SERVICE_NAME}). The macro wraps an Orca service around a single thread. The BUILD_SERVICES option is defined globally but can be user-configured with ccmake tool. The default setting is OFF. The macro will also schedule this service library to be installed into [ORCA-INSTALL]/lib. We could also link this library to dependencies.

    ORCA_GENERATE_CONFIG_FILE( ${APP_NAME}.def )

We call a macro to automatically generate a configuration file (.cfg) from the component definition file (.def). For more information on config files, see Orca Configuration Files.

ENDIF( build )

End of the IF block. Most of the CMake syntax you'll need you can work out from the existing files. For more details, consult the CMake documentation.

There are additional sources of information on CMake. Take a look at the CMake documentation and a GearBox build system tutorial.

mainthread.h

#ifndef MAIN_THREAD_H
#define MAIN_THREAD_H

#include <gbxsickacfr/gbxiceutilacfr/subsystemthread.h>
#include <orcaice/context.h>

namespace brick
{

class MainThread: public gbxiceutilacfr::SubsystemThread
{       
public:
    MainThread( const orcaice::Context& context );

private:    
    // from SubsystemThread
    virtual void initialise();
    virtual void work();

    orcaice::Context context_;
};

} // namespace

#endif

Line by Line Walkthrough

#include <gbxsickacfr/gbxiceutilacfr/subsystemthread.h>
#include <orcaice/context.h>

Definitions of the thread class from GearBox and orcaice::Context classes.

class MainThread: public gbxiceutilacfr::SubsystemThread

The one and only thread used by our component is derived from hydroutil::SubsystemThread class. This thread class derives from a basic hydroutil::Thread class and adds a bit of functionality to it.

Firstly, it catches all common and uncommon exception which may originate in our code. This does not mean that we should not worry about exceptions because when SubsystemThread catches an exception it does not know what to do, so it just prints out a statement and waits for the component to shut down. This behavior is useful because, without this precaution, the program would simply seg fault and you wouldn't event know what happened.

Secondly, this class simplifies usage of hydroutil::Status class by integrating functionality of hydroutil::SubStatus. Status can keep track of multiple subsystems which can be defined arbitrarily and are destinguished by a name. Typically, each thread is a subsystem. It can be in certain state and this state can be reported through the hydroutil::Status facility.

If something about the way hydroutil::SubsystemThread behaves doesn't suit your needs, you can always use the more general hydroutil::Thread.

public:
    MainThread( const orcaice::Context& context );

The context described above is passed down to our thread by the component.

    virtual void initialise();
    virtual void work();

We implement the virtual functions initialise() and work() defined in hydroutil::SubsystemThread. These two functions correspond to two states in the Subsystem state machine: Initializing and Working.

private:
    orcaice::Context context_;
};

We will keep a copy of the context so we can use it throughout the life of the thread.

mainthread.cpp

#include <iostream>
#include <orcaice/orcaice.h>

#include "mainthread.h"

using namespace std;
using namespace brick;

MainThread::MainThread( const orcaice::Context& context ) :
    SubsystemThread( context.tracer(), context.status(), "MainThread" ),
    context_(context)
{
}

void 
MainThread::initialise()
{
    setMaxHeartbeatInterval( 20.0 );

    // do some initialization here, e.g. create a hardware driver.
}

void
MainThread::work()
{
    //
    // Read configuration settings
    //
    std::string prefix = context_.tag() + ".Config.";

    int sleepIntervalMs = orcaice::getPropertyAsIntWithDefault( context_.properties(),
            prefix+"SleepIntervalMs", 1000 );

    setMaxHeartbeatInterval( sleepIntervalMs * 3.0/1000.0 );

    while( !isStopping() )
    {
        context_.tracer().debug( "Running main loop", 5 );
        health().heartbeat();

        // here we can do something useful

        IceUtil::ThreadControl::sleep(IceUtil::Time::milliSeconds(sleepIntervalMs));
    }
}

Line by Line Walkthrough

MainThread::MainThread( const orcaice::Context& context ) :
    SubsystemThread( context.tracer(), context.status(), "MainThread" ),
    context_(context)
{

A copy of the context is stored for future use. Note that the constructor is executed in the calling thread, in this case in the thread which created the component. We initialize SubsystemThread with the tracer and status objects contained in the context. We also name the subsystem corresponding to this thread. This name will be used for all status reporting.

void
MainThread::initialise()
{

This is the entry point of the thread. Now we are running in our own thread. We get here after Thread::start() is called by the component.

Executing code in a separate thread usually means that we are responsible for catching all possible exceptions. We don't do it here because hydroutil::SubsystemThread does it for us.

While this function is running, the Subsystem is in Initialising state.

    setMaxHeartbeatInterval( 20.0 );

The Status facility implements the heartbeat pattern. In this line we make a promise to Status that we will update status information at least as often as every 20 seconds. This promise will allow Status to raise an alarm if there's no update from this subsystem (thread) for longer than the specified interval.

Note that this line is equivalento to calling.

    context_.status().setMaxHeartbeatInterval( subsysName(), 20.0 );

The simplified syntax is provided by SubsystemThread.

This example doesn't actually have anything to initialize. Normally we would create and initialize hardware and algorithm drivers here.

}

void
MainThread::work()
{

We finished initializing and are now working, i.e. the Subsystem is in Working state. The state machine has transitioned automatically on return of initialise() function.

    std::string prefix = context_.tag() + ".Config.";
    int sleepIntervalMs = orcaice::getPropertyAsIntWithDefault( context_.properties(),
            prefix+"SleepIntervalMs", 1000 );

Reading in configuration parameters from the config file. All configuration properties start with the component tag, followed by a period and "Config" and another period. We form a string prefix by following this recipe. See the complete guide to Orca Configuration Files for more details.

This component has a single configuration parameter specifying the sleep interval within the main loop. It must be specified as an integer in milliseconds. See Brick documentation for the description of this config parameter.

We use a helper function from libOrcaIce which returns an integer with default. The value is looked up in the property set available from the component context using the key "Brick.Config.SleepIntervalMs". If this property is absent in the config file, the default value of 1000ms = 1s is used.

Note that we should probably do more checks on the specified value, e.g. make sure that it is not negative.

    setMaxHeartbeatInterval( sleepIntervalMs * 3.0/1000.0 );

Initialization is complete and thread behavior becomes more predictable, we can now promise to update Status more frequently.

    while( !isStopping() )
    {

We are entering the main loop. It will execute until the thread is told to stop. After that the value returned by isStopping() function will become TRUE and we will exit from the loop.

        context_.tracer().debug( "Running main loop", 5 );

We use the tracer to let the user know what's going on. The hydroutil::Tracer defines several types of trace messages: info, warning, error, and debug. Each one can be forwarded to any number of destinations: display, network, log, or file. The default configuration is shown in the documentation. E.g. the default debug-to-display setting is 0, therefore this debug statement of level 5 will not be shown on the screen. In the next tutorial we will show how to change this setting.

        health().heartbeat();

At every iteration of the loop, we call the heartbeat() function of the status object letting it know that this Subsystem is not stuck. If we promiss the status monitor to call it periodically by calling setMaxHeartbeatInterval() but then fail to call heartbeat(), the monitor will conclude that this Subsystem has stalled. This Subsystem status information can be monitored remotely using Status interface.

        // here we can do something useful

        IceUtil::ThreadControl::sleep(IceUtil::Time::milliSeconds(sleepIntervalMs));

Here we would actually perform some useful operations, e.g. read data from hardware, perform computations, send messages over the network. Instead, this example component just sleeps for the amount of times specified in the config file. The sleep function provided by libIceUtil is cross-platform.

}
}

When the component is told to stop (by calling Component::stop() function), it will tell all of its threads to stop (by calling the Thread::stop() function). After this, the return value of Thread::isStopping() will change to TRUE, we will drop out from the main loop and exit from walk(). The thread will self-destruct and at this point the the main thread "joins" this one.

brick.def

DefaultComponentTag=Brick

# Provided Interfaces
# none

# Required Interfaces
#none

# Component Configuration
Config.SleepIntervalMs.Default=1000

Line by Line Walkthrough

DefaultComponentTag=Brick

This component tag will be pre-pended to all component properties in the brick.cfg file.

# Provided Interfaces
# none

# Required Interfaces
#none

This is a super-simple example, it has no (non-standard) provided or required interfaces. The following standard interfaces are automatically provided by libOrcaIce : orca_interface_home, orca_interface_status, orca_interface_tracer. These do not need to be specified here.

# Component Configuration
Config.SleepIntervalMs.Default=1000

This will be translated into the following line of brick.cfg file "Brick.Config.SleepIntervalMs=1000"

What's Next?

When you are done, go to the next tutorial: Running a super-simple component.