State.hpp

// <State.hpp> -*- C++ -*-
#pragma once
 
#include "sparta/utils/Enum.hpp"
#include "sparta/kernel/Scheduler.hpp"
#include "sparta/simulation/Audience.hpp"
#include "sparta/events/Scheduleable.hpp"
#include "sparta/simulation/StateTracker.hpp"
#include "sparta/utils/SpartaAssert.hpp"
#include "sparta/utils/SpartaException.hpp"
 
namespace sparta
{
    namespace app{
        class Simulation;
        class SimulationConfiguration;
    }
 
    class BoolEnum {
    public:
 
        enum class BoolValue : unsigned int {
            __FIRST,
            FALSE = __FIRST,
            TRUE,
            __LAST
        };
 
        // Default constructor.
        BoolEnum() = default;
 
        // Constructor to convert any bool instance into an
        // actual BoolEnum instance. This is important because
        // users will pass around bool instances for methods
        // related to sparta::State<bool> instances.
        BoolEnum(const bool val) :
            enum_val_(val ? BoolValue::TRUE : BoolValue::FALSE) {}
 
        // Constructor to convert any BoolValue enum instance
        // into an actual BoolEnum instance. This is important
        // because the State constructor can take any enum constant
        // and convert it into EnumTValueType instance.
        BoolEnum(const BoolValue& val) :
            enum_val_(val) {}
 
        // Copy Constructor.
        BoolEnum(const BoolEnum& other) :
            enum_val_(other.enum_val_) {}
 
        // Move Constructor.
        BoolEnum(BoolEnum&& other) :
            enum_val_(std::move(other.enum_val_)) {}
 
        // Copy Assignment operator.
        BoolEnum& operator=(const BoolEnum& other) {
            enum_val_ = other.enum_val_;
            return *this;
        }
 
        // Move Assignment operator.
        BoolEnum& operator=(BoolEnum&& other) {
            enum_val_ = std::move(other.enum_val_);
            return *this;
        }
 
        // BoolEnum instances should be implicitly converted
        // into integers.
        operator uint32_t() const {
            return static_cast<uint32_t>(enum_val_);
        }
 
        // BoolEnum instances should be implicitly converted
        // into its internal enum instance type.
        operator BoolValue() const {
            return enum_val_;
        }
    private:
 
        // Enum instance which holds the true or false state.
        BoolValue enum_val_;
    };
 
    template<class EnumT, class MetaDataT = void, uint32_t MAX_MARKERS = 15>
    class State
    {
        class MarkerSet;
 
    public:
        typedef MetaDataT * MetaDataTPtr;
 
        typedef typename std::conditional<
            !std::is_same<EnumT, bool>::value,
            typename utils::Enum<EnumT>::Value,
            BoolEnum>::type
        EnumTValueType;
 
        //  BoolEnum::BoolValue because there are signatures
        //  which assert on std::is_enum.
        typedef typename std::conditional<
            !std::is_same<EnumT, bool>::value,
            EnumT, BoolEnum::BoolValue>::type
        EnumType;
 
        class Marker
        {
        private:
            friend MarkerSet;
 
            void reset_() {
                marked_ = false;
            }
 
            // Default constructor only made by MarkerSet
            Marker() = default;
 
            // Initialize this Marker
            void initialize(MarkerSet * marker_set, const EnumTValueType & val) {
                marker_set_ = marker_set;
                val_ = val;
            }
 
        public:
 
            // No copies
            Marker(const Marker &) = default;
 
            void set(MetaDataTPtr ptr = nullptr) {
                if(!marked_) {
                    marker_set_->jointSet_(ptr);
                    marked_ = true;
                }
            }
 
            void clear() {
                if(marked_) {
                    // clear the marker set
                    marker_set_->clearMark_();
                    marked_ = false;
                }
            }
 
            bool isMarked() const {
                return marked_;
            }
 
