gbxutilacfr::Status Class Reference

Local interface to component status. More...

#include <status.h>

Inherited by gbxutilacfr::TrivialStatus.

List of all members.

Public Member Functions

virtual void addSubsystem (const std::string &subsystem, double maxHeartbeatIntervalSec=-1.0, SubsystemType type=SubsystemStandard)=0

virtual void removeSubsystem (const std::string &subsystem)=0

virtual std::vector< std::string > subsystems ()=0

Returns a list of subsystem names.

virtual SubsystemStatus subsystemStatus (const std::string &subsystem)=0

virtual ComponentStatus componentStatus ()=0

Returns state of the component infrastructure.

virtual void setMaxHeartbeatInterval (const std::string &subsystem, double intervalSec)=0

virtual void setSubsystemType (const std::string &subsystem, SubsystemType type)=0

Sets the subsystem type which describes the expected behavior of the subsystem.

virtual void setSubsystemStatus (const std::string &subsystem, SubsystemState state, SubsystemHealth health, const std::string &message="")=0

virtual void initialising (const std::string &subsystem)=0

virtual void working (const std::string &subsystem)=0

virtual void finalising (const std::string &subsystem)=0

virtual void fault (const std::string &subsystem, const std::string &message)=0

virtual void ok (const std::string &subsystem, const std::string &message="")=0

virtual void warning (const std::string &subsystem, const std::string &message)=0

virtual void critical (const std::string &subsystem, const std::string &message)=0

virtual void heartbeat (const std::string &subsystem)=0

virtual void message (const std::string &subsystem, const std::string &message)=0

virtual void process ()=0

Detailed Description

Local interface to component status.

Overview

Status provides a machine-readable interface such that tools external to the component can monitor its status. A single Status object is meant to be shared by all threads in the library, so the implementation must be thread-safe. The idea is that Status tracks the state of a number of subsystems (most often one per thread).

Each subsystem should first call addSubsystem(), to make the Status engine aware that it exists. If any other function is called before the subsystem is added, a gbxutilacfr::Exception is thrown.

The default initial status of a subsystem is Idle with health OK.

After registering a subsystem, a subsystem can report its state and health. Each of the calls is sufficient to let the Status engine know that the subsystem is alive. The special call heartbeat() lets Status know that the subsystem is alive without modifying its status.

The 'maxHeartbeatIntervalSec' parameter tells the Status engine how often it should expect to hear from the subsystem. If no message is received from a subsystem for longer than maxHeartbeatIntervalSec, it is assumed that the subsystem has stalled (hung).

State Machine

The state machine of a subsystem is a chain of state transitions with one extra link:

Idle --> Initialising --> Working --> Finalising --> Shutdown
              |___________________________^

In addition, the system can transition to Fault state from any other state.

The following represents the Subsystem state machine in the format of State Machine Compiler (see smc.sf.net) :

Idle
Entry { init(); }
{
    init
        Initialising
        {}
}

Initialising
Entry { initialise(); }
{
    [ !isStopping ] finished
        Working
        {}

    [ isStopping ] finished
        Finalising
        {}
}

Working
Entry { work(); }
{
    finished
        Finalising
        {}
}

Finalising
Entry { finalise(); }
{
    finished
        Shutdown
        {}
}

Shutdown
{
}

Fault
{
}

Default
{
    fault
        Fault
        {}
}

See also:: Tracer
SubStatus

Member Function Documentation

virtual void gbxutilacfr::Status::addSubsystem	(	const std::string &	subsystem,
		double	maxHeartbeatIntervalSec = `-1.0`,
		SubsystemType	type = `SubsystemStandard`
	)			`[pure virtual]`

Adds a new subsystem to the system status descriptor. This command must be called before actually modifying the subsystem status, i.e. all other status commands will raise an exception if a subsystem with that name does not already exists.

An Exception is also raised when trying to add a subsystem with an existing name.

It is possible to specify the maximum expected interval between heartbeats. See setMaxHeartbeatInterval() for details.

It is also possible to describe the expected behavior of the subsystem by specifying SubsystemType. See setSubsystemType() for details.

The initial status of the new subsystem is the same as produced by the empty constructor of SubsystemStatus.

Implemented in gbxutilacfr::TrivialStatus.

virtual ComponentStatus gbxutilacfr::Status::componentStatus ( ) [pure virtual]

Returns state of the component infrastructure.

Returns component status. Component status cannot be set directly, it is the aggregate of the states and healths of its subsystems and the infrastructure.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::critical	(	const std::string &	subsystem,
		const std::string &	message
	)			`[pure virtual]`

Sets subsystem health to Critical. Diagnostic message is required. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::fault	(	const std::string &	subsystem,
		const std::string &	message
	)			`[pure virtual]`

Sets state of the subsystem to Fault. Diagnostic message is required. Subsystem health is automatically changed to Critical. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::finalising ( const std::string & subsystem ) [pure virtual]

Sets state of the subsystem to Finalising. Health and message are not affected. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::heartbeat ( const std::string & subsystem ) [pure virtual]

Record heartbeat from a subsystem: let Status know the subsystem is alive without modifying its status. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::initialising ( const std::string & subsystem ) [pure virtual]

Sets state of the subsystem to Initialising. Health and message are not affected. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::message	(	const std::string &	subsystem,
		const std::string &	message
	)			`[pure virtual]`

Change the human-readable message for a subsystem but keep the previous state and health information. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::ok	(	const std::string &	subsystem,
		const std::string &	message = `""`
	)			`[pure virtual]`

Sets subsystem health to Ok. The old message is cleared if a new one is not supplied. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::process ( ) [pure virtual]

This function must be called periodically in order for status publishing to happen and stalled susbsystems identified.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::removeSubsystem ( const std::string & subsystem ) [pure virtual]

Removes a subsystem from the status descriptor. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

Referenced by gbxutilacfr::SubStatus::~SubStatus().

virtual void gbxutilacfr::Status::setMaxHeartbeatInterval	(	const std::string &	subsystem,
		double	intervalSec
	)			`[pure virtual]`

Sets the maximum expected interval between heartbeats (in seconds). When time since the last heartbeat exceeds the specified value, the subsystem is considered stalled. Negative interval means infinite interval. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::setSubsystemStatus	(	const std::string &	subsystem,
		SubsystemState	state,
		SubsystemHealth	health,
		const std::string &	message = `""`
	)			`[pure virtual]`

Sets the status of a subsystem (both state and health) in an atomic operation. Use this method when both state and health have changed. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual SubsystemStatus gbxutilacfr::Status::subsystemStatus ( const std::string & subsystem ) [pure virtual]

Returns status of the subsystem with the given name. Throws Exception when the specified subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::warning	(	const std::string &	subsystem,
		const std::string &	message
	)			`[pure virtual]`

Sets subsystem health to Warning. Diagnostic message is required. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

virtual void gbxutilacfr::Status::working ( const std::string & subsystem ) [pure virtual]

Sets state of the subsystem to Working. Health and message are not affected. Throws Exception if the subsystem does not exist.

Implemented in gbxutilacfr::TrivialStatus.

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

status.h