SubsystemRunner Class Reference

#include "common/subsystem-runner.hpp"

Description

Implementation helper for managing execution of a collection of subsystems, which may depend on one another and execute in parallel.

Properties of the subsystems are available through Subsys object refs, which act as handle. In this context, »Subsystem« is an abstraction and doesn't necessarily correspond to a single component, interface or plugin. It may well be a complete layer of the application (e.g. the GUI).

Protocol of operation

The SubsystemRunner is to be configured with a lumiera::Option object first. Then, primary subsystems are provided for eventual startup, which may depend on conditions defined by the subsystem. When it turns out (by investigating the options) that a Subsystem is actually to be pulled up, all of its prerequisite subsystems shall be started beforehand. Problems while starting may result in throwing an exception, which is not handled here and aborts the whole operation. On startup, a callback signal slot is reserved for each subsystem to notify the SubsystemRunner on termination. It is the liability of the subsystems to ensure this callback functor is activated reliably, irrespective of what actually causes the termination; failure to do so may deadlock the whole System.

Usually, the startup process is conducted from one (main) thread, which enters the blocking wait after starting the subsystems. Awakened by some termination signal from one of the subsystems, termination of any remaining subsystems will be triggered. The wait() function returns after shutdown of all subsystems, signalling an emergency situation with its return value. In this context, emergency is defined by encountering an top-level exception in any Subsystem, reported by a non-empty error string in the sigTerm handler. An emergency thus jeopardises the ability to wind-down the all parts of the application reliably.

Todo:

2018 this component works well but could be (re)written in a cleaner way ////////////////////////TICKET #1177

See also

lumiera::AppState

lumiera::Subsys

main.cpp

Definition at line 109 of file subsystem-runner.hpp.

Public Member Functions
	SubsystemRunner (Option &opts)
void	maybeRun (Subsys &susy)
void	shutdownAll ()
void	triggerEmergency (bool cond)
bool	wait ()

Private Member Functions
bool	isEmergency ()
bool	allDead ()
void	triggerStartup (Subsys *susy)
void	sigTerm (Subsys *susy, string *problem)

Private Attributes
Option &	opts_
volatile bool	emergency_
vector< Subsys * >	running_

Additional Inherited Members
Static Public Member Functions inherited from Sync< CONF >
static Monitor &	getMonitor (Sync const *forThis)

Constructor & Destructor Documentation

SubsystemRunner()

SubsystemRunner ( Option &  opts )

inline

Definition at line 121 of file subsystem-runner.hpp.

Member Function Documentation

isEmergency()

bool isEmergency ( )

inlineprivate

Definition at line 116 of file subsystem-runner.hpp.

References SubsystemRunner::emergency_.

Referenced by SubsystemRunner::wait().

Here is the caller graph for this function:

allDead()

bool allDead ( )

inlineprivate

Definition at line 117 of file subsystem-runner.hpp.

References SubsystemRunner::running_.

Referenced by SubsystemRunner::wait().

Here is the caller graph for this function:

maybeRun()

void maybeRun ( Subsys &  susy )

inline

Definition at line 127 of file subsystem-runner.hpp.

References Subsys::isRunning(), SubsystemRunner::opts_, Subsys::shouldStart(), and SubsystemRunner::triggerStartup().

Referenced by SubsystemRunner_test::dependentSubsys_complete_cycle(), SubsystemRunner_test::dependentSubsys_start_failure(), SubsystemRunner_test::singleSubsys_complete_cycle(), SubsystemRunner_test::singleSubsys_emegency_exit(), and SubsystemRunner_test::singleSubsys_start_failure().

Here is the call graph for this function:

Here is the caller graph for this function:

shutdownAll()

void shutdownAll ( )

inline

Definition at line 136 of file subsystem-runner.hpp.

References SubsystemRunner::running_, and Subsys::triggerShutdown().

Referenced by SubsystemRunner::sigTerm().

Here is the call graph for this function:

Here is the caller graph for this function:

triggerEmergency()

void triggerEmergency ( bool  cond )

inline

Definition at line 143 of file subsystem-runner.hpp.

References SubsystemRunner::emergency_.

Referenced by SubsystemRunner::sigTerm().

Here is the caller graph for this function:

wait()

bool wait ( )

inline

Definition at line 150 of file subsystem-runner.hpp.

References SubsystemRunner::allDead(), and SubsystemRunner::isEmergency().

Referenced by SubsystemRunner_test::dependentSubsys_complete_cycle(), SubsystemRunner_test::dependentSubsys_start_failure(), SubsystemRunner_test::singleSubsys_complete_cycle(), SubsystemRunner_test::singleSubsys_emegency_exit(), and SubsystemRunner_test::singleSubsys_start_failure().

Here is the call graph for this function:

Here is the caller graph for this function:

triggerStartup()

void triggerStartup ( Subsys *  susy )

inlineprivate

Definition at line 163 of file subsystem-runner.hpp.

References cStr(), Subsys::getPrerequisites(), Subsys::isRunning(), SubsystemRunner::opts_, SubsystemRunner::running_, SubsystemRunner::sigTerm(), Subsys::start(), Subsys::triggerShutdown(), and SubsystemRunner::triggerStartup().

Referenced by SubsystemRunner::maybeRun(), and SubsystemRunner::triggerStartup().

Here is the call graph for this function:

Here is the caller graph for this function:

sigTerm()

void sigTerm ( Subsys *  susy, string *  problem  )

inlineprivate

Parameters

problem

called from subsystem on termination

Definition at line 195 of file subsystem-runner.hpp.

References cStr(), Subsys::isRunning(), SubsystemRunner::running_, SubsystemRunner::shutdownAll(), and SubsystemRunner::triggerEmergency().

Referenced by SubsystemRunner::triggerStartup().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

opts_

Option& opts_

private

Definition at line 112 of file subsystem-runner.hpp.

Referenced by SubsystemRunner::maybeRun(), and SubsystemRunner::triggerStartup().

emergency_

volatile bool emergency_

private

Definition at line 113 of file subsystem-runner.hpp.

Referenced by SubsystemRunner::isEmergency(), and SubsystemRunner::triggerEmergency().

running_

vector<Subsys*> running_

private

Definition at line 114 of file subsystem-runner.hpp.

Referenced by SubsystemRunner::allDead(), SubsystemRunner::shutdownAll(), SubsystemRunner::sigTerm(), and SubsystemRunner::triggerStartup().

Inheritance diagram for SubsystemRunner:

Collaboration diagram for SubsystemRunner:

---

The documentation for this class was generated from the following file:

• subsystem-runner.hpp