            const EnumTValueType & getMarkerValue() const {
                return val_;
            }
 
        private:
            MarkerSet * marker_set_ = nullptr;
 
            bool marked_ = false;
 
            EnumTValueType val_;
 
        }; // class Marker
 
        class Monitor
        {
        public:
 
            typedef State::EnumTValueType EnumTValueType;
 
            virtual void signalSet(const EnumTValueType & val, MetaDataTPtr) = 0;
 
            virtual ~Monitor() {}
        }; // class Monitor
 
    private:
 
        class MarkerSet
        {
        public:
 
            MarkerSet() {}
 
            MarkerSet(const MarkerSet&) = default;
 
            Marker * makeMarker(State * state) {
                state_ = state;
                sparta_assert(marker_cnt_ != MAX_MARKERS);
                markers_[marker_cnt_].initialize(this, transition_val_);
                return &markers_[marker_cnt_++];
            }
 
            uint32_t numMarkers() const {
                return marker_cnt_;
            }
 
            uint32_t numMarks() const {
                return marked_count_;
            }
 
            uint32_t numMarked() const {
                uint32_t cnt = 0;
                for(uint32_t i = 0; i < marker_cnt_; ++i) {
                    cnt += markers_[i].isMarked();
                }
                return cnt;
            }
 
            void reset() {
                for(uint32_t i = 0; i < marker_cnt_; ++i) {
                    markers_[i].reset_();
                }
                marked_count_ = 0;
                is_set_ = false;
            }
 
            void observe(const ScheduleableHandle & ev_hand) {
                audience_.enroll(ev_hand);
            }
 
            void withdraw(const ScheduleableHandle & ev_hand) {
                audience_.withdraw(ev_hand);
            }
 
            void release() {
                audience_.release();
            }
 
            void setThreshold(uint32_t thresh) {
                marked_thresh_ = thresh;
            }
 
            void attachMonitor(Monitor * mon) {
                monitors_.emplace_back(mon);
            }
 
            void detachMonitor(Monitor *mon)
            {
                auto i = std::find(monitors_.begin(), monitors_.end(), mon);
                if (i != monitors_.end()) {
                    monitors_.erase(i);
                }
            }
 
            void notifyObservers() {
                audience_.notify();
                is_set_ = true;
            }
 
            bool isSet() const {
                return is_set_;
            }
 
        private:
 
            friend Marker;
 
            friend State;
 
            void jointSet_(MetaDataTPtr ptr = nullptr) {
                ++marked_count_;
                if (SPARTA_EXPECT_FALSE(!monitors_.empty())) {
                    for (auto& i : monitors_) {
                        i->signalSet(transition_val_, ptr);
                    }
                    //} else if ((markers_.size() - marked_count_) <= marked_thresh_) {
                } else if ((marker_cnt_ - marked_count_) <= marked_thresh_) {
                    state_->setValue_(transition_val_);
                    notifyObservers();
                    is_set_ = true;
                }
 
            }
 
            void clearMark_() {
                sparta_assert(marked_count_ != 0);
                --marked_count_;
            }
 
            // MarkerSet privates
            uint32_t                marked_count_  = 0;
            uint32_t                marked_thresh_ = 0;
            //std::list<Marker>       markers_;
            Marker                  markers_[MAX_MARKERS];
            uint32_t                marker_cnt_ = 0;
            State                  *state_ = nullptr;
            EnumTValueType          transition_val_;       //<! The value to transition to
            Audience                audience_;
            bool                    is_set_ = false;
            std::vector<Monitor *>  monitors_;
        }; // class MarkerSet
 
        friend class MarkerSet;
 
        void setValue_(const EnumTValueType & val) {
            current_state_ = val;
        }
 
