Kea: state_model.h Source File

| Kea 3.2.0-git

state_model.h
Go to the documentation of this file.
1// Copyright (C) 2013-2026 Internet Systems Consortium, Inc. ("ISC")
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7#ifndef STATE_MODEL_H
8#define STATE_MODEL_H
9
11
12#include <exceptions/exceptions.h>
13#include <util/labeled_value.h>
14#include <boost/shared_ptr.hpp>
15#include <functional>
16#include <map>
17#include <mutex>
18#include <string>
19
20namespace isc {
21namespace util {
22
24 class StateModelError : public isc::Exception {
25public:
26 StateModelError(const char* file, size_t line, const char* what) :
27 isc::Exception(file, line, what) { }
28};
29
31 typedef LabeledValue Event;
32
34 typedef LabeledValuePtr EventPtr;
35
37 typedef std::function<void()> StateHandler;
38
45 enum StatePausing {
46 STATE_PAUSE_ALWAYS,
47 STATE_PAUSE_NEVER,
48 STATE_PAUSE_ONCE
49};
50
61 class State : public LabeledValue {
62public:
80 State(const int value, const std::string& label, StateHandler handler,
81 const StatePausing& state_pausing = STATE_PAUSE_NEVER);
82
84 virtual ~State();
85
87 void run();
88
96 bool shouldPause();
97
98private:
100 StateHandler handler_;
101
103 StatePausing pausing_;
104
107 bool was_paused_;
108};
109
111 typedef boost::shared_ptr<State> StatePtr;
112
118 class StateSet : public LabeledValueSet {
119public:
121 StateSet();
122
124 virtual ~StateSet();
125
135 void add(const int value, const std::string& label, StateHandler handler,
136 const StatePausing& state_pausing);
137
146 const StatePtr getState(int value);
147};
148
226
274 class StateModel {
275public:
276
278
279 static const int NEW_ST = 0;
280
282 static const int END_ST = 1;
283
285 static const int SM_DERIVED_STATE_MIN = 11;
287
289
292 static const int NOP_EVT = 0;
293
295 static const int START_EVT = 1;
296
298 static const int END_EVT = 2;
299
301 static const int FAIL_EVT = 3;
302
304 static const int SM_DERIVED_EVENT_MIN = 11;
306
308 StateModel();
309
311 virtual ~StateModel();
312
324 void startModel(const int start_state);
325
348 virtual void runModel(int event);
349
357 void endModel();
358
360 void unpauseModel();
361
367 void nopStateHandler();
368
369protected:
370
379 void initDictionaries();
380
405 virtual void defineEvents();
406
417 void defineEvent(int value, const std::string& label);
418
428 const EventPtr& getEvent(int value);
429
456 virtual void verifyEvents();
457
482 virtual void defineStates();
483
498 void defineState(int value, const std::string& label,
499 StateHandler handler,
500 const StatePausing& state_pausing = STATE_PAUSE_NEVER);
501
509 const StatePtr getState(int value);
510
536 virtual void verifyStates();
537
548 virtual void onModelFailure(const std::string& explanation);
549
561 void transition(int state, int event);
562
572 void abortModel(const std::string& explanation);
573
585 void setState(int state);
586
596 void postNextEvent(int event);
597
607 bool doOnEntry();
608
618 bool doOnExit();
619
620public:
621
629 int getCurrState() const;
630
634 int getPrevState() const;
635
639 int getLastEvent() const;
640
648 int getNextEvent() const;
649
653 bool isModelNew() const;
654
659 bool isModelRunning() const;
660
665 bool isModelWaiting() const;
666
670 bool isModelDone() const;
671
675 bool isModelPaused() const;
676
681 bool didModelFail() const;
682
689 std::string getEventLabel(const int event) const;
690
697 std::string getStateLabel(const int state) const;
698
707 std::string getContextStr() const;
708
717 std::string getPrevContextStr() const;
718
719protected:
720
730 const StatePtr getStateInternal(int value);
731
732private:
733
746 void setStateInternal(int state);
747
758 void postNextEventInternal(int event);
759
765 bool isModelNewInternal() const;
766
775 std::string getEventLabelInternal(const int event) const;
776
785 std::string getStateLabelInternal(const int state) const;
786
797 std::string getContextStrInternal() const;
798
809 std::string getPrevContextStrInternal() const;
810
812 LabeledValueSet events_;
813
815 StateSet states_;
816
818 bool dictionaries_initted_;
819
821 int curr_state_;
822
824 int prev_state_;
825
827 int last_event_;
828
830 int next_event_;
831
833 bool on_entry_flag_;
834
836 bool on_exit_flag_;
837
839 bool paused_;
840
842 boost::shared_ptr<std::mutex> mutex_;
843};
844
846 typedef boost::shared_ptr<StateModel> StateModelPtr;
847
848} // namespace isc::util
849} // namespace isc
850#endif
isc::Exception
This is a base class for exceptions thrown from the DNS library module.
Definition exceptions/exceptions.h:23
isc::Exception::Exception
Exception(const char *file, size_t line, const char *what)
Constructor for a given type for exceptions with file name and file line number.
Definition exceptions/exceptions.cc:17
isc::Exception::what
virtual const char * what() const
Returns a C-style character string of the cause of the exception.
Definition exceptions/exceptions.cc:32
isc::util::LabeledValueSet
Implements a set of unique LabeledValues.
Definition labeled_value.h:114
isc::util::LabeledValueSet::LabeledValueSet
LabeledValueSet()
Constructor.
Definition labeled_value.cc:60
isc::util::LabeledValue
Implements the concept of a constant value with a text label.
Definition labeled_value.h:39
isc::util::LabeledValue::LabeledValue
LabeledValue(const int value, const std::string &label)
Constructor.
Definition labeled_value.cc:16
isc::util::StateModelError::StateModelError
StateModelError(const char *file, size_t line, const char *what)
Definition state_model.h:26
isc::util::StateModel::isModelWaiting
bool isModelWaiting() const
Returns whether or not the model is waiting.
Definition state_model.cc:396
isc::util::StateModel::initDictionaries
void initDictionaries()
Initializes the event and state dictionaries.
Definition state_model.cc:144
isc::util::StateModel::endModel
void endModel()
Conducts a normal transition to the end of the model.
Definition state_model.cc:271
isc::util::StateModel::SM_DERIVED_STATE_MIN
static const int SM_DERIVED_STATE_MIN
Value at which custom states in a derived class should begin.
Definition state_model.h:285
isc::util::StateModel::getStateLabel
std::string getStateLabel(const int state) const
Fetches the label associated with an state value.
Definition state_model.cc:421
isc::util::StateModel::getStateInternal
const StatePtr getStateInternal(int value)
Fetches the state referred to by value.
Definition state_model.cc:219
isc::util::StateModel::unpauseModel
void unpauseModel()
Unpauses state model.
Definition state_model.cc:276
isc::util::StateModel::FAIL_EVT
static const int FAIL_EVT
Event issued to abort the model execution.
Definition state_model.h:301
isc::util::StateModel::isModelDone
bool isModelDone() const
Returns whether or not the model has finished execution.
Definition state_model.cc:403
isc::util::StateModel::getLastEvent
int getLastEvent() const
Fetches the model's last event.
Definition state_model.cc:367
isc::util::StateModel::isModelPaused
bool isModelPaused() const
Returns whether or not the model is paused.
Definition state_model.cc:415
isc::util::StateModel::defineEvents
virtual void defineEvents()
Populates the set of events.
Definition state_model.cc:229
isc::util::StateModel::verifyStates
virtual void verifyStates()
Validates the contents of the set of states.
Definition state_model.cc:253
isc::util::StateModel::isModelRunning
bool isModelRunning() const
Returns whether or not the model is running.
Definition state_model.cc:390
isc::util::StateModel::doOnExit
bool doOnExit()
Checks if on exit flag is true.
Definition state_model.cc:347
isc::util::StateModel::StateModel
StateModel()
Constructor.
Definition state_model.cc:89
isc::util::StateModel::NEW_ST
static const int NEW_ST
State that a state model is in immediately after construction.
Definition state_model.h:279
isc::util::StateModel::nopStateHandler
void nopStateHandler()
An empty state handler.
Definition state_model.cc:140
isc::util::StateModel::onModelFailure
virtual void onModelFailure(const std::string &explanation)
Handler for fatal model execution errors.
Definition state_model.cc:259
isc::util::StateModel::defineEvent
void defineEvent(int value, const std::string &label)
Adds an event value and associated label to the set of events.
Definition state_model.cc:170
isc::util::StateModel::verifyEvents
virtual void verifyEvents()
Validates the contents of the set of events.
Definition state_model.cc:237
isc::util::StateModel::END_EVT
static const int END_EVT
Event issued to end the model execution.
Definition state_model.h:298
isc::util::StateModel::doOnEntry
bool doOnEntry()
Checks if on entry flag is true.
Definition state_model.cc:339
isc::util::StateModel::NOP_EVT
static const int NOP_EVT
Signifies that no event has occurred.
Definition state_model.h:292
isc::util::StateModel::START_EVT
static const int START_EVT
Event issued to start the model execution.
Definition state_model.h:295
isc::util::StateModel::abortModel
void abortModel(const std::string &explanation)
Aborts model execution.
Definition state_model.cc:282
isc::util::StateModel::getCurrState
int getCurrState() const
Fetches the model's current state.
Definition state_model.cc:355
isc::util::StateModel::getEventLabel
std::string getEventLabel(const int event) const
Fetches the label associated with an event value.
Definition state_model.cc:432
isc::util::StateModel::isModelNew
bool isModelNew() const
Returns whether or not the model is new.
Definition state_model.cc:379
isc::util::StateModel::setState
void setState(int state)
Sets the current state to the given state value.
Definition state_model.cc:291
isc::util::StateModel::defineState
void defineState(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.
Definition state_model.cc:196
isc::util::StateModel::startModel
void startModel(const int start_state)
Begins execution of the model.
Definition state_model.cc:100
isc::util::StateModel::getEvent
const EventPtr & getEvent(int value)
Fetches the event referred to by value.
Definition state_model.cc:186
isc::util::StateModel::defineStates
virtual void defineStates()
Populates the set of states.
Definition state_model.cc:245
isc::util::StateModel::getPrevContextStr
std::string getPrevContextStr() const
Convenience method which returns a string rendition of the previous state and last event.
Definition state_model.cc:454
isc::util::StateModel::~StateModel
virtual ~StateModel()
Destructor.
Definition state_model.cc:96
isc::util::StateModel::runModel
virtual void runModel(int event)
Processes events through the state model.
Definition state_model.cc:112
isc::util::StateModel::transition
void transition(int state, int event)
Sets up the model to transition into given state with a given event.
Definition state_model.cc:264
isc::util::StateModel::getNextEvent
int getNextEvent() const
Fetches the model's next event.
Definition state_model.cc:373
isc::util::StateModel::getPrevState
int getPrevState() const
Fetches the model's previous state.
Definition state_model.cc:361
isc::util::StateModel::getContextStr
std::string getContextStr() const
Convenience method which returns a string rendition of the current state and next event.
Definition state_model.cc:443
isc::util::StateModel::SM_DERIVED_EVENT_MIN
static const int SM_DERIVED_EVENT_MIN
Value at which custom events in a derived class should begin.
Definition state_model.h:304
isc::util::StateModel::getState
const StatePtr getState(int value)
Fetches the state referred to by value.
Definition state_model.cc:213
isc::util::StateModel::END_ST
static const int END_ST
Final state, all the state model has reached its conclusion.
Definition state_model.h:282
isc::util::StateModel::postNextEvent
void postNextEvent(int event)
Sets the next event to the given event value.
Definition state_model.cc:320
isc::util::StateModel::didModelFail
bool didModelFail() const
Returns whether or not the model failed.
Definition state_model.cc:409
isc::util::StateSet
Implements a unique set or dictionary of states.
Definition state_model.h:118
isc::util::StateSet::getState
const StatePtr getState(int value)
Fetches a state for the given value.
Definition state_model.cc:61
isc::util::StateSet::StateSet
StateSet()
Constructor.
Definition state_model.cc:42
isc::util::StateSet::add
void add(const int value, const std::string &label, StateHandler handler, const StatePausing &state_pausing)
Adds a state definition to the set of states.
Definition state_model.cc:49
isc::util::StateSet::~StateSet
virtual ~StateSet()
Destructor.
Definition state_model.cc:45
isc::util::State::~State
virtual ~State()
Destructor.
Definition state_model.cc:22
isc::util::State::run
void run()
Invokes the State's handler.
Definition state_model.cc:26
isc::util::State::shouldPause
bool shouldPause()
Indicates if the state model should pause upon entering this state.
Definition state_model.cc:31
isc::util::State::State
State(const int value, const std::string &label, StateHandler handler, const StatePausing &state_pausing=STATE_PAUSE_NEVER)
Constructor.
Definition state_model.cc:16
exceptions.h
labeled_value.h
This file defines classes: LabeledValue and LabeledValueSet.
isc::util::file
Definition filesystem.cc:29
isc::util
Definition time_utils.cc:43
isc::util::Event
LabeledValue Event
Define an Event.
Definition state_model.h:31
isc::util::StateHandler
std::function< void()> StateHandler
Defines a pointer to an instance method for handling a state.
Definition state_model.h:37
isc::util::StateModelPtr
boost::shared_ptr< StateModel > StateModelPtr
Defines a pointer to a StateModel.
Definition state_model.h:846
isc::util::StatePausing
StatePausing
State machine pausing modes.
Definition state_model.h:45
isc::util::STATE_PAUSE_ALWAYS
@ STATE_PAUSE_ALWAYS
Definition state_model.h:46
isc::util::STATE_PAUSE_ONCE
@ STATE_PAUSE_ONCE
Definition state_model.h:48
isc::util::STATE_PAUSE_NEVER
@ STATE_PAUSE_NEVER
Definition state_model.h:47
isc::util::StatePtr
boost::shared_ptr< State > StatePtr
Defines a shared pointer to a State.
Definition state_model.h:111
isc::util::EventPtr
LabeledValuePtr EventPtr
Define Event pointer.
Definition state_model.h:34
isc::util::LabeledValuePtr
boost::shared_ptr< LabeledValue > LabeledValuePtr
Defines a shared pointer to a LabeledValue instance.
Definition labeled_value.h:92
isc
Defines the logger used by the top-level component of kea-lfc.
Definition check_exists_add.cc:18