Implements a finite state machine. More...

#include <state_model.h>

Inheritance diagram for isc::util::StateModel:

Public Member Functions
	StateModel ()
	Constructor.

virtual	~StateModel ()
	Destructor.

bool	didModelFail () const
	Returns whether or not the model failed.

void	endModel ()
	Conducts a normal transition to the end of the model.

std::string	getContextStr () const
	Convenience method which returns a string rendition of the current state and next event.

unsigned int	getCurrState () const
	Fetches the model's current state.

std::string	getEventLabel (const int event) const
	Fetches the label associated with an event value.

unsigned int	getLastEvent () const
	Fetches the model's last event.

unsigned int	getNextEvent () const
	Fetches the model's next event.

std::string	getPrevContextStr () const
	Convenience method which returns a string rendition of the previous state and last event.

unsigned int	getPrevState () const
	Fetches the model's previous state.

std::string	getStateLabel (const int state) const
	Fetches the label associated with an state value.

bool	isModelDone () const
	Returns whether or not the model has finished execution.

bool	isModelNew () const
	Returns whether or not the model is new.

bool	isModelPaused () const
	Returns whether or not the model is paused.

bool	isModelRunning () const
	Returns whether or not the model is running.

bool	isModelWaiting () const
	Returns whether or not the model is waiting.

void	nopStateHandler ()
	An empty state handler.

virtual void	runModel (unsigned int event)
	Processes events through the state model.

void	startModel (const int start_state)
	Begins execution of the model.

void	unpauseModel ()
	Unpauses state model.

Static Public Attributes
static const int	END_EVT = 2
	Event issued to end the model execution.

static const int	END_ST = 1
	Final state, all the state model has reached its conclusion.

static const int	FAIL_EVT = 3
	Event issued to abort the model execution.

static const int	NEW_ST = 0
	State that a state model is in immediately after construction.

static const int	NOP_EVT = 0
	Signifies that no event has occurred.

static const int	SM_DERIVED_EVENT_MIN = 11
	Value at which custom events in a derived class should begin.

static const int	SM_DERIVED_STATE_MIN = 11
	Value at which custom states in a derived class should begin.

static const int	START_EVT = 1
	Event issued to start the model execution.

Protected Member Functions
void	abortModel (const std::string &explanation)
	Aborts model execution.

void	defineEvent (unsigned int value, const std::string &label)
	Adds an event value and associated label to the set of events.

virtual void	defineEvents ()
	Populates the set of events.

void	defineState (unsigned int value, const std::string &label, StateHandler handler, const StatePausing &state_pausing=STATE_PAUSE_NEVER)
	Adds an state value and associated label to the set of states.

virtual void	defineStates ()
	Populates the set of states.

bool	doOnEntry ()
	Checks if on entry flag is true.

bool	doOnExit ()
	Checks if on exit flag is true.

const EventPtr &	getEvent (unsigned int value)
	Fetches the event referred to by value.

const StatePtr	getState (unsigned int value)
	Fetches the state referred to by value.

const StatePtr	getStateInternal (unsigned int value)
	Fetches the state referred to by value.

void	initDictionaries ()
	Initializes the event and state dictionaries.

virtual void	onModelFailure (const std::string &explanation)
	Handler for fatal model execution errors.

void	postNextEvent (unsigned int event)
	Sets the next event to the given event value.

void	setState (unsigned int state)
	Sets the current state to the given state value.

void	transition (unsigned int state, unsigned int event)
	Sets up the model to transition into given state with a given event.

virtual void	verifyEvents ()
	Validates the contents of the set of events.

virtual void	verifyStates ()
	Validates the contents of the set of states.

Detailed Description

Implements a finite state machine.

StateModel is an abstract class that provides the structure and mechanics of a basic finite state machine.

The state model implementation used is a very basic approach. The model uses numeric constants to identify events and states, and maintains dictionaries of defined events and states. Event and state definitions include a text label for logging purposes. Additionally, each state definition includes a state handler. State handlers are methods which implement the actions that need to occur when the model is "in" a given state. The implementation provides methods to add entries to and verify the contents of both dictionaries.

During model execution, the following context is tracked:

current state - The current state of the model
previous state - The state the model was in prior to the current state
next event - The next event to be consumed
last event - The event most recently consumed

When invoked, a state handler determines what it should do based upon the next event including what the next state and event should be. In other words the state transition knowledge is distributed among the state handlers rather than encapsulated in some form of state transition table.

Events "posted" from within the state handlers are "internally" triggered events. Events "posted" from outside the state model, such as through the invocation of a callback are "externally" triggered.

StateModel defines two states:

NEW_ST - State that a model is in following instantiation. It remains in this state until model execution has begun.
END_ST - State that a model is in once it has reached its conclusion.

and the following events:

START_EVT - Event used to start model execution.
NOP_EVT - Event used to signify that the model stop and wait for an external event, such as the completion of an asynchronous IO operation.
END_EVT - Event used to trigger a normal conclusion of the model. This means only that the model was traversed from start to finish, without any model violations (i.e. invalid state, event, or transition) or uncaught exceptions.
FAIL_EVT - Event to trigger an abnormal conclusion of the model. This event is posted internally when model execution fails due to a model violation or uncaught exception. It signifies that the model has reached an inoperable condition.

Derivations add their own states and events appropriate for their state model. Note that NEW_ST and END_ST do not support handlers. No work can be done (events consumed) prior to starting the model nor can work be done once the model has ended.

Model execution consists of iteratively invoking the state handler indicated by the current state which should consume the next event. As the handlers post events and/or change the state, the model is traversed. The loop stops whenever the model cannot continue without an externally triggered event or when it has reached its final state. In the case of the former, the loop may be re-entered upon arrival of the external event.

This loop is implemented in the runModel method. This method accepts an event as argument which it "posts" as the next event. It then retrieves the handler for the current state from the handler map and invokes it. runModel repeats this process until either a NOP_EVT posts or the state changes to END_ST. In other words each invocation of runModel causes the model to be traversed from the current state until it must wait or ends.

Re-entering the "loop" upon the occurrence of an external event is done by invoking runModel with the appropriate event. As before, runModel will loop until either the NOP_EVT occurs or until the model reaches its end.

A StateModel (derivation) is in the NEW_ST when constructed and remains there until it has been "started". Starting the model is done by invoking the startModel method which accepts a state as a parameter. This parameter specifies the "start" state and it becomes the current state. The first task undertaken by startModel is to initialize and verify the the event and state dictionaries. The following virtual methods are provided for this:

defineEvents - define events
verifyEvents - verifies that the expected events are defined
defineStates - defines states
verifyStates - verifies that the expected states are defined

The concept behind the verify methods is to provide an initial sanity check of the dictionaries. This should help avoid using undefined event or state values accidentally.

These methods are intended to be implemented by each "layer" in a StateModel derivation hierarchy. This allows each layer to define additional events and states.

Once the dictionaries have been properly initialized, the startModel method invokes runModel with an event of START_EVT. From this point forward and until the model reaches the END_ST or fails, it is considered to be "running". If the model encounters a NOP_EVT then it is "running" and "waiting". If the model reaches END_ST with an END_EVT it is considered "done". If the model fails (END_ST with a FAILED_EVT) it is considered "done" and "failed". There are several boolean status methods which may be used to check these conditions. Once the model has been started, defining new events or new states is illegal. It is possible to call startModel only once.

To progress from one state to the another, state handlers invoke use the method, transition. This method accepts a state and an event as parameters. These values become the current state and the next event respectively. This has the effect of entering the given state having posted the given event. The postEvent method may be used to post a new event to the current state.

Bringing the model to a normal end is done by invoking the endModel method which transitions the model to END_ST with END_EVT. Bringing the model to an abnormal end is done via the abortModel method, which transitions the model to END_ST with FAILED_EVT.

The model can be paused in the selected states. The states in which the state model should pause (always or only once) are determined within the StateModel::defineStates method. The state handlers can check whether the state machine is paused or not by calling StateModel::isModelPaused and act accordingy. Typically, the state handler would simply post the NOP_EVT when it finds that the state model is paused. The model remains paused until StateModel::unpauseModel is called.

Definition at line 274 of file state_model.h.

Constructor & Destructor Documentation

◆ StateModel()

isc::util::StateModel::StateModel ( )

Constructor.

Definition at line 89 of file state_model.cc.

◆ ~StateModel()

isc::util::StateModel::~StateModel ( )

virtual

Destructor.

Definition at line 96 of file state_model.cc.

Member Function Documentation

◆ abortModel()

void isc::util::StateModel::abortModel ( const std::string & explanation )

protected

Aborts model execution.

This method posts a FAILED_EVT and sets the current state to END_ST. It is called internally when a model violation occurs. Violations are any sort of inconsistency such as attempting to reference an invalid state, or if the next event is not valid for the current state, or a state handler throws an uncaught exception.

Parameters

explanation is text detailing the reason for aborting.

Definition at line 282 of file state_model.cc.

References END_ST, FAIL_EVT, getContextStr(), onModelFailure(), and transition().

Referenced by isc::http::HttpMessageParserBase::parseEndedHandler(), isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::poll(), and runModel().

Here is the call graph for this function:

◆ defineEvent()

void isc::util::StateModel::defineEvent	(	unsigned int	value,
		const std::string &	label )

protected

Adds an event value and associated label to the set of events.

This method is called in a thread safe context from defineEvents.

Parameters

value	is the numeric value of the event
label	is the text label of the event used in log messages and exceptions.

Exceptions

StateModelError if the model has already been started, if the value is already defined, or if the label is empty.

Definition at line 170 of file state_model.cc.

References isc::util::LabeledValueSet::add(), isc_throw, and isc::Exception::what().

Referenced by isc::d2::CheckExistsAddTransaction::defineEvents(), isc::d2::NameAddTransaction::defineEvents(), isc::d2::SimpleAddTransaction::defineEvents(), isc::d2::SimpleAddWithoutDHCIDTransaction::defineEvents(), isc::d2::NameChangeTransaction::defineEvents(), defineEvents(), and isc::http::HttpMessageParserBase::defineEvents().

Here is the call graph for this function:

◆ defineEvents()

void isc::util::StateModel::defineEvents ( )

protectedvirtual

Populates the set of events.

This method is used to construct the set of valid events. Each class within a StateModel derivation hierarchy uses this method to add any events it defines to the set. Each derivation's implementation must also call its superclass's implementation. This allows each class within the hierarchy to make contributions to the set of defined events. Implementations use the method, defineEvent(), to add event definitions. An example of the derivation's implementation follows:

void StateModelDerivation::defineEvents() {
    // Call the superclass implementation.
    StateModelDerivation::defineEvents();
 
    // Add the events defined by the derivation.
    defineEvent(SOME_CUSTOM_EVT_1, "CUSTOM_EVT_1");
    defineEvent(SOME_CUSTOM_EVT_2, "CUSTOM_EVT_2");
    :
}

This method is called in a thread safe context from initDictionaries.

Reimplemented in isc::d2::CheckExistsAddTransaction, isc::d2::CheckExistsRemoveTransaction, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, isc::d2::SimpleAddWithoutDHCIDTransaction, isc::d2::SimpleRemoveTransaction, isc::d2::SimpleRemoveWithoutDHCIDTransaction, isc::d2::NameChangeTransaction, and isc::http::HttpMessageParserBase.

Definition at line 229 of file state_model.cc.

References defineEvent(), END_EVT, FAIL_EVT, NOP_EVT, and START_EVT.

Referenced by isc::d2::NameChangeTransaction::defineEvents(), isc::http::HttpMessageParserBase::defineEvents(), and initDictionaries().

Here is the call graph for this function:

◆ defineState()

void isc::util::StateModel::defineState	(	unsigned int	value,
		const std::string &	label,
		StateHandler	handler,
		const StatePausing &	state_pausing = STATE_PAUSE_NEVER )

protected

Adds an state value and associated label to the set of states.

This method is called in a thread safe context from defineStates.

Parameters

value	is the numeric value of the state
label	is the text label of the state used in log messages and exceptions.
handler	is the bound instance method which implements the state's actions.
state_pausing	pausing mode selected for the given state. The default value is `STATE_PAUSE_NEVER`.

Exceptions

StateModelError if the model has already been started, if the value is already defined, or if the label is empty.

Definition at line 196 of file state_model.cc.

References isc::util::StateSet::add(), isc_throw, and isc::Exception::what().

Referenced by isc::d2::CheckExistsAddTransaction::defineStates(), isc::d2::CheckExistsRemoveTransaction::defineStates(), isc::d2::NameAddTransaction::defineStates(), isc::d2::NameRemoveTransaction::defineStates(), isc::d2::SimpleAddTransaction::defineStates(), isc::d2::SimpleAddWithoutDHCIDTransaction::defineStates(), isc::d2::SimpleRemoveTransaction::defineStates(), isc::d2::SimpleRemoveWithoutDHCIDTransaction::defineStates(), defineStates(), and isc::http::HttpMessageParserBase::defineStates().

Here is the call graph for this function:

◆ defineStates()

void isc::util::StateModel::defineStates ( )

protectedvirtual

Populates the set of states.

This method is used to construct the set of valid states. Each class within a StateModel derivation hierarchy uses this method to add any states it defines to the set. Each derivation's implementation must also call its superclass's implementation. This allows each class within the hierarchy to make contributions to the set of defined states. Implementations use the method, defineState(), to add state definitions. An example of the derivation's implementation follows:

void StateModelDerivation::defineStates() {
    // Call the superclass implementation.
    StateModelDerivation::defineStates();
 
    // Add the states defined by the derivation.
    defineState(SOME_ST, "SOME_ST",
                std::bind(&StateModelDerivation::someHandler, this));
    :
}

This method is called in a thread safe context from initDictionaries.

Reimplemented in isc::d2::CheckExistsAddTransaction, isc::d2::CheckExistsRemoveTransaction, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, isc::d2::SimpleAddWithoutDHCIDTransaction, isc::d2::SimpleRemoveTransaction, isc::d2::SimpleRemoveWithoutDHCIDTransaction, isc::d2::NameChangeTransaction, and isc::http::HttpMessageParserBase.

Definition at line 245 of file state_model.cc.

References defineState(), END_ST, NEW_ST, and nopStateHandler().

Referenced by isc::d2::NameChangeTransaction::defineStates(), isc::http::HttpMessageParserBase::defineStates(), and initDictionaries().

Here is the call graph for this function:

◆ didModelFail()

bool isc::util::StateModel::didModelFail ( ) const

Returns whether or not the model failed.

Returns: Boolean true if the model has reached the END_ST and the last event indicates a model violation, FAILED_EVT.

Definition at line 409 of file state_model.cc.

References END_ST, and FAIL_EVT.

◆ doOnEntry()

bool isc::util::StateModel::doOnEntry ( )

protected

Checks if on entry flag is true.

This method acts as a one-shot test of whether or not the model is transitioning into a new state. It returns true if the on-entry flag is true upon entering this method and will set the flag false prior to exit. It may be used within state handlers to perform steps that should only occur upon entry into the state.

Returns: true if the on entry flag is true, false otherwise.

Definition at line 339 of file state_model.cc.

◆ doOnExit()

bool isc::util::StateModel::doOnExit ( )

protected

Checks if on exit flag is true.

This method acts as a one-shot test of whether or not the model is transitioning out of the current state. It returns true if the on-exit flag is true upon entering this method and will set the flag false prior to exiting. It may be used within state handlers to perform steps that should only occur upon exiting out of the current state.

Returns: true if the on entry flag is true, false otherwise.

Definition at line 347 of file state_model.cc.

◆ endModel()

void isc::util::StateModel::endModel ( )

Conducts a normal transition to the end of the model.

This method posts an END_EVT and sets the current state to END_ST. It should be called by any state handler in the model from which an exit leads to the model end. In other words, if the transition out of a particular state is to the end of the model, that state's handler should call endModel.

Definition at line 271 of file state_model.cc.

References END_EVT, END_ST, and transition().

Here is the call graph for this function:

◆ getContextStr()

std::string isc::util::StateModel::getContextStr ( ) const

Convenience method which returns a string rendition of the current state and next event.

The string will be of the form:

current state: [ {state} {label} ] next event: [ {event} {label} ]

Returns: Returns a std::string of the format described above.

Definition at line 443 of file state_model.cc.

◆ getCurrState()

unsigned int isc::util::StateModel::getCurrState ( ) const

Fetches the model's current state.

This returns the model's notion of the current state. It is the state whose handler will be executed on the next iteration of the run loop.

Returns: An unsigned int representing the current state.

Definition at line 355 of file state_model.cc.

Referenced by isc::ha::HAService::adjustNetworkState(), isc::ha::HAService::conditionalLogPausedState(), isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::poll(), isc::config::JSONFeed::postBuffer(), isc::http::HttpMessageParserBase::postBuffer(), isc::d2::NameChangeTransaction::retryTransition(), and isc::ha::HAService::verboseTransition().

◆ getEvent()

const EventPtr & isc::util::StateModel::getEvent ( unsigned int value )

protected

Fetches the event referred to by value.

This method is called in a thread safe context from verifyEvents.

Parameters

value is the numeric value of the event desired.

Returns: returns a constant pointer reference to the event if found

Exceptions

StateModelError if the event is not defined.

Definition at line 186 of file state_model.cc.

References isc::util::LabeledValueSet::get(), isc_throw, and isc::util::LabeledValueSet::isDefined().

Referenced by isc::d2::CheckExistsAddTransaction::verifyEvents(), isc::d2::NameAddTransaction::verifyEvents(), isc::d2::SimpleAddTransaction::verifyEvents(), isc::d2::SimpleAddWithoutDHCIDTransaction::verifyEvents(), isc::d2::NameChangeTransaction::verifyEvents(), verifyEvents(), and isc::http::HttpMessageParserBase::verifyEvents().

Here is the call graph for this function:

◆ getEventLabel()

std::string isc::util::StateModel::getEventLabel ( const int event ) const

Fetches the label associated with an event value.

Parameters

event is the numeric event value for which the label is desired.

Returns: Returns a string containing the event label or LabeledValueSet::UNDEFINED_LABEL if the value is undefined.

Definition at line 432 of file state_model.cc.

Referenced by isc::http::HttpMessageParserBase::invalidEventError(), and isc::d2::NameChangeTransaction::transactionOutcomeString().

◆ getLastEvent()

unsigned int isc::util::StateModel::getLastEvent ( ) const

Fetches the model's last event.

Returns: An unsigned int representing the last event.

Definition at line 367 of file state_model.cc.

Referenced by isc::config::JSONFeed::feedOk(), isc::http::HttpMessageParserBase::httpParseOk(), and isc::ha::HAService::isMaintenanceCanceled().

◆ getNextEvent()

unsigned int isc::util::StateModel::getNextEvent ( ) const

Fetches the model's next event.

This returns the model's notion of the next event. It is the event that will be passed into the current state's handler on the next iteration of the run loop.

Returns: An unsigned int representing the next event.

Definition at line 373 of file state_model.cc.

◆ getPrevContextStr()

std::string isc::util::StateModel::getPrevContextStr ( ) const

Convenience method which returns a string rendition of the previous state and last event.

The string will be of the form:

previous state: [ {state} {label} ] last event: [ {event} {label} ]

Returns: Returns a std::string of the format described above.

Definition at line 454 of file state_model.cc.

◆ getPrevState()

unsigned int isc::util::StateModel::getPrevState ( ) const

Fetches the model's previous state.

Returns: An unsigned int representing the previous state.

Definition at line 361 of file state_model.cc.

◆ getState()

const StatePtr isc::util::StateModel::getState ( unsigned int value )

protected

Fetches the state referred to by value.

Parameters

value is the numeric value of the state desired.

Returns: returns a constant pointer to the state if found

Exceptions

StateModelError if the state is not defined.

Definition at line 213 of file state_model.cc.

References getStateInternal().

Referenced by isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::poll(), and runModel().

Here is the call graph for this function:

◆ getStateInternal()

const StatePtr isc::util::StateModel::getStateInternal ( unsigned int value )

protected

Fetches the state referred to by value.

This method should be called in a thread safe context.

Parameters

value is the numeric value of the state desired.

Returns: returns a constant pointer to the state if found

Exceptions

StateModelError if the state is not defined.

Definition at line 219 of file state_model.cc.

References isc::util::StateSet::getState(), isc_throw, and isc::util::LabeledValueSet::isDefined().

Here is the call graph for this function:

◆ getStateLabel()

std::string isc::util::StateModel::getStateLabel ( const int state ) const

Fetches the label associated with an state value.

Parameters

state is the numeric state value for which the label is desired.

Returns: Returns a const char* containing the state label or LabeledValueSet::UNDEFINED_LABEL if the value is undefined.

Definition at line 421 of file state_model.cc.

Referenced by isc::ha::HAService::adjustNetworkState(), and isc::ha::HAService::verboseTransition().

◆ initDictionaries()

void isc::util::StateModel::initDictionaries ( )

protected

Initializes the event and state dictionaries.

This method invokes the define and verify methods for both events and states to initialize their respective dictionaries. This method can be called only once to initialize the state model.

Exceptions

StateModelError or others indirectly, as this method calls dictionary define and verify methods.

Definition at line 144 of file state_model.cc.

References defineEvents(), defineStates(), isc_throw, verifyEvents(), verifyStates(), and isc::Exception::what().

Referenced by isc::config::JSONFeed::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpResponseParser::initModel(), and startModel().

