CorePlugin

How to write a CorePlugin?

The goal of this tutorial is to register a core plugin. CorePlugins can be used to execute code on startup and on shutdown of the application.

For this tutorial we want to measure how long the application was running.

---

Next Tutorial: How to add a new message type?

---

Maintenance

---

First we create the new class. Add a new file: tutorial_core_plugin.cpp and change your CMakeLists.txt and add another library:

add_library(csapex_tutorial_core
  src/tutorial_core_plugin.cpp
)
target_link_libraries(csapex_tutorial_core
  ${catkin_LIBRARIES}
)

install(TARGETS csapex_tutorial_core
        ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
        LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
        RUNTIME DESTINATION ${CATKIN_GLOBAL_BIN_DESTINATION})

Then we have to register the plugin library with plugin_lib by adding

<library path="libcsapex_tutorial_core">
   <class type="csapex::tutorial::RegisterPlugin" base_class_type="csapex::CorePlugin">
      <description>Sets up the Tutorial module</description>
   </class>
</library>

to the file plugins.xml. You should never put plug-in classes of different parent types in the same library. Libraries are only loaded when necessary, however all CorePlugins have to be loaded on start-up. Large libraries with inhomogeneous classes are therefore less efficient than multiple smaller libraries.

---

Scaffolding

Every core plug-in you want to create has to be derived from CorePlugin. Change tutorial_core_plugin.cpp to:

/// PROJECT
#include <csapex/core/core_plugin.h>
#include <csapex/utility/register_apex_plugin.h>

namespace csapex
{

namespace tutorial
{

class RegisterPlugin : public CorePlugin
{
public:
    RegisterPlugin() {}

    virtual void init(CsApexCore& core) override
    {
    }

    virtual void shutdown() override
    {
    }
};

} // namespace tutorial

} // namespace csapex

CSAPEX_REGISTER_CLASS(csapex::tutorial::RegisterPlugin, csapex::CorePlugin)

Here we use two hook functions:

virtual void init(CsApexCore& core) override

is called before the graph execution is started and

virtual void shutdown() override

just before the program is shutting down.

Timing

We now want to measure the time between the call to init and shutdown:

/// PROJECT
#include <csapex/core/core_plugin.h>
#include <csapex/utility/register_apex_plugin.h>
#include <csapex/profiling/timer.h>

namespace csapex
{

namespace tutorial
{

class RegisterPlugin : public CorePlugin
{
public:
    RegisterPlugin()
        : timer("Application Duration")
    {}

    virtual void init(CsApexCore& core) override
    {
        timer.restart();
    }

    virtual void shutdown() override
    {
        timer.finish();

        long duration_ms = timer.stopTimeMs() - timer.startTimeMs();

        std::cerr << "the program ran for " << (duration_ms / 1000.) << " seconds" << std::endl;
    }

private:
    csapex::Timer timer;
};

} // namespace tutorial

} // namespace csapex

CSAPEX_REGISTER_CLASS(csapex::tutorial::RegisterPlugin, csapex::CorePlugin)

Which will print the execution time, when the program is shut down.

---

In the next tutorial we are looking at how to create a custom message type.