Kea  2.3.5-git
isc::util::StateModel Class Reference

Implements a finite state machine. More...

#include <state_model.h>

+ Inheritance diagram for isc::util::StateModel:

Public Member Functions

 StateModel ()
 Constructor. More...
 
virtual ~StateModel ()
 Destructor. More...
 
bool didModelFail () const
 Returns whether or not the model failed. More...
 
void endModel ()
 Conducts a normal transition to the end of the model. More...
 
std::string getContextStr () const
 Convenience method which returns a string rendition of the current state and next event. More...
 
unsigned int getCurrState () const
 Fetches the model's current state. More...
 
std::string getEventLabel (const int event) const
 Fetches the label associated with an event value. More...
 
unsigned int getLastEvent () const
 Fetches the model's last event. More...
 
unsigned int getNextEvent () const
 Fetches the model's next event. More...
 
std::string getPrevContextStr () const
 Convenience method which returns a string rendition of the previous state and last event. More...
 
unsigned int getPrevState () const
 Fetches the model's previous state. More...
 
std::string getStateLabel (const int state) const
 Fetches the label associated with an state value. More...
 
bool isModelDone () const
 Returns whether or not the model has finished execution. More...
 
bool isModelNew () const
 Returns whether or not the model is new. More...
 
bool isModelPaused () const
 Returns whether or not the model is paused. More...
 
bool isModelRunning () const
 Returns whether or not the model is running. More...
 
bool isModelWaiting () const
 Returns whether or not the model is waiting. More...
 
void nopStateHandler ()
 An empty state handler. More...
 
virtual void runModel (unsigned int event)
 Processes events through the state model. More...
 
void startModel (const int start_state)
 Begins execution of the model. More...
 
void unpauseModel ()
 Unpauses state model. More...
 

Static Public Attributes

static const int NEW_ST = 0
 State that a state model is in immediately after construction. More...
 
static const int END_ST = 1
 Final state, all the state model has reached its conclusion. More...
 
static const int SM_DERIVED_STATE_MIN = 11
 Value at which custom states in a derived class should begin. More...
 
static const int NOP_EVT = 0
 Signifies that no event has occurred. More...
 
static const int START_EVT = 1
 Event issued to start the model execution. More...
 
static const int END_EVT = 2
 Event issued to end the model execution. More...
 
static const int FAIL_EVT = 3
 Event issued to abort the model execution. More...
 
static const int SM_DERIVED_EVENT_MIN = 11
 Value at which custom events in a derived class should begin. More...
 

Protected Member Functions

void abortModel (const std::string &explanation)
 Aborts model execution. More...
 
void defineEvent (unsigned int value, const std::string &label)
 Adds an event value and associated label to the set of events. More...
 
virtual void defineEvents ()
 Populates the set of events. More...
 
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. More...
 
virtual void defineStates ()
 Populates the set of states. More...
 
bool doOnEntry ()
 Checks if on entry flag is true. More...
 
bool doOnExit ()
 Checks if on exit flag is true. More...
 
const EventPtrgetEvent (unsigned int value)
 Fetches the event referred to by value. More...
 
const StatePtr getState (unsigned int value)
 Fetches the state referred to by value. More...
 
const StatePtr getStateInternal (unsigned int value)
 Fetches the state referred to by value. More...
 
void initDictionaries ()
 Initializes the event and state dictionaries. More...
 
virtual void onModelFailure (const std::string &explanation)
 Handler for fatal model execution errors. More...
 
void postNextEvent (unsigned int event)
 Sets the next event to the given event value. More...
 
void setState (unsigned int state)
 Sets the current state to the given state value. More...
 
void transition (unsigned int state, unsigned int event)
 Sets up the model to transition into given state with a given event. More...
 
virtual void verifyEvents ()
 Validates the contents of the set of events. More...
 