Here is the call graph for this function:

◆ isModelDone()

bool isc::util::StateModel::isModelDone ( ) const

Returns whether or not the model has finished execution.

Returns: Boolean true if the model has reached the END_ST.

Definition at line 403 of file state_model.cc.

References END_ST.

Referenced by isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::poll(), and runModel().

◆ isModelNew()

bool isc::util::StateModel::isModelNew ( ) const

Returns whether or not the model is new.

Returns: Boolean true if the model has not been started.

Definition at line 379 of file state_model.cc.

◆ isModelPaused()

bool isc::util::StateModel::isModelPaused ( ) const

Returns whether or not the model is paused.

Returns: Boolean true if the model is paused, false otherwise.

Definition at line 415 of file state_model.cc.

Referenced by isc::ha::HAService::conditionalLogPausedState(), and isc::ha::HAService::unpause().

◆ isModelRunning()

bool isc::util::StateModel::isModelRunning ( ) const

Returns whether or not the model is running.

Returns: Boolean true if the model has been started but has not yet ended.

Definition at line 390 of file state_model.cc.

References END_ST, and NEW_ST.

◆ isModelWaiting()

bool isc::util::StateModel::isModelWaiting ( ) const

Returns whether or not the model is waiting.

Returns: Boolean true if the model is running but is waiting for an external event for resumption.

Definition at line 396 of file state_model.cc.

References END_ST, NEW_ST, and NOP_EVT.

◆ nopStateHandler()

void isc::util::StateModel::nopStateHandler ( )

An empty state handler.

This method is primarily used to permit special states, NEW_ST and END_ST to be included in the state dictionary. Currently it is an empty method.

Definition at line 140 of file state_model.cc.

Referenced by defineStates().

◆ onModelFailure()

void isc::util::StateModel::onModelFailure ( const std::string & explanation )

protectedvirtual

Handler for fatal model execution errors.

This method is called when an unexpected error renders during model execution, such as a state handler throwing an exception. It provides derivations an opportunity to act accordingly by setting the appropriate status or taking other remedial action. This allows the model execution loop to remain exception safe. This default implementation does nothing.

Parameters

explanation text detailing the error and state machine context

Reimplemented in isc::d2::NameChangeTransaction, and isc::http::HttpMessageParserBase.

Definition at line 259 of file state_model.cc.

Referenced by abortModel().

◆ postNextEvent()

void isc::util::StateModel::postNextEvent ( unsigned int event )

protected

Sets the next event to the given event value.

This updates the model's notion of the next event and is the event that will be passed into the current state's handler on the next iteration of the run loop.

Parameters

event the numeric event value to post as the next event.

Exceptions

StateModelError if the event is undefined

Definition at line 320 of file state_model.cc.

Referenced by isc::http::HttpMessageParserBase::getNextFromBuffer(), isc::config::JSONFeed::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpResponseParser::initModel(), runModel(), and isc::d2::NameChangeTransaction::sendUpdate().

◆ runModel()

void isc::util::StateModel::runModel ( unsigned int event )

virtual

Processes events through the state model.

This method implements the state model "execution loop". It uses the given event as the next event to process and begins invoking the state handler for the current state. As described above, the invoked state handler consumes the next event and then determines the next event and the current state as required to implement the business logic. The method continues to loop until the next event posted is NOP_EVT or the model ends.

Any exception thrown during the loop is caught, logged, and the model is aborted with a FAIL_EVT. The derivation's state model is expected to account for any possible errors so any that escape are treated as unrecoverable.

Note: This method is made virtual for the unit tests which require customizations allowing for more control over the state model execution.

Parameters

event is the next event to process

This method is guaranteed not to throw.

If the dictionaries aren't built bail out.

Definition at line 112 of file state_model.cc.

References abortModel(), getNextEvent(), getState(), isModelDone(), NOP_EVT, and postNextEvent().

Referenced by isc::ha::HAService::asyncSendLeaseUpdate(), isc::d2::NameChangeTransaction::operator()(), and startModel().

Here is the call graph for this function:

◆ setState()

void isc::util::StateModel::setState ( unsigned int state )

protected

Sets the current state to the given state value.

This updates the model's notion of the current state and is the state whose handler will be executed on the next iteration of the run loop. This is intended primarily for internal use and testing. It is unlikely that transitioning to a new state without a new event is of much use.

Parameters

state the new value to assign to the current state.

Exceptions

