AppState Class Reference

#include "common/appstate.hpp"

Description

The Lumiera Application state and basic initialisation.

Singleton to hold global flags directing the overall application behaviour, responsible for triggering lifecycle events and performing early initialisation tasks. AppState services are available already from static initialisation code.

Warning

don't use AppState in destructors.

Definition at line 61 of file appstate.hpp.

Public Types
enum	ExitCode {   NORMAL_EXIT ,   CLEAN_EXIT_AFTER_ERROR ,   CLEAN_EMERGENCY_EXIT ,   FAILED_EMERGENCY_EXIT }

Static Public Attributes
static lib::Depend< AppState >	instance
	get the (single) AppState instance.

Public Member Functions
void	init (lumiera::Option &options)
	evaluate the result of option parsing and maybe additional configuration such as to be able to determine the further behaviour of the application.
string	fetchSetupValue (lib::Literal key)
	access basic application setup values (from setup.ini)
void	maybeStart (lumiera::Subsys &)
	building on the state determined by init, decide if the given Subsys needs to be pulled up and, if necessary, register the Subsys and its prerequisites to be maintained throughout the application's lifetime.
ExitCode	maybeWait ()
	put the main thread of the application into a wait state, as long as some subsystem(s) registered with maybeStart still need to be maintained.
ExitCode	abort (lumiera::Error &problem)
	initiate the controlled error shutdown sequence
ExitCode	abort () noexcept
	initiate an fatal emergency shutdown, caused by an unforeseen error condition

Friends
class	lib::DependencyFactory< AppState >

Private Types
using	PSub = std::unique_ptr< SubsystemRunner >

Private Member Functions
	AppState ()
	perform initialisation triggered on first access.
	~AppState ()
	anything which should be closed as late as possible and after the normal shutdown sequence can be placed into the AppState dtor.
Private Member Functions inherited from NonCopyable
	~NonCopyable ()=default
	NonCopyable ()=default
	NonCopyable (NonCopyable const &)=delete
NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
BasicSetup	setup_
PSub	subsystems_
bool	emergency_
bool	core_up_

Constructor & Destructor Documentation

AppState()

AppState ( )

private

perform initialisation triggered on first access.

Will execute BasicSetup sequence to determine the location of the executable and read in setup.ini – Since above a LifecycleHook is installed ON_BASIC_INIT, this can be expected to happen on static initialisation of this compilation unit, if not earlier (if some other static initialisation code accesses the instance).

Note

all further application startup is conducted by main.cpp

Definition at line 71 of file appstate.cpp.

~AppState()

~AppState ( )

private

anything which should be closed as late as possible and after the normal shutdown sequence can be placed into the AppState dtor.

But note though, when the application is halted unconditionally, no dtors will be executed.

Definition at line 227 of file appstate.cpp.

References AppState::core_up_, lumiera_config_interface_destroy(), and lumiera_interfaceregistry_destroy().

Here is the call graph for this function:

Member Typedef Documentation

PSub

using PSub = std::unique_ptr<SubsystemRunner>

private

Definition at line 124 of file appstate.hpp.

Member Enumeration Documentation

ExitCode

enum ExitCode

Enumerator
NORMAL_EXIT
CLEAN_EXIT_AFTER_ERROR
CLEAN_EMERGENCY_EXIT
FAILED_EMERGENCY_EXIT

Definition at line 94 of file appstate.hpp.

Member Function Documentation

init()

void init

(

lumiera::Option &

options

)

evaluate the result of option parsing and maybe additional configuration such as to be able to determine the further behaviour of the application.

Set the internal state within this object accordingly.

Definition at line 102 of file appstate.cpp.

References _MAYBE_THROW_, AppState::core_up_, lumiera_config_interface_init(), lumiera_interfaceregistry_init(), lumiera_plugin_discover(), lumiera_plugin_load(), lumiera_plugin_register(), lumiera::ON_GLOBAL_INIT, AppState::subsystems_, and LifecycleHook::trigger().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fetchSetupValue()

