state_model.h

Go to the documentation of this file.

// Copyright (C) 2013-2024 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
#ifndef STATE_MODEL_H
#define STATE_MODEL_H
 
 
#include <exceptions/exceptions.h>
#include <util/labeled_value.h>
#include <boost/shared_ptr.hpp>
#include <functional>
#include <map>
#include <mutex>
#include <string>
 
namespace isc {
namespace util {
 
class StateModelError : public isc::Exception {
public:
    StateModelError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { }
};
 
typedef LabeledValue Event;
 
typedef LabeledValuePtr EventPtr;
 
typedef std::function<void()> StateHandler;
 
enum StatePausing {
    STATE_PAUSE_ALWAYS,
    STATE_PAUSE_NEVER,
    STATE_PAUSE_ONCE
};
 
class State : public LabeledValue {
public:
    State(const int value, const std::string& label, StateHandler handler,
          const StatePausing& state_pausing = STATE_PAUSE_NEVER);
 
    virtual ~State();
 
    void run();
 
    bool shouldPause();
 
private:
    StateHandler handler_;
 
    StatePausing pausing_;
 
    bool was_paused_;
};
 
typedef boost::shared_ptr<State> StatePtr;
 
class StateSet : public LabeledValueSet {
public:
    StateSet();
 
    virtual ~StateSet();
 
    void add(const int value, const std::string& label, StateHandler handler,
             const StatePausing& state_pausing);
 
    const StatePtr getState(int value);
};
 
 
class StateModel {
public:
 
 
    static const int NEW_ST = 0;
 
    static const int END_ST = 1;
 
    static const int SM_DERIVED_STATE_MIN = 11;
 
 
    static const int NOP_EVT = 0;
 
    static const int START_EVT = 1;
 
    static const int END_EVT = 2;
 
    static const int FAIL_EVT = 3;
 
    static const int SM_DERIVED_EVENT_MIN = 11;
 
    StateModel();
 
    virtual ~StateModel();
 
    void startModel(const int start_state);
 
    virtual void runModel(unsigned int event);
 
    void endModel();
 
    void unpauseModel();
 
    void nopStateHandler();
 
protected:
 
    void initDictionaries();
 
    virtual void defineEvents();
 
    void defineEvent(unsigned int value, const std::string& label);
 
    const EventPtr& getEvent(unsigned int value);
 
    virtual void verifyEvents();
 
    virtual void defineStates();
 
    void defineState(unsigned int value, const std::string& label,
                     StateHandler handler,
                     const StatePausing& state_pausing = STATE_PAUSE_NEVER);
 
    const StatePtr getState(unsigned int value);
 
    virtual void verifyStates();
 
    virtual void onModelFailure(const std::string& explanation);
 
    void transition(unsigned int state, unsigned int event);
 
    void abortModel(const std::string& explanation);
 
    void setState(unsigned int state);
 
    void postNextEvent(unsigned int event);
 
    bool doOnEntry();
 
    bool doOnExit();
 
public:
 
    unsigned int getCurrState() const;
 
    unsigned int getPrevState() const;
 
    unsigned int getLastEvent() const;
 
    unsigned int getNextEvent() const;
 
    bool isModelNew() const;
 
    bool isModelRunning() const;
 
    bool isModelWaiting() const;
 
    bool isModelDone() const;
 
    bool isModelPaused() const;
 
    bool didModelFail() const;
 
    std::string getEventLabel(const int event) const;
 
    std::string getStateLabel(const int state) const;
 
    std::string getContextStr() const;
 
    std::string getPrevContextStr() const;
 
protected:
 
    const StatePtr getStateInternal(unsigned int value);
 
private:
 
    void setStateInternal(unsigned int state);
 
    void postNextEventInternal(unsigned int event);
 
    bool isModelNewInternal() const;
 
    std::string getEventLabelInternal(const int event) const;
 
    std::string getStateLabelInternal(const int state) const;
 
    std::string getContextStrInternal() const;
 
    std::string getPrevContextStrInternal() const;
 
    LabeledValueSet events_;
 
    StateSet states_;
 
    bool dictionaries_initted_;
 
    unsigned int curr_state_;
 
    unsigned int prev_state_;
 
    unsigned int last_event_;
 
    unsigned int next_event_;
 
    bool on_entry_flag_;
 
    bool on_exit_flag_;
 
    bool paused_;
 
    boost::shared_ptr<std::mutex> mutex_;
};
 
typedef boost::shared_ptr<StateModel> StateModelPtr;
 
} // namespace isc::util
} // namespace isc
#endif