Detailed Description

Implements the state machine.

Provides several PVs that allow to read and set the local and global state.

#include <stateMachineImpl.h>

Inheritance diagram for nds::StateMachineImpl:

Public Member Functions
	StateMachineImpl (bool bAsync, stateChange_t switchOnFunction, stateChange_t switchOffFunction, stateChange_t startFunction, stateChange_t stopFunction, stateChange_t recoverFunction, allowChange_t allowStateChangeFunction)
	Construct the StateMachineImpl class. More...

void	setState (const state_t newState)
	Instructs the state machine to start the transition to another state. More...

virtual state_t	getLocalState () const
	Return the local state. The local state does not reflect the state of the children. More...

virtual void	getGlobalState (timespec pTimestamp, state_t pState) const
	Return the global state. The global state takes into consideration the states of the children of the node to which the state machine is attached. More...

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

bool	isAllowedTransition (const state_t currentState, const state_t newState) const
	Returns true if the transition between two states is legal (does not check the delegate function allowChange_t declared in the constructor). More...

bool	isIntermediateState (const state_t newState) const
	Returns true if the specified state is an intermediate state (not settable directly with setState()). More...

parameters_t	commandSetState (const state_t state, const parameters_t &parameters)
	Delegate function for the commands that set the node's state. More...

virtual void	initialize (FactoryBaseImpl &controlSystem)
	Register the PVs and set the local state to state_t::off. More...

virtual void	deinitialize ()
	Wait for pending transitions to terminate and deregister the PVs.

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

Protected Member Functions
void	executeTransition (const state_t initialState, const state_t finalState, stateChange_t transitionFunction)
	Execute the state transition. May be called from a separate thread. More...

void	executeTransitionThread (const state_t initialState, const state_t finalState, stateChange_t transitionFunction)
	Thread function executed for asynchronous state machines. Calls executeTransition() and catches its exceptions. More...

void	readLocalState (timespec pTimestamp, std::int32_t pValue)
	Delegate function called to read the local state. More...

void	writeLocalState (const timespec &timestamp, const std::int32_t &value)
	Delegate function called to set the local state. More...

void	readGlobalState (timespec pTimestamp, std::int32_t pValue)
	Delegate function called to read the current global state. More...

Static Protected Member Functions
static std::string	getStateName (const state_t state)
	Returns the human readable name for the requested state. More...

Protected Attributes
bool	m_bAsync
	If true then the state transitions happen in another thread (held by m_transitionThread)

std::thread	m_transitionThread
	Thread that is used to execute the state transition when bAsync is true in the constructor.

std::mutex	m_lockTransitionThread
	Lock the access to m_transitionThread.

state_t	m_localState
	The local state.

timespec	m_stateTimestamp
	The timestamp of the last local state change.

stateChange_t	m_switchOn
	Delegate function for the switch-on transition.

stateChange_t	m_switchOff
	Delegate function for the switch-off transition.

stateChange_t	m_start
	Delegate function for the start transition.

stateChange_t	m_stop
	Delegate function for the stop transition.

stateChange_t	m_recover
	Delegate function for the recover transition.

allowChange_t	m_allowChange
	Delegate function for the Allow-Change function.

std::shared_ptr < PVDelegateInImpl < std::int32_t > >	m_pGetStatePV
	Delegate PV to which the local state change is pushed.

Constructor & Destructor Documentation

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

Construct the StateMachineImpl class.

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::StateMachineImpl::canChange ( const state_t newState ) const

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.

parameters_t nds::StateMachineImpl::commandSetState	(	const state_t	state,
		const parameters_t &	parameters
	)

Delegate function for the commands that set the node's state.

Parameters

state	the state to set
parameters	parameters passed to the delegate (ignored)

Returns: parameters returned by the command delegates (empty)

void nds::StateMachineImpl::executeTransition	(	const state_t	initialState,
		const state_t	finalState,
		stateChange_t	transitionFunction
	)

protected

Execute the state transition. May be called from a separate thread.

Parameters

initialState	the initial state
finalState	the final state
transitionFunction	the delegate function that execute the transition

void nds::StateMachineImpl::executeTransitionThread	(	const state_t	initialState,
		const state_t	finalState,
		stateChange_t	transitionFunction
	)

protected

Thread function executed for asynchronous state machines. Calls executeTransition() and catches its exceptions.

Parameters

initialState	the initial state
finalState	the final state
transitionFunction	the delegate function that executes the transition

virtual void nds::StateMachineImpl::getGlobalState	(	timespec *	pTimestamp,
		state_t *	pState
	)		const

virtual

Return the global state. The global state takes into consideration the states of the children of the node to which the state machine is attached.

Parameters

pTimestamp	pointer to a variable that will be filled with the timestamp
pState	pointer to a variable that will be filled with the current global state

Reimplemented from nds::NodeImpl.

virtual state_t nds::StateMachineImpl::getLocalState ( ) const

virtual

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

Returns: the current local state

Reimplemented from nds::NodeImpl.

static std::string nds::StateMachineImpl::getStateName ( const state_t state )

staticprotected

Returns the human readable name for the requested state.

Parameters

state the state for which the name is required

Returns: the human readable name of the state

virtual void nds::StateMachineImpl::initialize ( FactoryBaseImpl & controlSystem )

virtual

Register the PVs and set the local state to state_t::off.

Parameters

controlSystem the control system on which the node must be registered

Reimplemented from nds::NodeImpl.

bool nds::StateMachineImpl::isAllowedTransition	(	const state_t	currentState,
		const state_t	newState
	)		const

Returns true if the transition between two states is legal (does not check the delegate function allowChange_t declared in the constructor).

Parameters

currentState	the initial state
newState	the final state

Returns: true if the state change is legal, false otherwise

bool nds::StateMachineImpl::isIntermediateState ( const state_t newState ) const

Returns true if the specified state is an intermediate state (not settable directly with setState()).

Parameters

newState the state for which the information is required

Returns: true if the specified state is intermediate

void nds::StateMachineImpl::readGlobalState	(	timespec *	pTimestamp,
		std::int32_t *	pValue
	)

protected

Delegate function called to read the current global state.

Parameters

pTimestamp	pointer tp
pValue

void nds::StateMachineImpl::readLocalState	(	timespec *	pTimestamp,
		std::int32_t *	pValue
	)

protected

Delegate function called to read the local state.

Parameters

pTimestamp	pointer to a value that will be filled with the timestamp of the last state change
pValue	pointer to a value that will be written with the current local state

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

Instructs the state machine to start the transition to another state.

If the machine cannot start the transition to the desidered state then one of the following exceptions is thrown:

StateMachineForbidden: one of the intermediate states has been specified in the parameter. Only the state machine itself can change the state to switchingOff, initializing, stopping and starting.

Parameters

newState

the new requested state. Only the following states are allowed:

void nds::StateMachineImpl::writeLocalState	(	const timespec &	timestamp,
		const std::int32_t &	value
	)

protected

Delegate function called to set the local state.

Parameters

timestamp	ignored. The timestamp is taken from the node
value	requested state

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

/home/travis/build/Cosylab/nds3/include/nds3/impl/stateMachineImpl.h

Detailed Description

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation