Detailed Description

Represents a state machine to be attached to a node.

Attach the state machine to a node by using Node::addChild().

The state machine provides a local state and a global state:

the local state represents the state of a single state machine
the global state takes into account all the state machines attached to the children nodes (the state with the higher priority)

In EPICS the state machine PVs will be available as "StateMachine-setState" (set the state) and "StateMachine-getState" (to retrieve the state). The PV "StateMachine-globalState" represents the global state (state with higher priority among the current node and all its children).

Transitions between the different states can happen on the same thread that requested the transition or on a different thread when the StateMachine is created with the bAsync flag set to true.

The StateMachine node also registers the following commands on the state machine node itself and on the parent node:

switchOn (causes a transition to the state ON)
start (causes a transition to the state RUNNING)
stop (causes a transition to the state ON)
switchOff (causes a transition to the state OFF)
recover (causes a transition to the state OFF)

#include <stateMachine.h>

Inheritance diagram for nds::StateMachine:

Public Member Functions
	StateMachine ()
	Initializes an empty state machine node. More...

	StateMachine (bool bAsync, stateChange_t switchOnFunction, stateChange_t switchOffFunction, stateChange_t startFunction, stateChange_t stopFunction, stateChange_t recoverFunction, allowChange_t allowStateChangeFunction)
	Construct the state machine. More...

void	setState (const state_t newState)
	Instruct the state machine to change the local state to the requested one. More...

state_t	getLocalState ()
	Returns the local state of the state machine. More...

state_t	getGlobalState ()
	Returns the global state of the node to which this state machine is attached. More...

bool	canChange (const state_t newState)
	Check if the transition to the new state is legal and is not denied by the delegate function. More...

Public Member Functions inherited from nds::Node
	Node (const std::string &name, const nodeType_t nodeType=nodeType_t::generic)
	Construct the node. More...

template<class T >
T	addChild (T child)
	Add a child node or record to this node. This node will take ownership of the added one and will take care of deleting it. More...

void	initialize (void *pDeviceObject, Factory &factory)
	Registers all the records with the control system. Call this from the root node which will take care of traversing its children and initialize them. More...

Public Member Functions inherited from nds::Base
	Base (const Base &right)
	Copy constructor. The copy will refer to the same implementation object referenced in the copied object. More...

Base &	operator= (const Base &right)
	Copy operator. The copy will refer to the same implementation object referenced in the copied object. More...

void	setExternalName (const std::string &externalName)
	Set the string to pass to the naming rules in order to build the full node name as seen by the control system. More...

virtual Port	getPort ()
	Get the Node that communicate with the device (ASYN port on EPICS, Device on Tango). Query the parent nodes if necessary. More...

const std::string &	getComponentName () const
	Return the node's name. More...

const std::string &	getFullName () const
	Return the full node's name, prepending the parents' names if necessary (e.g. "ROOT-CHANNEL1-THISNODE") More...

const std::string &	getFullExternalName () const
	Return the full node's name as seen by the control system clients. More...

const std::string &	getFullNameFromPort () const
	Return the node's name as seen by the parent Port node (the node that communicates with the device). More...

timespec	getTimestamp () const
	Get the current time. More...

void	setTimestampDelegate (getTimestampPlugin_t timestampDelegate)
	Specify the delegate function to call to get the timestamp. More...

std::ostream &	getLogger (const logLevel_t logLevel)
	Retrieve a logging stream for the specified log level. More...

bool	isLogLevelEnabled (const logLevel_t logLevel) const
	Returns true if the logging for a particular severity level has been enabled. More...

void	setLogLevel (const logLevel_t logLevel)
	Enable the logging for a particular severity level. More...

void	defineCommand (const std::string &command, const std::string &usage, const size_t numParameters, const command_t function)
	Define a command specific for the node. More...

Thread	runInThread (const std::string &name, threadFunction_t function)
	Create and run a thread using the control system facilities. More...

Thread	runInThread (threadFunction_t function)
	Create and run a thread using the control system facilities. The created thread will have the node's name. More...

Additional Inherited Members
Protected Member Functions inherited from nds::Base
	Base ()
	Initializes an empty base class.

Constructor & Destructor Documentation

nds::StateMachine::StateMachine ( )

Initializes an empty state machine node.

You must assign a valid StateMachine node before calling Node::initialize() on the root node.

nds::StateMachine::StateMachine	(	bool	bAsync,
		stateChange_t	switchOnFunction,
		stateChange_t	switchOffFunction,
		stateChange_t	startFunction,
		stateChange_t	stopFunction,
		stateChange_t	recoverFunction,
		allowChange_t	allowStateChangeFunction
	)

Construct the state machine.

Parameters

bAsync	if true then the state transitions are executed in a dedicated thread, if false then the state transitions block
switchOnFunction	function to be called to switch the node state_t::on. The function is guaranteed to be called only when the current state is state_t::off. The state machine sets the state to state_t::initializing before calling the function and to state_t::on after the function returns.
switchOffFunction	function to be called to switch the node state_t::off. The function is guaranteed to be called only when the current state is state_t::on. The state machine sets the state to state_t::switchingOff before calling the function and to state_t::off after the function returns.
startFunction	function to be called to switch to the state_t::running state. The function is guaranteed to be called only when the current state is state_t::on. The state machine sets the state to state_t::starting before calling the function and to state_t::running after the function returns.
stopFunction	function to be called to switch to the state_t::off state. The function is guaranteed to be called only when the current state is state_t::running. The state machine sets the state to state_t::switchingOff before calling the function and to state_t::off after the function returns
recoverFunction	function to be called to switch the state fron state_t::fault to state_t::off. The function is guaranteed to be called only when the current state is state_t::fault. The state machine sets the state to state_t::switchingOff before calling the function and to state_t::off after the function returns
allowStateChangeFunction	function to be called before every state switching to receive a confirmation that the state switch is allowed. The function is called only after other internal checks clear the state switch

Member Function Documentation

bool nds::StateMachine::canChange ( const state_t newState )

Check if the transition to the new state is legal and is not denied by the delegate function.

Parameters

newState the new requested state

Returns: true if the transition is legal and has not been denied, false otherwise.

state_t nds::StateMachine::getGlobalState ( )

Returns the global state of the node to which this state machine is attached.

The global state is the state with higher priority amongs the local state and the states of the children nodes of the node that owns this state machine.

Returns: the global state

state_t nds::StateMachine::getLocalState ( )

Returns the local state of the state machine.

The local state does not reflect the state of the children nodes.

Returns: the local state

void nds::StateMachine::setState ( const state_t newState )

Instruct the state machine to change the local state to the requested one.

The state machine will first check that the change from the current state to the requested state is legal: if the change is not legal then a StateMachineNoSuchTransition exception is thrown.

Then the delegate function allowStateChangeFunction defined in the state machine constructor will be called: if the function returns false then a StateMachineTransitionDenied exception will be thrown.

The state will be changed to an intermediate states while the state change delegate function is executed. If the function executing the state change fails then it can throw one of the following exceptions:

StateMachineRollBack: the state change failed and the state should go back to the initial one (the state active before the transition was requested)
any exception: the state switches to Fault.

Warning: If the state machine is asynchronous (parameter bAsync set to true in the constructor) then exceptions thrown in state change functions are silenced and only the log messages are sent to the control system.

Parameters

newState

the new desidered local state. Intermediate states can be set only by the state machine. The user can set only the following states:

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

/home/travis/build/Cosylab/nds3/include/nds3/stateMachine.h

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation