RootTreeNode.hpp

Go to the documentation of this file.

// <RootTreeNode> -*- C++ -*-
 
#pragma once
 
#include <memory>
#include <ostream>
#include <string>
#include <vector>
 
#include "sparta/simulation/TreeNode.hpp"
#include "sparta/simulation/TreeNodeExtensions.hpp"
#include "sparta/simulation/GlobalTreeNode.hpp"
#include "sparta/app/ConfigApplicators.hpp"
#include "sparta/log/NotificationSource.hpp"
#include "sparta/simulation/TreeNodePrivateAttorney.hpp"
#include "sparta/simulation/ParameterTree.hpp"
#include "sparta/simulation/ParameterSet.hpp"
#include "sparta/kernel/PhasedObject.hpp"
#include "sparta/utils/SpartaAssert.hpp"
#include "sparta/utils/SpartaException.hpp"
 
namespace sparta
{
    class ArchData;
    class Clock;
    class TreeNodeExtensionManager;
 
    namespace app {
        class Simulation;
    }
 
    namespace python {
        class PythonInterpreter;
    }
 
    class RootTreeNode : public TreeNode
    {
    public:
 
        typedef NotificationSource<TreeNode> NewDescendantNotiSrc;
 
        RootTreeNode(const std::string & name,
                     const std::string & desc,
                     app::Simulation* sim,
                     GlobalTreeNode* search_scope) :
            TreeNode(name, GROUP_NAME_NONE, GROUP_IDX_NONE, desc),
            sim_(sim)
        {
            if(search_scope != nullptr){
                search_node_ = search_scope;
            }else{
                search_node_ = new GlobalTreeNode();
                alloc_search_node_.reset(search_node_);
            }
            search_node_->addChild(this);
 
            /* Define the default scope that all tree nodes will be in. This is
             * to ensure that getScopeRoot() never returns nullptr event when no
             * scope is explicitly defined. */
            setScopeRoot();
 
            // Create the notification after the RTN is fully realized
            new_node_noti_.reset(
                new NewDescendantNotiSrc(this,
                                         "descendant_attached",
                                         "Notification immediately after a node becomes a descendant of this "
                                         "root at any distance. This new node may have children already attached "
                                         "which will not receive their own descendant_attached notification",
                                         "descendant_attached"));
        }
 
        RootTreeNode(const std::string & name,
                     const std::string & desc,
                     GlobalTreeNode* search_scope) :
            RootTreeNode(name, desc, nullptr, search_scope)
        {
            // Delegated construction
        }
 
        RootTreeNode(const std::string & name) :
            RootTreeNode(name, "Top of device tree", nullptr, nullptr)
        {
            // Delegated construction
        }
 
        RootTreeNode(const std::string & name,
                     const std::string & desc,
                     app::Simulation* sim) :
            RootTreeNode(name, desc, sim, nullptr)
        {
            // Delegated construction
        }
 
        RootTreeNode(const std::string & name,
                     const std::string & desc) :
            RootTreeNode(name, desc, nullptr, nullptr)
        {
            // Delegated construction
        }
 
        RootTreeNode(app::Simulation* sim) :
            RootTreeNode("top", "Top of device tree", sim, nullptr)
        {
            // Delegated construction
        }
 
        RootTreeNode(GlobalTreeNode* search_scope) :
            RootTreeNode("top", "Top of device tree", nullptr, search_scope)
        {
            // Delegated construction
        }
 
        RootTreeNode(app::Simulation* sim, GlobalTreeNode* search_scope) :
            RootTreeNode("top", "Top of device tree", sim, search_scope)
        {
            // Delegated construction
        }
 
        RootTreeNode() :
            RootTreeNode("top", "Top of device tree", nullptr, nullptr)
        {
            // Delegated construction
        }
 
        virtual ~RootTreeNode() {
            // Inform Search Scope node since it will not be notified by
            // ~TreeNode, which does not recognize the search scope as a parent
            if(search_node_){
                removeFromParentForTeardown_(search_node_);
            }
 
            // No need to alert children, because ~TreeNode will do this next
        }
 
        // Returns true. Tree root is always considered "attached"
        virtual bool isAttached() const override final {
            return true;
        }
 
        // Returns 0. Tree root will never have a parent
        virtual TreeNode* getParent() override final { return nullptr; }
 
        // Returns 0. Tree root will never have a parent
        virtual const TreeNode* getParent() const override final { return nullptr; }
 
        // Override TreeNode::setClock() so we can pass that clock to the search scope
        virtual void setClock(const Clock * clk) override final {
            if (search_node_) {
                search_node_->setClock(clk);
            }
            TreeNode::setClock(clk);
        }
 
        app::Simulation* getSimulator() const {
            return sim_;
        }
 
        GlobalTreeNode* getSearchScope(){
            sparta_assert(search_node_);
            return search_node_;
        }
 
        void enterConfiguring(){
            if(getPhase() != TREE_BUILDING){
                throw SpartaException("Device tree with root \"")
                    << getLocation()<< "\" not currently in the TREE_BUILDING phase, so it cannot "
                                       "enter TREE_CONFIGURING";
            }
 
            enterConfig_(); // Enter the next phase (cannot throw)
        }
 
