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::DspsrApplicationManager, 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.

bool is_resettable() const

Return true if the state is Aborted or RuntimeError.

inline bool is_resetting() const

Return true if a Reset is occurring.

inline bool is_aborting() const

Return true if Abort is occurring.

inline bool is_stopping_scan() const

Return true if stopping a scan.

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

inline 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

inline 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

inline 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

bool is_abortable() const

Return true if the ApplicationManager is in an abortable state.

Returns

true ApplicationManager is in an abortable state.

Returns

false ApplicationManager is not in an abortable 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 be raised as exceptions.

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 abort()

Abort any actions that the application manager is in and move to the Aborted state.

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 state

inline std::string get_state_name() const

Get the name of the current state.

Returns

Name of the current state_model state

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 implemented in the child class taking actions needed for the Idle to BeamConfigured transition.

virtual void perform_configure_scan() = 0

Scan configuration callback implemented in the child class taking actions needed for the BeamConfigured to ScanConfigured transition.

virtual void perform_scan() = 0

Scan callback implemented in the child class that is executed in the scan_thread.

Note

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 start_scan 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

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

Start Scan callback implemented in the child class taking actions needed for the StartingScan to Scanning transition.

virtual void perform_stop_scan() = 0

StopScan callback implemented in the child class taking actions needed for the Scanning to ScanConfigured transition.

virtual void perform_deconfigure_scan() = 0

Scan callback implemented in the child class taking actions needed for the ScanConfigured to BeamConfigured transition.

virtual void perform_deconfigure_beam() = 0

Scan callback implemented in the child class taking actions needed for the BeamConfigured to Idle transition.

virtual void perform_reset()

Reset callback implemented in the child class taking actions needed for the RuntimeError to Idle transition.

virtual void perform_terminate() = 0

Terminate callback implemented in the child class taking actions needed for the Idle to Terminating transition.

virtual void perform_abort_scan() = 0

Perform any necessary steps to abort a scan for the application manager.

inline virtual void perform_abort_scan_configured()

Perform any necessary steps to abort when in scan configured state.

The default implementation of this is to do nothing.

inline virtual void perform_abort_beam_configured()

Perform any necessary steps to abort when in beam configured state.

The default implementation of this is to do nothing.

inline virtual void perform_reset_subordinates()

Perform any necessary steps to reset any subordinate application managers.

DSP application managers have subordinates that need to be reset but as their state is independent of the parent the parent needs to be able able to reset them to allow for the whole component to be in a valid empty state after reset has been performed.

The default implementation of this is to do nothing.

void reset_subordinate(ApplicationManager &subordinate)

Safely reset a subordinate application manager.

When an application manager has subordinate managers it is possible that the subordinate is not in a state that could be reset, this could be because an error happened before the subordinate itself was commanded to change state or the parent itself faulted and didn’t update the subordinates. This method can be used to safely reset a subordinate application manager.

Reset can only be performed when the state is RuntimeError or Aborted. This method will check if the subordinate is in an abortable state (e.g. scanning) and call the abort command. After that it will check if the state is resettable and call the reset command if the state is resettable.

If this was successful, the subordinate will be in an Empty state.

Parameters

subordinate – the subordinate to reset.

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.