state_model.h

Go to the documentation of this file.

// Copyright (C) 2013-2026 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 <cstdint>
#include <functional>
#include <map>
#include <mutex>
#include <string>
 
#include <boost/shared_ptr.hpp>
 
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 : uint16_t {
    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(int event);

    void endModel();

    void unpauseModel();

    void nopStateHandler();
 
protected:

    void initDictionaries();

    virtual void defineEvents();

    void defineEvent(int value, const std::string& label);

    const EventPtr& getEvent(int value);

    virtual void verifyEvents();

    virtual void defineStates();

    void defineState(int value, const std::string& label,
                     StateHandler handler,
                     const StatePausing& state_pausing = STATE_PAUSE_NEVER);

    const StatePtr getState(int value);

    virtual void verifyStates();

    virtual void onModelFailure(const std::string& explanation);

    void transition(int state, int event);

    void abortModel(const std::string& explanation);

    void setState(int state);

    void postNextEvent(int event);

    bool doOnEntry();

    bool doOnExit();
 
public:

    int getCurrState() const;

    int getPrevState() const;

    int getLastEvent() const;

    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(int value);
 
private:

    void setStateInternal(int state);

    void postNextEventInternal(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_;

    int curr_state_;

    int prev_state_;

    int last_event_;

    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