        void enterFinalized(sparta::python::PythonInterpreter* pyshell = nullptr);
 
        void bindTreeEarly() {
            if(getPhase() != TREE_FINALIZED){
                throw SpartaException("Device tree with root \"")
                    << getLocation()
                    << "\" not in the TREE_FINALIZED phase, so it cannot be bound (bindTreeEarly)";
            }
 
            bindTreeEarly_();
        }
 
        void bindTreeLate() {
            if(getPhase() != TREE_FINALIZED){
                throw SpartaException("Device tree with root \"")
                    << getLocation()
                    << "\" not in the TREE_FINALIZED phase, so it cannot be bound (bindTreeLate)";
            }
 
            bindTreeLate_();
        }
 
        void simulationTerminating() {
            simulationTerminating_();
        }
 
        void validatePreRun() {
            if(getPhase() != TREE_FINALIZED){
                throw SpartaException("Device tree with root \"")
                    << getLocation()
                    << "\" not in the TREE_FINALIZED phase, so it cannot be pre-run validated";
            }
 
            validateTree_(); // Validate all nodes, which may throw
        }
 
 
        void validatePostRun();
 
        void dumpDebugContent(std::ostream& out) noexcept {
            dumpDebugContent_(out);
        }
 
        void enterTeardown() {
            enterTeardown_(); // Enter the next phase
        }
 
        virtual std::string stringize(bool pretty=false) const override {
            (void) pretty;
            std::stringstream ss;
            ss << "<" << getLocation() << " (root)>";
            return ss.str();
        }
 
 
        NewDescendantNotiSrc& getNodeAttachedNotification() {
            return *new_node_noti_;
        }
 
 
 
        void getArchDataAssociations(std::vector<const ArchData*>& ad_this_tree,
                                     std::vector<const ArchData*>& ad_no_assoc,
                                     std::vector<const ArchData*>& ad_not_attached,
                                     std::vector<const ArchData*>& ad_other_tree) const noexcept;
 
        void validateArchDataAssociations() const;
 
        void dumpArchDataAssociations(std::ostream& o) const noexcept;
 
        void dumpTypeMix(std::ostream& o) const;
 
        void setExtensionManager(TreeNodeExtensionManager* mgr);
 
        const TreeNodeExtensionManager * getExtensionManager(bool must_exist = true) const {
            if (!extension_mgr_ && must_exist) {
                throw SpartaException("Expecting TreeNodeExtensionsManager to exist but it doesn't");
            }
            return extension_mgr_;
        }
 
        TreeNodeExtensionManager * getExtensionManager(bool must_exist = true) {
            if (!extension_mgr_ && must_exist) {
                throw SpartaException("Expecting TreeNodeExtensionsManager to exist but it doesn't");
            }
            return extension_mgr_;
        }
 
 
    private:
 
        // The TreeNodeExtensionManager object owned by CommandLineSimulator,
        // a simulation subclass, or in the SimulationConfiguration object
        // on the stack in a unit test.
        TreeNodeExtensionManager * extension_mgr_ = nullptr;
 
        // No effect on root
        virtual void createResource_() override {};
 
        virtual void onSettingParent_(const TreeNode* parent) const override final {
            if(parent != search_node_){
                throw SpartaException("This RootTreeNode \"")
                    << "\" cannot be a child of any other node except its constructed "
                       "GlobalTreeNode";
            }
        }
 
        virtual void setParent_(TreeNode* parent, bool) override final {
            if(parent != search_node_){
                throw SpartaCriticalError("This RootTreeNode \"")
                    << "\" cannot be a child of any other node except its constructed "
                       "GlobalTreeNode";
            }
 
            // NOTE: Do not store parent because the root should act as if there is no parent
        }
 
        virtual void onDescendentSubtreeAdded_(TreeNode* des) noexcept override final {
            // Broadcast notification for self coming into existence
            try{
                // There's an irony here ... how do you create the new
                // node notification object without it calling itself
                // to notify that it's adding itself?  Easy -- the
                // unique pointer isn't fully realized until it's
                // fully added to the tree node hierarchy.
                if (SPARTA_EXPECT_TRUE(new_node_noti_)) {
                    new_node_noti_->postNotification(*des);
                }
 
                // Iterate subtree headed by des and notify observers of these
                for(TreeNode* child : TreeNodePrivateAttorney::getAllChildren(des)){
                    onDescendentSubtreeAdded_(child);
                }
            }catch(SpartaException& ex){
                std::stringstream msg;
                msg << ex.what() <<
                    "\nThis exception within onDescendentSubtreeAdded_, which is not exception-"
                    "safe. The integrity of this sparta tree (" << getRoot() << ") is compromised. "
                    "Aborting. ";
                sparta_abort(false,msg.str());
            }
        }
 
        std::unique_ptr<GlobalTreeNode> alloc_search_node_;
 
        GlobalTreeNode* search_node_;
 
        app::Simulation* sim_;
 
        std::unique_ptr<NewDescendantNotiSrc> new_node_noti_;
    };
 
} // namespace sparta