state_model.h

Go to the documentation of this file.

// Copyright (C) 2013-2021 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