Kea 2.5.9
state_model.h
Go to the documentation of this file.
1// Copyright (C) 2013-2021 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
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
25public:
26 StateModelError(const char* file, size_t line, const char* what) :
27 isc::Exception(file, line, what) { };
28};
29
32
35
37typedef std::function<void()> StateHandler;
38
49};
50
61class 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
111typedef boost::shared_ptr<State> StatePtr;
112
118class 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
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(unsigned 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(unsigned int value, const std::string& label);
418
428 const EventPtr& getEvent(unsigned int value);
429
456 virtual void verifyEvents();
457
482 virtual void defineStates();
483
498 void defineState(unsigned int value, const std::string& label,
499 StateHandler handler,
500 const StatePausing& state_pausing = STATE_PAUSE_NEVER);
501
509 const StatePtr getState(unsigned int value);
510
536 virtual void verifyStates();
537
548 virtual void onModelFailure(const std::string& explanation);
549
561 void transition(unsigned int state, unsigned int event);
562
572 void abortModel(const std::string& explanation);
573
585 void setState(unsigned int state);
586
596 void postNextEvent(unsigned int event);
597
607 bool doOnEntry();
608
618 bool doOnExit();
619
620public:
621
629 unsigned int getCurrState() const;
630
634 unsigned int getPrevState() const;
635
639 unsigned int getLastEvent() const;
640
648 unsigned 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(unsigned int value);
731
732private:
733
746 void setStateInternal(unsigned int state);
747
758 void postNextEventInternal(unsigned 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 unsigned int curr_state_;
822
824 unsigned int prev_state_;
825
827 unsigned int last_event_;
828
830 unsigned 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
846typedef boost::shared_ptr<StateModel> StateModelPtr;
847
848} // namespace isc::util
849} // namespace isc
850#endif
This is a base class for exceptions thrown from the DNS library module.
virtual const char * what() const
Returns a C-style character string of the cause of the exception.
Implements a set of unique LabeledValues.
Implements the concept of a constant value with a text label.
Definition: labeled_value.h:39
Thrown if the state machine encounters a general error.
Definition: state_model.h:24
StateModelError(const char *file, size_t line, const char *what)
Definition: state_model.h:26
Implements a finite state machine.
Definition: state_model.h:274
const EventPtr & getEvent(unsigned int value)
Fetches the event referred to by value.
Definition: state_model.cc:186
bool isModelWaiting() const
Returns whether or not the model is waiting.
Definition: state_model.cc:396
void initDictionaries()
Initializes the event and state dictionaries.
Definition: state_model.cc:144
void endModel()
Conducts a normal transition to the end of the model.
Definition: state_model.cc:271
static const int SM_DERIVED_STATE_MIN
Value at which custom states in a derived class should begin.
Definition: state_model.h:285
std::string getStateLabel(const int state) const
Fetches the label associated with an state value.
Definition: state_model.cc:421
void unpauseModel()
Unpauses state model.
Definition: state_model.cc:276
static const int FAIL_EVT
Event issued to abort the model execution.
Definition: state_model.h:301
bool isModelDone() const
Returns whether or not the model has finished execution.
Definition: state_model.cc:403
virtual void runModel(unsigned int event)
Processes events through the state model.
Definition: state_model.cc:112
bool isModelPaused() const
Returns whether or not the model is paused.
Definition: state_model.cc:415
virtual void defineEvents()
Populates the set of events.
Definition: state_model.cc:229
void postNextEvent(unsigned int event)
Sets the next event to the given event value.
Definition: state_model.cc:320
virtual void verifyStates()
Validates the contents of the set of states.
Definition: state_model.cc:253
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.
Definition: state_model.cc:196
const StatePtr getState(unsigned int value)
Fetches the state referred to by value.
Definition: state_model.cc:213
bool isModelRunning() const
Returns whether or not the model is running.
Definition: state_model.cc:390
bool doOnExit()
Checks if on exit flag is true.
Definition: state_model.cc:347
StateModel()
Constructor.
Definition: state_model.cc:89
static const int NEW_ST
State that a state model is in immediately after construction.
Definition: state_model.h:279
unsigned int getNextEvent() const
Fetches the model's next event.
Definition: state_model.cc:373
void nopStateHandler()
An empty state handler.
Definition: state_model.cc:140
virtual void onModelFailure(const std::string &explanation)
Handler for fatal model execution errors.
Definition: state_model.cc:259
void defineEvent(unsigned int value, const std::string &label)
Adds an event value and associated label to the set of events.
Definition: state_model.cc:170
void transition(unsigned int state, unsigned int event)
Sets up the model to transition into given state with a given event.
Definition: state_model.cc:264
virtual void verifyEvents()
Validates the contents of the set of events.
Definition: state_model.cc:237
static const int END_EVT
Event issued to end the model execution.
Definition: state_model.h:298
bool doOnEntry()
Checks if on entry flag is true.
Definition: state_model.cc:339
static const int NOP_EVT
Signifies that no event has occurred.
Definition: state_model.h:292
static const int START_EVT
Event issued to start the model execution.
Definition: state_model.h:295
void abortModel(const std::string &explanation)
Aborts model execution.
Definition: state_model.cc:282
std::string getEventLabel(const int event) const
Fetches the label associated with an event value.
Definition: state_model.cc:432
bool isModelNew() const
Returns whether or not the model is new.
Definition: state_model.cc:379
void startModel(const int start_state)
Begins execution of the model.
Definition: state_model.cc:100
virtual void defineStates()
Populates the set of states.
Definition: state_model.cc:245
const StatePtr getStateInternal(unsigned int value)
Fetches the state referred to by value.
Definition: state_model.cc:219
std::string getPrevContextStr() const
Convenience method which returns a string rendition of the previous state and last event.
Definition: state_model.cc:454
virtual ~StateModel()
Destructor.
Definition: state_model.cc:96
void setState(unsigned int state)
Sets the current state to the given state value.
Definition: state_model.cc:291
std::string getContextStr() const
Convenience method which returns a string rendition of the current state and next event.
Definition: state_model.cc:443
static const int SM_DERIVED_EVENT_MIN
Value at which custom events in a derived class should begin.
Definition: state_model.h:304
static const int END_ST
Final state, all the state model has reached its conclusion.
Definition: state_model.h:282
unsigned int getLastEvent() const
Fetches the model's last event.
Definition: state_model.cc:367
unsigned int getPrevState() const
Fetches the model's previous state.
Definition: state_model.cc:361
bool didModelFail() const
Returns whether or not the model failed.
Definition: state_model.cc:409
unsigned int getCurrState() const
Fetches the model's current state.
Definition: state_model.cc:355
Implements a unique set or dictionary of states.
Definition: state_model.h:118
const StatePtr getState(int value)
Fetches a state for the given value.
Definition: state_model.cc:61
StateSet()
Constructor.
Definition: state_model.cc:42
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
virtual ~StateSet()
Destructor.
Definition: state_model.cc:45
Defines a State within the State Model.
Definition: state_model.h:61
virtual ~State()
Destructor.
Definition: state_model.cc:22
void run()
Invokes the State's handler.
Definition: state_model.cc:26
bool shouldPause()
Indicates if the state model should pause upon entering this state.
Definition: state_model.cc:31
This file defines classes: LabeledValue and LabeledValueSet.
LabeledValue Event
Define an Event.
Definition: state_model.h:31
std::function< void()> StateHandler
Defines a pointer to an instance method for handling a state.
Definition: state_model.h:37
boost::shared_ptr< StateModel > StateModelPtr
Defines a pointer to a StateModel.
Definition: state_model.h:846
StatePausing
State machine pausing modes.
Definition: state_model.h:45
@ STATE_PAUSE_ALWAYS
Definition: state_model.h:46
@ STATE_PAUSE_ONCE
Definition: state_model.h:48
@ STATE_PAUSE_NEVER
Definition: state_model.h:47
boost::shared_ptr< State > StatePtr
Defines a shared pointer to a State.
Definition: state_model.h:111
LabeledValuePtr EventPtr
Define Event pointer.
Definition: state_model.h:34
boost::shared_ptr< LabeledValue > LabeledValuePtr
Defines a shared pointer to a LabeledValue instance.
Definition: labeled_value.h:92
Defines the logger used by the top-level component of kea-lfc.