StateModelError if the state is invalid.

Definition at line 291 of file state_model.cc.

Referenced by isc::config::JSONFeed::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpResponseParser::initModel(), and startModel().

◆ startModel()

void isc::util::StateModel::startModel ( const int start_state )

Begins execution of the model.

This method invokes initDictionaries method to initialize the event and state dictionaries and then starts the model execution setting the current state to the given start state, and the event to START_EVT. This method can be called only once to start the state model.

Parameters

start_state is the state in which to begin execution.

Exceptions

StateModelError or others indirectly, as this method calls dictionary define and verify methods.

Definition at line 100 of file state_model.cc.

References initDictionaries(), runModel(), setState(), and START_EVT.

Referenced by isc::ha::HAService::HAService(), and isc::d2::NameChangeTransaction::startTransaction().

Here is the call graph for this function:

◆ transition()

void isc::util::StateModel::transition	(	unsigned int	state,
		unsigned int	event )

protected

Sets up the model to transition into given state with a given event.

This updates the model's notion of the current state and the next event to process. State handlers use this method to move from one state to the next.

Parameters

state	the new value to assign to the current state.
event	the new value to assign to the next event.

Exceptions

StateModelError if the state is invalid.

Definition at line 264 of file state_model.cc.

◆ unpauseModel()

void isc::util::StateModel::unpauseModel ( )

Unpauses state model.

Definition at line 276 of file state_model.cc.

Referenced by isc::ha::HAService::unpause().

◆ verifyEvents()

void isc::util::StateModel::verifyEvents ( )

protectedvirtual

Validates the contents of the set of events.

This method is invoked immediately after the defineEvents method and is used to verify that all the required events are defined. If the event set is determined to be invalid this method should throw a StateModelError. As with the defineEvents method, each class within a StateModel derivation hierarchy must supply an implementation which calls its superclass's implementation as well as verifying any events added by the derivation. Validating an event is accomplished by simply attempting to fetch an event by its value from the event set. An example of the derivation's implementation follows:

void StateModelDerivation::verifyEvents() {
    // Call the superclass implementation.
    StateModelDerivation::verifyEvents();
 
    // Verify the events defined by the derivation.
    getEvent(SOME_CUSTOM_EVT_1, "CUSTOM_EVT_1");
    getEvent(SOME_CUSTOM_EVT_2, "CUSTOM_EVT_2");
    :
}

This method is called in a thread safe context from initDictionaries.

Reimplemented in isc::d2::CheckExistsAddTransaction, isc::d2::CheckExistsRemoveTransaction, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, isc::d2::SimpleAddWithoutDHCIDTransaction, isc::d2::SimpleRemoveTransaction, isc::d2::SimpleRemoveWithoutDHCIDTransaction, isc::d2::NameChangeTransaction, and isc::http::HttpMessageParserBase.

Definition at line 237 of file state_model.cc.

References END_EVT, FAIL_EVT, getEvent(), NOP_EVT, and START_EVT.

Referenced by initDictionaries(), isc::d2::NameChangeTransaction::verifyEvents(), and isc::http::HttpMessageParserBase::verifyEvents().

Here is the call graph for this function:

◆ verifyStates()

void isc::util::StateModel::verifyStates ( )

protectedvirtual

Validates the contents of the set of states.

This method is invoked immediately after the defineStates method and is used to verify that all the required states are defined. If the state set is determined to be invalid this method should throw a StateModelError. As with the defineStates method, each class within a StateModel derivation hierarchy must supply an implementation which calls its superclass's implementation as well as verifying any states added by the derivation. Validating an state is accomplished by simply attempting to fetch the state by its value from the state set. An example of the derivation's implementation follows:

void StateModelDerivation::verifyStates() {
    // Call the superclass implementation.
    StateModelDerivation::verifyStates();
 
    // Verify the states defined by the derivation.
    getState(SOME_CUSTOM_EVT_2);
    :
}

This method is called in a thread safe context from initDictionaries.

Reimplemented in isc::d2::CheckExistsAddTransaction, isc::d2::CheckExistsRemoveTransaction, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, isc::d2::SimpleAddWithoutDHCIDTransaction, isc::d2::SimpleRemoveTransaction, isc::d2::SimpleRemoveWithoutDHCIDTransaction, and isc::d2::NameChangeTransaction.

Definition at line 253 of file state_model.cc.

References END_ST, getStateInternal(), and NEW_ST.

Referenced by initDictionaries(), and isc::d2::NameChangeTransaction::verifyStates().

Here is the call graph for this function:

Member Data Documentation

◆ END_EVT

const int isc::util::StateModel::END_EVT = 2

static

Event issued to end the model execution.

Definition at line 298 of file state_model.h.

Referenced by defineEvents(), endModel(), isc::config::JSONFeed::feedOk(), isc::http::HttpMessageParserBase::httpParseOk(), isc::http::HttpMessageParserBase::parseEndedHandler(), and verifyEvents().

◆ END_ST

const int isc::util::StateModel::END_ST = 1

static

Final state, all the state model has reached its conclusion.

Definition at line 282 of file state_model.h.

Referenced by abortModel(), defineStates(), didModelFail(), endModel(), isModelDone(), isModelRunning(), isModelWaiting(), isc::http::HttpMessageParserBase::parseEndedHandler(), and verifyStates().

◆ FAIL_EVT

const int isc::util::StateModel::FAIL_EVT = 3

static

Event issued to abort the model execution.

Definition at line 301 of file state_model.h.

Referenced by abortModel(), defineEvents(), didModelFail(), and verifyEvents().

◆ NEW_ST

const int isc::util::StateModel::NEW_ST = 0

static

State that a state model is in immediately after construction.

Definition at line 279 of file state_model.h.

Referenced by defineStates(), isModelRunning(), isModelWaiting(), and verifyStates().

◆ NOP_EVT

const int isc::util::StateModel::NOP_EVT = 0

static

Signifies that no event has occurred.

This is event used to interrupt the event loop to allow waiting for an IO event or when there is no more work to be done.

Definition at line 292 of file state_model.h.

Referenced by defineEvents(), isModelWaiting(), isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::poll(), runModel(), isc::d2::NameChangeTransaction::sendUpdate(), and verifyEvents().

◆ SM_DERIVED_EVENT_MIN

const int isc::util::StateModel::SM_DERIVED_EVENT_MIN = 11

static

Value at which custom events in a derived class should begin.

Definition at line 304 of file state_model.h.

◆ SM_DERIVED_STATE_MIN

const int isc::util::StateModel::SM_DERIVED_STATE_MIN = 11

static

Value at which custom states in a derived class should begin.

Definition at line 285 of file state_model.h.

◆ START_EVT

const int isc::util::StateModel::START_EVT = 1

static

Event issued to start the model execution.

Definition at line 295 of file state_model.h.

Referenced by defineEvents(), isc::config::JSONFeed::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpResponseParser::initModel(), isc::config::JSONFeed::needData(), isc::http::HttpMessageParserBase::needData(), isc::d2::CheckExistsAddTransaction::readyHandler(), isc::d2::CheckExistsRemoveTransaction::readyHandler(), isc::d2::NameAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::readyHandler(), isc::d2::SimpleAddTransaction::readyHandler(), isc::d2::SimpleAddWithoutDHCIDTransaction::readyHandler(), isc::d2::SimpleRemoveTransaction::readyHandler(), isc::d2::SimpleRemoveWithoutDHCIDTransaction::readyHandler(), startModel(), and verifyEvents().

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StateModel()

◆ ~StateModel()

Member Function Documentation

◆ abortModel()

◆ defineEvent()

◆ defineEvents()

◆ defineState()

◆ defineStates()

◆ didModelFail()

◆ doOnEntry()

◆ doOnExit()

◆ endModel()

◆ getContextStr()

◆ getCurrState()

◆ getEvent()

◆ getEventLabel()

◆ getLastEvent()

◆ getNextEvent()

◆ getPrevContextStr()

◆ getPrevState()

◆ getState()

◆ getStateInternal()

◆ getStateLabel()

◆ initDictionaries()

◆ isModelDone()

◆ isModelNew()

◆ isModelPaused()

◆ isModelRunning()

◆ isModelWaiting()

◆ nopStateHandler()

◆ onModelFailure()

◆ postNextEvent()

◆ runModel()

◆ setState()

◆ startModel()

◆ transition()

◆ unpauseModel()

◆ verifyEvents()

◆ verifyStates()

Member Data Documentation

◆ END_EVT

◆ END_ST

◆ FAIL_EVT

◆ NEW_ST

◆ NOP_EVT

◆ SM_DERIVED_EVENT_MIN

◆ SM_DERIVED_STATE_MIN

◆ START_EVT