virtual void verifyStates ()
 Validates the contents of the set of states. More...
 

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
explanationis 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::http::HttpMessageParserBase::poll(), isc::config::JSONFeed::poll(), isc::config::JSONFeed::postBuffer(), 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
valueis the numeric value of the event
labelis the text label of the event used in log messages and exceptions.
Exceptions
StateModelErrorif 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::SimpleAddTransaction::defineEvents(), isc::d2::NameAddTransaction::defineEvents(), isc::ha::HAService::defineEvents(), isc::http::HttpMessageParserBase::defineEvents(), isc::d2::NameChangeTransaction::defineEvents(), defineEvents(), and isc::config::JSONFeed::postBuffer().

+ 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::NameChangeTransaction, isc::http::HttpMessageParserBase, isc::ha::HAService, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, and isc::d2::SimpleRemoveTransaction.

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(), 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
valueis the numeric value of the state
labelis the text label of the state used in log messages and exceptions.
handleris the bound instance method which implements the state's actions.
state_pausingpausing mode selected for the given state. The default value is STATE_PAUSE_NEVER.
Exceptions
StateModelErrorif 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::SimpleRemoveTransaction::defineStates(), isc::d2::SimpleAddTransaction::defineStates(), isc::d2::NameRemoveTransaction::defineStates(), isc::d2::NameAddTransaction::defineStates(), isc::ha::HAService::defineStates(), isc::http::HttpMessageParserBase::defineStates(), defineStates(), isc::http::HttpResponseParser::initModel(), isc::http::HttpRequestParser::initModel(), and isc::config::JSONFeed::postBuffer().

+ 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::NameChangeTransaction, isc::http::HttpMessageParserBase, isc::ha::HAService, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, and isc::d2::SimpleRemoveTransaction.

Definition at line 245 of file state_model.cc.

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

Referenced by isc::d2::NameChangeTransaction::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.

Referenced by isc::d2::NameAddTransaction::addingFwdAddrsHandler(), isc::ha::HAService::backupStateHandler(), isc::ha::HAService::communicationRecoveryHandler(), isc::ha::HAService::inMaintenanceStateHandler(), isc::ha::HAService::normalStateHandler(), isc::ha::HAService::partnerDownStateHandler(), isc::ha::HAService::partnerInMaintenanceStateHandler(), isc::ha::HAService::passiveBackupStateHandler(), isc::ha::HAService::readyStateHandler(), isc::d2::NameRemoveTransaction::removingFwdAddrsHandler(), isc::d2::SimpleRemoveTransaction::removingFwdRRsHandler(), isc::d2::NameRemoveTransaction::removingFwdRRsHandler(), isc::d2::SimpleRemoveTransaction::removingRevPtrsHandler(), isc::d2::NameRemoveTransaction::removingRevPtrsHandler(), isc::d2::SimpleAddTransaction::replacingFwdAddrsHandler(), isc::d2::NameAddTransaction::replacingFwdAddrsHandler(), isc::d2::SimpleAddTransaction::replacingRevPtrsHandler(), isc::d2::NameAddTransaction::replacingRevPtrsHandler(), isc::ha::HAService::syncingStateHandler(), isc::ha::HAService::terminatedStateHandler(), and isc::ha::HAService::waitingStateHandler().

◆ 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.

Referenced by isc::ha::HAService::communicationRecoveryHandler(), and isc::ha::HAService::normalStateHandler().

◆ 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().

Referenced by isc::d2::SimpleAddTransaction::processAddFailedHandler(), isc::d2::NameAddTransaction::processAddFailedHandler(), isc::d2::SimpleAddTransaction::processAddOkHandler(), isc::d2::NameAddTransaction::processAddOkHandler(), isc::d2::SimpleRemoveTransaction::processRemoveFailedHandler(), isc::d2::NameRemoveTransaction::processRemoveFailedHandler(), isc::d2::SimpleRemoveTransaction::processRemoveOkHandler(), and isc::d2::NameRemoveTransaction::processRemoveOkHandler().

+ 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.