        //  construction. There are tests which assert that. So, this method
        //  when called, checks if this current instance is a State<bool> or not,
        //  and depending on that, sets the value to FALSE.
        template<typename U = EnumT>
        typename std::enable_if<std::is_same<U, bool>::value, void>::type
        attemptSetValue_() {
            setValue(BoolEnum::BoolValue::FALSE);
        }
 
        //  construction. There are tests which assert that. So, this method
        //  when called, checks if this current instance is a State<bool> or not,
        //  and depending on that, sets the value to FALSE. If the current context
        //  is not tempaltized on bool, then do nothing.
        template<typename U = EnumT>
        typename std::enable_if<!std::is_same<U, bool>::value, void>::type
        attemptSetValue_() {}
 
    public:
        // State Class
 
        State(const EnumTValueType & initial_value = EnumType::__FIRST) :
            initial_value_(initial_value),
            current_state_(initial_value),
 
            // procedure. The sparta::State class asks the StatePoolManager to dispatch
            // a State Tracker Unit, templatized on the same enum type as itself, by
            // calling the dispatchNewTracker() API. Inside the dispatchNewTracker() API,
            // the pool manager looks at all the StatePool template instantiations that it
            // manages, to check if it has one instantiation which is templated on the same
            // type as requested right here. If it has, then we go to the second step of
            // taking that StatePool handle and demand a new StateTrackerUnit out of it.
            // The StatePool instance looks into its internal Tracker Queue to see if it
            // has any available, ready-to-go tracker unit for dispatching. If yes, then
            // it dispatches a std::unique_ptr to a new tracker unit back to the caller's
            // side, which is sparta::State and sparta::State moves that into it's internal
            // member variable. If the internal Tracker Queue does not have any tracker
            // unit to go, the StatePool creates one from heap right then and dispatches
            // it. If the Pool Manager does not have a StatePool instantiation of the
            // requested enum type (which happens only on the first call for an enum type),
            // the pool manager creates a new StatePool template instantiation and pushes it
            // in its internal map, along with a unique ID, which separates all the different
            // StatePool instantiations form each other.
            state_tracker_unit_(std::move(
                                    tracker::StatePoolManager::getInstance().
                                    dispatchNewTracker<EnumType>()))
        {
 
            // If tracking is disabled, this internal
            // tracker unit will be nullptr. In that case,
            // we do not track anything.
            if(state_tracker_unit_) {
                state_tracker_unit_->startState(initial_value_);
            }
 
            for(uint32_t i = 0; i < EnumTValueType(EnumType::__LAST); ++i) {
                marker_set_[i].transition_val_ = static_cast<EnumType>(i);
            }
            static_assert(std::is_enum<EnumType>::value,
                          "ERROR: State classes must be templatized on a valid enum or enum class type");
            attemptSetValue_();
        }
 
        State(const State &other) :
            initial_value_{other.initial_value_},
            current_state_{other.current_state_},
            marker_set_{other.marker_set_},
            state_tracker_unit_{other.state_tracker_unit_ ? new auto {*other.state_tracker_unit_} : nullptr}
        {}
 
 
        State & operator = (const State &) = delete;
 
        virtual ~State() {}
 
        const EnumTValueType & getValue() const {
            return current_state_;
        }
 
        const EnumType & getEnumValue() const {
            return (current_state_.getValue()).getEnum();
        }
 
        Scheduler::Tick getTimeInState() const {
            sparta_assert(state_tracker_unit_ != nullptr,
                          "This method can only be called on this State class with tracking enabled");
            return state_tracker_unit_->getActiveTime();
        }
 
        void setValue(const EnumTValueType & val) {
 
            // tracker unit will be nullptr. In that case,
            // we do not track anything.
            if(state_tracker_unit_) {
                state_tracker_unit_->startState(val);
            }
            setValue_(val);
 
            // Notify audience members of state change.  The observers
            // are registered with the Audience in the marker set for
            // that value type
            marker_set_[val].notifyObservers();
        }
 
