Class ApplicationManager

Inheritance Relationships

Derived Types

Class Documentation

class ApplicationManager

The ApplicationManager.

Subclassed by ska::pst::dsp::DiskManager, ska::pst::dsp::DiskMonitor, ska::pst::dsp::FlowThroughManager, ska::pst::dsp::StreamWriter, ska::pst::recv::Receiver, ska::pst::smrb::DataBlockManager, ska::pst::stat::StatApplicationManager

Public Functions

ApplicationManager(const std::string &entity)

Construct a new ApplicationManager object, initialising the State to Unknown.

Parameters

entity – name of the entity for logging context

~ApplicationManager()

Destroy the ApplicationManager object.

void quit()

Issue the commands on the ApplicationManager required to terminate the main method.

bool is_idle() const

Return true if Application state model is Idle.

Returns

true if application state is Idle

Returns

false if application state is not Idle

bool is_beam_configured() const

Return true if Application beam resources are currently assigned.

Returns

true if state is one of the following: BeamConfigured, ScanConfigured, Scanning

Returns

false beam not configured

bool is_scan_configured() const

Return true if the Application has been configured for scan.

Returns

true Application has been configured for scan

Returns

false Application has not been configured for scan

bool is_scanning() const

Return true if the Application is Scanning.

Returns

true Application is in a Scanning state

Returns

false Application is not in a Scanning state

void initialise()

A post-constructor method that needs to be called to get the ApplicationManager a valid state.

Sub-classes of the ApplicationManager class need to call this at the end of its constructor. This will in turn call the perform_initialise() method and it will then put the instance into an Idle state.

virtual void validate_configure_beam(const AsciiHeader &config, ValidationContext *context) = 0

Validates Beam configuration.

Validation errors should not be raised as exceptions but added to the validation context. The caller of the method can decide what to do with the validation errors.

Parameters

  • config – Beam configuration to validate

  • context – A validation context where errors should be added.

virtual void configure_beam(const AsciiHeader &config)

Perform beam configuration on the instance.

This method validates the beam configuration, enforces the state is Idle and then executes perform_configure_beam method. On success, the state transitions to BeamConfigured, otherwise to RuntimeError and a std::exception is thrown.

Parameters

config – Beam configuration

Throws

std::exception – if an exception occurs during the configuration step.

virtual void validate_configure_scan(const AsciiHeader &config, ValidationContext *context) = 0

Validates Scan configuration.

Validation errors should not be raised as exceptions but added to the validation context. The client of the method can decide what to do with the validation errors.

Parameters

  • config – Scan configuration to validate

  • context – A validation context where errors should be added.

virtual void configure_scan(const AsciiHeader &config)

Perform scan configuration on the instance.

This method validates the scan configuration, enforces the state is BeamConfigured and then executes perform_configure_scan method. On success, the state transitions to ScanConfigured, otherwise to RuntimeError and a std::exception is thrown.

Parameters

config – Scan configuration

Throws

std::exception – if an exception occurs during the configuration step.

virtual void validate_start_scan(const AsciiHeader &config) = 0

Validates the StartScan configuration.

Validation errors should not be raised as exceptions but added to the validation context. The caller of the method can decide what to do with the validation errors.

Parameters

config – StartScan configuration to validate

virtual void start_scan(const AsciiHeader &config)

Starts a background scan thread.

This method validates the start scan configuration, enforces the state is ScanConfigured, executes perform_start_scan method, and then starts a background thread that will call the perform_scan method. It will wait for the state to transition to Scanning or RuntimeError.

If an error occurs the state will transition to RuntimeError and a std::exception is thrown.

Parameters

config – StartScan configuration

Throws

std::exception – if an exception occurs during the starting of the scan.

virtual void stop_scan()

Stops the background scan thread.

This method enforces the state is Scanning, executes perform_stop_scan method, and then waits until the background scan thread completes and is joined. On success, the state transitions to ScanConfigured, otherwise to RuntimeError and a std::exception is thrown.

Throws

std::exception – if an exception occurs during the stopping of the scan.

virtual void deconfigure_scan()

Deconfigure the ApplicationManager for scanning.

This method enforces the state is ScanConfigured, executes perform_deconfigure_scan method. On success, the state transitions to BeamConfigured otherwise to RuntimeError and a std::exception is thrown.

Throws

std::exception – if an exception occurs during the deconfiguration step.

virtual void deconfigure_beam()

Deconfigure the ApplicationManager completely and put it into an Idle state.

This method enforces the state is BeamConfigured, executes perform_deconfigure_beam method. On success, the state transitions to Idle otherwise to RuntimeError and a std::exception is thrown.

Throws

std::exception – if an exception occurs during the deconfiguration step.

virtual void reset()

Resets the ApplicationManager from RuntimeError to Idle.