Referenced by abortModel(), isc::d2::NameAddTransaction::addingFwdAddrsHandler(), isc::http::HttpMessageParserBase::parseFailure(), isc::d2::SimpleAddTransaction::processAddFailedHandler(), isc::d2::NameAddTransaction::processAddFailedHandler(), isc::d2::SimpleAddTransaction::processAddOkHandler(), isc::d2::NameAddTransaction::processAddOkHandler(), isc::d2::SimpleRemoveTransaction::processRemoveFailedHandler(), isc::d2::NameRemoveTransaction::processRemoveFailedHandler(), isc::d2::SimpleRemoveTransaction::processRemoveOkHandler(), isc::d2::NameRemoveTransaction::processRemoveOkHandler(), isc::d2::SimpleRemoveTransaction::readyHandler(), isc::d2::SimpleAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::readyHandler(), isc::d2::NameAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::removingFwdAddrsHandler(), isc::d2::SimpleRemoveTransaction::removingFwdRRsHandler(), isc::d2::NameRemoveTransaction::removingFwdRRsHandler(), isc::d2::SimpleRemoveTransaction::removingRevPtrsHandler(), isc::d2::NameRemoveTransaction::removingRevPtrsHandler(), isc::d2::SimpleAddTransaction::replacingFwdAddrsHandler(), isc::d2::NameAddTransaction::replacingFwdAddrsHandler(), isc::d2::SimpleAddTransaction::replacingRevPtrsHandler(), isc::d2::NameAddTransaction::replacingRevPtrsHandler(), isc::d2::SimpleRemoveTransaction::selectingFwdServerHandler(), isc::d2::SimpleAddTransaction::selectingFwdServerHandler(), isc::d2::NameRemoveTransaction::selectingFwdServerHandler(), isc::d2::NameAddTransaction::selectingFwdServerHandler(), isc::d2::SimpleRemoveTransaction::selectingRevServerHandler(), isc::d2::SimpleAddTransaction::selectingRevServerHandler(), isc::d2::NameRemoveTransaction::selectingRevServerHandler(), and isc::d2::NameAddTransaction::selectingRevServerHandler().

◆ getCurrState()

◆ 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
valueis the numeric value of the event desired.
Returns
returns a constant pointer reference to the event if found
Exceptions
StateModelErrorif 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::config::JSONFeed::postBuffer(), isc::d2::SimpleAddTransaction::verifyEvents(), isc::d2::NameAddTransaction::verifyEvents(), isc::ha::HAService::verifyEvents(), isc::http::HttpMessageParserBase::verifyEvents(), isc::d2::NameChangeTransaction::verifyEvents(), and 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
eventis 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.

References isc::util::LabeledValueSet::getLabel().

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

+ Here is the call graph for this function:

◆ 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(), isc::ha::HAService::isMaintenanceCanceled(), and isc::ha::HAService::partnerDownStateHandler().

◆ 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.

Referenced by isc::d2::NameAddTransaction::addingFwdAddrsHandler(), isc::config::JSONFeed::feedOk(), isc::http::HttpMessageParserBase::getNextFromBuffer(), isc::http::HttpMessageParserBase::httpParseOk(), isc::http::HttpResponseParser::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpMessageParserBase::needData(), isc::config::JSONFeed::needData(), isc::http::HttpMessageParserBase::parseEndedHandler(), isc::http::HttpMessageParserBase::poll(), isc::config::JSONFeed::poll(), isc::http::HttpMessageParserBase::postBuffer(), isc::config::JSONFeed::postBuffer(), isc::d2::SimpleAddTransaction::processAddFailedHandler(), isc::d2::NameAddTransaction::processAddFailedHandler(), isc::d2::SimpleAddTransaction::processAddOkHandler(), isc::d2::NameAddTransaction::processAddOkHandler(), isc::d2::SimpleRemoveTransaction::processRemoveFailedHandler(), isc::d2::NameRemoveTransaction::processRemoveFailedHandler(), isc::d2::SimpleRemoveTransaction::processRemoveOkHandler(), isc::d2::NameRemoveTransaction::processRemoveOkHandler(), isc::d2::SimpleRemoveTransaction::readyHandler(), isc::d2::SimpleAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::readyHandler(), isc::d2::NameAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::removingFwdAddrsHandler(), isc::d2::SimpleRemoveTransaction::removingFwdRRsHandler(), isc::d2::NameRemoveTransaction::removingFwdRRsHandler(), isc::d2::SimpleRemoveTransaction::removingRevPtrsHandler(), isc::d2::NameRemoveTransaction::removingRevPtrsHandler(), isc::d2::SimpleAddTransaction::replacingFwdAddrsHandler(), isc::d2::NameAddTransaction::replacingFwdAddrsHandler(), isc::d2::SimpleAddTransaction::replacingRevPtrsHandler(), isc::d2::NameAddTransaction::replacingRevPtrsHandler(), runModel(), isc::d2::SimpleRemoveTransaction::selectingFwdServerHandler(), isc::d2::SimpleAddTransaction::selectingFwdServerHandler(), isc::d2::NameRemoveTransaction::selectingFwdServerHandler(), isc::d2::NameAddTransaction::selectingFwdServerHandler(), isc::d2::SimpleRemoveTransaction::selectingRevServerHandler(), isc::d2::SimpleAddTransaction::selectingRevServerHandler(), isc::d2::NameRemoveTransaction::selectingRevServerHandler(), isc::d2::NameAddTransaction::selectingRevServerHandler(), isc::http::HttpMessageParserBase::stateWithMultiReadHandler(), isc::http::HttpMessageParserBase::stateWithReadHandler(), isc::d2::NameChangeTransaction::transactionOutcomeString(), and isc::ha::HAService::verboseTransition().