string fetchSetupValue

(

lib::Literal

key

)

access basic application setup values (from setup.ini)

Definition at line 83 of file appstate.cpp.

References BasicSetup::get(), and AppState::setup_.

Here is the call graph for this function:

maybeStart()

void maybeStart

(

lumiera::Subsys &

subsys

)

building on the state determined by init, decide if the given Subsys needs to be pulled up and, if necessary, register the Subsys and its prerequisites to be maintained throughout the application's lifetime.

Definition at line 127 of file appstate.cpp.

References cStr(), and AppState::subsystems_.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

maybeWait()

ExitCode maybeWait

(

)

put the main thread of the application into a wait state, as long as some subsystem(s) registered with maybeStart still need to be maintained.

On termination of one of those components, tear down the remaining components and initiate a normal or emergency shutdown of the application, depending on the triggering component's mode of termination (exit or exception).

Returns

global application exit code

Remarks

This function is executed at the end of main(), after the necessary subsystems have been started, typically in separate threads. Thus, the main thread will enter a blocking wait, until all activated subsystems have signalled shutdown. After returning, we can proceed with the normal shutdown sequence.

The SubsystemRunner ensures that in case of a premature failure of one subsystem, the termination of all other subsystems is initiated; when detecting this case, the emergency exit sequence is called. Any error which can't be handled within this scheme, should be thrown as exception, in which case the abort handler is activated.

Definition at line 152 of file appstate.cpp.

References AppState::CLEAN_EMERGENCY_EXIT, AppState::emergency_, AppState::NORMAL_EXIT, lumiera::ON_EMERGENCY, lumiera::ON_GLOBAL_SHUTDOWN, AppState::subsystems_, and LifecycleHook::trigger().

Referenced by AppState::abort(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

abort() [1/2]

ExitCode abort

(

lumiera::Error &

problem

)

initiate the controlled error shutdown sequence

Parameters

problem

causing exception

Definition at line 178 of file appstate.cpp.

References AppState::abort(), cStr(), AppState::maybeWait(), AppState::subsystems_, and Error::what().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

abort() [2/2]

ExitCode abort ( )

noexcept

initiate an fatal emergency shutdown, caused by an unforeseen error condition

Definition at line 203 of file appstate.cpp.

References AppState::CLEAN_EXIT_AFTER_ERROR, AppState::emergency_, AppState::FAILED_EMERGENCY_EXIT, lumiera::ON_EMERGENCY, lumiera::ON_GLOBAL_SHUTDOWN, and LifecycleHook::trigger().

Referenced by AppState::abort().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

instance

lib::Depend< AppState > instance

static

get the (single) AppState instance.

storage for the Appstate Singleton instance

Warning

don't use it after the end of main()!

Definition at line 74 of file appstate.hpp.

Referenced by Config::Config(), Config::get(), and main().

setup_

BasicSetup setup_

private

Definition at line 126 of file appstate.hpp.

Referenced by AppState::fetchSetupValue().

subsystems_

PSub subsystems_

private

Definition at line 128 of file appstate.hpp.

Referenced by AppState::abort(), AppState::init(), AppState::maybeStart(), and AppState::maybeWait().

emergency_

bool emergency_

private

Definition at line 130 of file appstate.hpp.

Referenced by AppState::abort(), and AppState::maybeWait().

core_up_

bool core_up_

private

Definition at line 131 of file appstate.hpp.

Referenced by AppState::~AppState(), and AppState::init().

Friends And Related Symbol Documentation

lib::DependencyFactory< AppState >

friend class lib::DependencyFactory< AppState >

friend

Definition at line 67 of file appstate.hpp.

Inheritance diagram for AppState:

Collaboration diagram for AppState:

---

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

• appstate.hpp
• appstate.cpp