This method enforces the state is RuntimeError, executes perform_reset method. On success, the state transitions to Idle otherwise to RuntimeError and a std::exception is thrown.

Resetting should not throw an error but it does this method will ensure that the state stays in a RuntimeError.

Throws

std::exception – if an exception occurs during the reset step.

inline virtual ska::pst::common::AsciiHeader &get_beam_configuration()

Get the beam configuration parameters.

Returns

ska::pst::common::AsciiHeader& beam configuration parameters

inline virtual ska::pst::common::AsciiHeader &get_scan_configuration()

Get the scan configuration parameters.

Returns

ska::pst::common::AsciiHeader& scan configuration parameters

inline virtual ska::pst::common::AsciiHeader &get_startscan_configuration()

Get the start scan configuration parameters.

Returns

ska::pst::common::AsciiHeader& start scan configuration parameters

inline State get_state() const

Get the current state.

Returns

State current state_model sate

State get_previous_state() const

Get the previous state before being in a RuntimeError state.

Returns

State

void enforce(bool required, const std::string &contextual_message) const

Utility method to enforce that required is true or else an exception is thrown.

Parameters

  • required – boolean value that must be true.

  • contextual_message – Runtime error message describing the calling context.

Throws

std::runtime_error – if required is false

void go_to_runtime_error(std::exception_ptr exception)

Utility method to move application manager to RuntimeError state.

This method is used by the gRPC interface to make sure that the application is in a faulted state, this could be because an error from the LMC.

Parameters

exception – an exception pointer to store as most recently received exception.

inline std::exception_ptr get_exception()

Return a pointer to the most recently received exception.

Returns

std::exception_ptr pointer to the most recently received exception

void force_exit(int _exit_code)

Forces an application to exit with the given exit code.

Parameters

_exit_code – return code as the application process terminates

inline const std::map<std::string, std::string> get_log_context() const

Return mapped diagnostic context key/value pairs, that the constructor initialises to: { “entity”: entity}.

Returns

const std::map<std::string, std::string> list of key/value pairs

Public Static Attributes

static constexpr int restart_exit_code = 1

Place holder for PST specific forced exit codes.

Protected Functions

void set_beam_config(const AsciiHeader &config)

Set the beam config object.

Parameters

config – beam configuration parameters

void set_scan_config(const AsciiHeader &config)

Set the scan config object.

Parameters

config – scan configuration parameters

void set_startscan_config(const AsciiHeader &config)

Set the start scan config object.

Parameters

config – start scan configuration parameters

virtual void perform_initialise() = 0

Initialisation callback to be implemented in the child class. The method should wait for the Unknown state and transition the state model to the Initialised.

virtual void perform_configure_beam() = 0

Beam configuration callback that is called by main to transition the state from Idle to BeamConfigured.

virtual void perform_configure_scan() = 0

Scan configuration callback that is called by main to transition the state from BeamConfigured to ScanConfigured.

virtual void perform_scan() = 0

Scan callback that is called by main to spawn a child thread that calls perform_start_scan. This method is expected to block until the scan is complete.

void perform_scan_safely()

Calls the perform_scan method wrapped in a try/catch statement for a std::exception. This method is run by the main in a std::thread, and so the try/catch wrapper ensures that any std::exception thrown by the child class’ perform_scan method is caught and used to transition to the RuntimeError state. Note that the child class can additionally wrap its’ perform_scan method in a try/catch statement, allowing it to perform any necessary releasing of resources.

virtual void perform_start_scan() = 0

Scan callback that is called by main to transition the state from StartingScan to Scanning. This method is expected to block until the scan is complete.

virtual void perform_stop_scan() = 0

StopScan callback that is called by main to transition the state from Scanning to ScanConfigured. This method is expected to block until state transitions to ScanConfigured.

virtual void perform_deconfigure_scan() = 0

Scan callback that is called by main to transition the state from ScanConfigured to BeamConfigured. This method is expected to block until state transitions to BeamConfigured.

virtual void perform_deconfigure_beam() = 0

Scan callback that is called by main to transition the state from BeamConfigured to Idle. This method is expected to block until state transitions to Idle.

virtual void perform_reset()

Reset callback that is called by main to transition the state from RuntimeError to Idle. This method is expected to block until state transitions to Idle.

virtual void perform_terminate() = 0

Terminate callback that is called by main to transition the state from Idle to Terminating.

Protected Attributes

AsciiHeader beam_config

Beam configuration.

AsciiHeader scan_config

Scan configuration.

AsciiHeader startscan_config

StartScan configuration.

std::exception_ptr last_exception = {nullptr}

Reference to the most recently experienced exception.

std::string entity

Name of the agent using the ApplicationManager.

std::map<std::string, std::string> log_context = {{"entity", "ApplicationManager"}}

mapped diagnostic context key/value pairs

StateModel state_model

The state model used to track the current state of the application.