◆ 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.

Referenced by isc::ha::HAService::processMaintenanceCancel(), and isc::ha::HAService::processMaintenanceNotify().

◆ getState()

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

Fetches the state referred to by value.

Parameters
valueis the numeric value of the state desired.
Returns
returns a constant pointer to the state if found
Exceptions
StateModelErrorif the state is not defined.

Definition at line 213 of file state_model.cc.

References getStateInternal().

Referenced by isc::http::HttpMessageParserBase::poll(), isc::config::JSONFeed::poll(), isc::ha::HAService::processHeartbeat(), 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
valueis the numeric value of the state desired.
Returns
returns a constant pointer to the state if found
Exceptions
StateModelErrorif 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().

Referenced by getState(), setState(), isc::d2::SimpleRemoveTransaction::verifyStates(), isc::d2::SimpleAddTransaction::verifyStates(), isc::d2::NameRemoveTransaction::verifyStates(), isc::d2::NameAddTransaction::verifyStates(), isc::d2::NameChangeTransaction::verifyStates(), and verifyStates().

+ 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
stateis 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.

References isc::util::LabeledValueSet::getLabel().

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

+ Here is the call graph for this function:

◆ 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
StateModelErroror 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::http::HttpResponseParser::initModel(), isc::http::HttpRequestParser::initModel(), isc::config::JSONFeed::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::http::HttpMessageParserBase::poll(), isc::config::JSONFeed::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.

References NEW_ST.

◆ isModelPaused()

◆ 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
explanationtext 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
eventthe numeric event value to post as the next event.
Exceptions
StateModelErrorif the event is undefined

Definition at line 320 of file state_model.cc.

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

Referenced by isc::ha::HAService::asyncSendHeartbeat(), isc::ha::HAService::backupStateHandler(), isc::ha::HAService::communicationRecoveryHandler(), isc::http::HttpMessageParserBase::getNextFromBuffer(), isc::http::HttpResponseParser::initModel(), isc::http::HttpRequestParser::initModel(), isc::config::JSONFeed::initModel(), isc::ha::HAService::inMaintenanceStateHandler(), isc::ha::HAService::normalStateHandler(), isc::ha::HAService::partnerDownStateHandler(), isc::ha::HAService::partnerInMaintenanceStateHandler(), isc::ha::HAService::passiveBackupStateHandler(), isc::config::JSONFeed::postBuffer(), isc::ha::HAService::processMaintenanceCancel(), isc::ha::HAService::processMaintenanceNotify(), isc::ha::HAService::processMaintenanceStart(), isc::ha::HAService::readyStateHandler(), runModel(), isc::d2::NameChangeTransaction::sendUpdate(), isc::ha::HAService::synchronize(), isc::ha::HAService::syncingStateHandler(), isc::ha::HAService::terminatedStateHandler(), and isc::ha::HAService::waitingStateHandler().