        void reset() {
            current_state_ = static_cast<EnumTValueType>(initial_value_);
            for(auto & ms : marker_set_) {
                ms.reset();
            }
            attemptSetValue_();
        }
 
        void reset(const EnumTValueType & val) {
            current_state_ = val;
            for(auto & ms : marker_set_) {
                ms.reset();
            }
        }
 
        // \defgroup Assignment/comparison
 
        void operator=(const EnumTValueType& val) {
            setValue(val);
        }
 
        bool operator==(const EnumTValueType& rhs_val) const {
            return (getValue() == rhs_val);
        }
 
        bool operator!=(const EnumTValueType& rhs_val) const {
            return (getValue() != rhs_val);
        }
 
 
        // \defgroup Marker methods
 
        Marker* newMarker(const EnumTValueType & val) {
            return marker_set_[val].makeMarker(this);
        }
 
        uint32_t numMarks(const EnumTValueType & val) const {
            return marker_set_[val].numMarks();
        }
 
        uint32_t numMarkers(const EnumTValueType & val) const {
            return marker_set_[val].numMarkers();
        }
 
        bool complete(const EnumTValueType & val) const {
            return (numMarks(val) == numMarkers(val));
        }
 
        void setMarkedThreshold(const EnumTValueType & val, uint32_t thresh) {
            marker_set_[val].setThreshold(thresh);
        }
 
 
        // \defgroup Condition methods, API
 
        bool isSet(const EnumTValueType & val = BoolEnum::BoolValue::TRUE) const
        {
            return (marker_set_[val].isSet() == true);
        }
 
        bool isClear(const EnumTValueType & val = BoolEnum::BoolValue::TRUE) const
        {
            return (marker_set_[val].isSet() == false);
        }
 
 
        // \defgroup Observation methods
 
        void observe(const EnumTValueType & val,
                     const ScheduleableHandle & ev_hand)
        {
            marker_set_[val].observe(ev_hand);
        }
 
        void withdraw(const EnumTValueType & val,
                      const ScheduleableHandle & ev_hand)
        {
            marker_set_[val].withdraw(ev_hand);
        }
 
        void release(const EnumTValueType & val)
        {
            marker_set_[val].release();
        }
 
 
        // \defgroup Monitor methods
 
        void attachMonitor(const EnumTValueType & val, Monitor * mon) {
            marker_set_[val].attachMonitor(mon);
        }
 
        void detachMonitor(const EnumTValueType & val, Monitor *mon)
        {
            marker_set_[val].detachMonitor(mon);
        }
 
 
#ifndef DO_NOT_DOCUMENT
        // Debug API for testing only.
        // This only tests the stats accumulated by a
        // single sparta::State instance.
        const std::vector<Scheduler::Tick> & getRawAccumulatedTime() const {
            sparta_assert(state_tracker_unit_ != nullptr);
            return state_tracker_unit_->getStateSet().state_delta_set;
        }
#endif
 
    private:
        // State Privates
        const EnumType initial_value_;
        utils::ValidValue<EnumTValueType> current_state_;
        std::array<MarkerSet, static_cast<uint32_t>(EnumType::__LAST)> marker_set_;
 
        // This tracker is a unique pointer with its own deleter which
        // knows what to do, when deleted.
        tracker::state_tracker_ptr<EnumType> state_tracker_unit_;
    }; // class State
 
    // SimulationConfiguration which holds the state tracker
    // name. The Simulation class contains an instance of this
    // state template. When Simulation is being torn down,
    // the destructor  of this class is invoked and then in turn
    // we start doing all the data collection and processing from
    // each and every state tracker unit ever used, which are all
    // queued up in their respective queues.
    template<typename T>
    class State<T,
                typename std::enable_if<
                    std::is_same<T, PhasedObject::TreePhase>::value>::type> {
    public:
        State(app::Simulation * sim);
        void configure();
        ~State();
 
    private:
        app::Simulation * sim_ = nullptr;
    };
}