Goby provides some classes that make it easy to quickly build complete applications (binaries) without having to write them from scratch.

These application-related classes are also a good reference for how to use the Transporters if you wish to build your own applications from scratch.

All the Goby applications are run using goby::run().

Application Instantiations

For a list of concrete applications included in the Goby project see

the Middleware Applications page.
the ZeroMQ Applications page.

The rest of this page describes the parent classes used to create these applications and your own custom applications.

Base class: Application

goby::middleware::Application is the base class for all Goby applications. It performs only a few simple tasks, all of which are complete when its constructor exits:

Reads configuration from the command line using a Configurator
Sets up the goby::glog debug logger
Sets up the goby::time::SimulatorSettings simulation parameters (if in use)
Sets up a goby::util::UTMGeodesy if desired.

Additionally, it provides several virtual methods:

goby::middleware::Application::initialize(): Called after construction but before run(). Optional, the default does nothing.
goby::middleware::Application::finalize(): Called just before destruction after run() completes. Optional, the default does nothing.
goby::middleware::Application::run(): Must be implemented - it is called repeatedly until goby::middleware::Application::quit() is called.

Configurators

The goby::middleware::ConfiguratorInterface can be subclassed to automatically turn command-line configuration (and may also open configuration files) into an object representing this configuration for the application to use.

Currently the implemented configurator is the goby::middleware::ProtobufConfigurator which uses a Protocol Buffers message to represent the allowable configuration for an application. From this message, allowable command-line and configuration file options are produced. These are then validated against the Protobuf Descriptor.

SingleThreadApplication

Note: most users will not instantiate a goby::middleware::SingleThreadApplication directly, but rather use a particular interprocess implementation such as goby::zeromq::SingleThreadApplication.

The goby::middleware::SingleThreadApplication is designed for users to quickly access an InterProcessPortal (via goby::middleware::SingleThreadApplication::interprocess()) and an InterVehicleForwarder (via goby::middleware::SingleThreadApplication::intervehicle()). As the name suggests, this application has no interthread layer (and thus no InterThreadTransporter).

The main (only) thread inherits from goby::middleware::Thread, which provides an optional method goby::middleware::Thread::loop() that is called regularly at the frequency passed to the constructor.

The loop() method will never be called when any of the callbacks passed to goby::middleware::StaticTransporterInterface::subscribe are called, so if the subscription callbacks block it may delay the loop() call.

MultiThreadApplication

Note: most users will not instantiate a goby::middleware::MultiThreadApplication directly, but rather use a particular interprocess implementation such as goby::zeromq::MultiThreadApplication.

The goby::middleware::MultiThreadApplication has the same interface as the SingleThreadApplication but with the addition of an InterThreadTransporter (accessed using goby::middleware::SingleThreadApplication::interthread()) as the innermost layer. This allows thread-to-thread comms.

User applications can inherit from goby::middleware::SimpleThread to create additional threads, and then manage them from the main thread with goby::middleware::MultiThreadApplication::launch_thread() and goby::middleware::MultiThreadApplication::join_thread().

All these threads use goby::middleware::Thread so they all have access to the goby::middleware::Thread::loop() method.

Writing thread-safe applications is now as a simple as ensuring that the various SimpleThread subclasses only share data via the publish/subscribe interface. This is easily accomplished by having each SimpleThread only access data within the class (no global or static variables) or data that has arrived via subscription callbacks.