+ Here is the call graph for this function:

◆ 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
eventis 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::asyncSendHeartbeat(), isc::ha::HAService::asyncSendLeaseUpdate(), isc::d2::NameChangeTransaction::operator()(), isc::ha::HAService::processHAReset(), isc::ha::HAService::processMaintenanceCancel(), isc::ha::HAService::processMaintenanceNotify(), isc::ha::HAService::processMaintenanceStart(), 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
statethe new value to assign to the current state.
Exceptions
StateModelErrorif the state is invalid.

Definition at line 291 of file state_model.cc.

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

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

+ Here is the call graph for this function:

◆ 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_stateis the state in which to begin execution.
Exceptions
StateModelErroror 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
statethe new value to assign to the current state.
eventthe new value to assign to the next event.
Exceptions
StateModelErrorif the state is invalid.

Definition at line 264 of file state_model.cc.

Referenced by abortModel(), isc::d2::NameAddTransaction::addingFwdAddrsHandler(), endModel(), isc::http::HttpResponseParser::initModel(), isc::http::HttpRequestParser::initModel(), isc::http::HttpMessageParserBase::parseEndedHandler(), isc::http::HttpMessageParserBase::parseFailure(), isc::http::HttpMessageParserBase::postBuffer(), isc::config::JSONFeed::postBuffer(), isc::d2::SimpleRemoveTransaction::readyHandler(), isc::d2::SimpleAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::readyHandler(), isc::d2::NameAddTransaction::readyHandler(), isc::d2::NameRemoveTransaction::removingFwdAddrsHandler(), isc::d2::SimpleRemoveTransaction::removingFwdRRsHandler(), isc::d2::NameRemoveTransaction::removingFwdRRsHandler(), isc::d2::SimpleRemoveTransaction::removingRevPtrsHandler(), isc::d2::NameRemoveTransaction::removingRevPtrsHandler(), isc::d2::SimpleAddTransaction::replacingFwdAddrsHandler(), isc::d2::NameAddTransaction::replacingFwdAddrsHandler(), isc::d2::SimpleAddTransaction::replacingRevPtrsHandler(), isc::d2::NameAddTransaction::replacingRevPtrsHandler(), isc::d2::NameChangeTransaction::retryTransition(), isc::d2::SimpleRemoveTransaction::selectingFwdServerHandler(), isc::d2::SimpleAddTransaction::selectingFwdServerHandler(), isc::d2::NameRemoveTransaction::selectingFwdServerHandler(), isc::d2::NameAddTransaction::selectingFwdServerHandler(), isc::d2::SimpleRemoveTransaction::selectingRevServerHandler(), isc::d2::SimpleAddTransaction::selectingRevServerHandler(), isc::d2::NameRemoveTransaction::selectingRevServerHandler(), isc::d2::NameAddTransaction::selectingRevServerHandler(), isc::d2::NameChangeTransaction::sendUpdate(), and isc::ha::HAService::verboseTransition().

◆ 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::NameChangeTransaction, isc::http::HttpMessageParserBase, isc::ha::HAService, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, and isc::d2::SimpleRemoveTransaction.

Definition at line 237 of file state_model.cc.

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

Referenced by initDictionaries(), and isc::d2::NameChangeTransaction::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::NameChangeTransaction, isc::d2::NameAddTransaction, isc::d2::NameRemoveTransaction, isc::d2::SimpleAddTransaction, and isc::d2::SimpleRemoveTransaction.

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

◆ END_ST

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

◆ 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(), isc::util::StateSet::getState(), postNextEvent(), 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(), isc::util::StateSet::getState(), isModelNew(), isModelRunning(), isModelWaiting(), and verifyStates().

◆ NOP_EVT

◆ 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.

Referenced by isc::util::StateSet::getState().

◆ 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.

Referenced by isc::util::StateSet::getState().

◆ START_EVT


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