Lumiera  0.pre.03
»edit your freedom«
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 70 of file appstate.hpp.

Public Types

enum  ExitCode {
  NORMAL_EXIT,
  CLEAN_EXIT_AFTER_ERROR,
  CLEAN_EMERGENCY_EXIT,
  FAILED_EMERGENCY_EXIT
}
 

Public Member Functions

ExitCode abort (lumiera::Error &problem)
 initiate the controlled error shutdown sequence More...
 
ExitCode abort () noexcept
 initiate an fatal emergency shutdown, caused by an unforeseen error condition
 
string fetchSetupValue (lib::Literal key)
 access basic application setup values (from setup.ini)
 
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. More...
 
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. More...
 

Static Public Attributes

static lib::Depend< AppStateinstance
 get the (single) AppState instance. More...
 

Friends

class lib::DependencyFactory< AppState >
 

Private Types

using PSub = std::unique_ptr< SubsystemRunner >
 

Private Member Functions

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

Private Attributes

bool core_up_
 
bool emergency_
 
BasicSetup setup_
 
PSub subsystems_
 

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 81 of file appstate.cpp.

References AppState::instance, and LUMIERA_LOCATION_OF_BOOTSTRAP_INI.

◆ ~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 237 of file appstate.cpp.

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 112 of file appstate.cpp.

References lumiera_interfaceregistry_init().

+ Here is the call 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 162 of file appstate.cpp.

References lumiera::ON_EMERGENCY, lumiera::ON_GLOBAL_SHUTDOWN, and LifecycleHook::trigger().

+ Here is the call graph for this function:

◆ abort()

ExitCode abort ( lumiera::Error problem)

initiate the controlled error shutdown sequence

Parameters
problemcausing exception

Definition at line 188 of file appstate.cpp.

References Error::what().

+ Here is the call 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 83 of file appstate.hpp.

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

+ Inheritance diagram for AppState:
+ Collaboration diagram for AppState:

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