NotificationSource.hpp

// <NotificationSource> -*- C++ -*-
 
#pragma once
 
#include <array>
#include <functional>
#include <iostream>
#include <sstream>
#include <type_traits>
#include <vector>
 
#include "sparta/simulation/TreeNode.hpp"
#include "sparta/utils/SpartaException.hpp"
#include "sparta/utils/SpartaAssert.hpp"
#include "sparta/utils/StringManager.hpp"
namespace sparta
{
 
    #define REGISTER_FOR_THIS(func)                                         \
        registerForThis<typename std::remove_reference<decltype(*this)>::type, \
                        &std::remove_reference<decltype(*this)>::type::func>(this);
 
    #define DEREGISTER_FOR_THIS(func)                                       \
        deregisterForThis<typename std::remove_reference<decltype(*this)>::type, \
                          &std::remove_reference<decltype(*this)>::type::func>(this);
 
    template<typename T>
    class MirrorNotificationSource;
 
    class NotificationSourceBase : public TreeNode
    {
    public:
        template <typename T>
        friend class MirrorNotificationSource;
        using TreeNode::DelegateVector;
        using TreeNode::delegate;
 
 
        enum class ObservationStateChange {
            SOLE_OBSERVER_REGISTERING,   
            SOLE_OBSERVER_DEREGISTERING, 
            OBSERVER_REGISTERING,        
            OBSERVER_DEREGISTERING       
        };
 
        typedef std::function<void (NotificationSourceBase const &, uint32_t)> callback_t;
 
        class ObservationStateCallback {
 
            ObservationStateChange type_;
            callback_t callback_;
            TreeNode::ConstWeakPtr tree_node_weak_ptr_;
            NotificationSourceBase& ns_;
 
        public:
 
            ObservationStateCallback(NotificationSourceBase& ns,
                                     ObservationStateChange type,
                                     callback_t callback)
              : type_(type),
                callback_(callback),
                tree_node_weak_ptr_(ns.getWeakPtr()),
                ns_(ns)
            {
                ObservationStateCallbackPrivateInterface::registerObservationStateChangeCallback_(ns_, this);
            }
 
            ~ObservationStateCallback()
            {
                // Deregister from notification ONLY if the node has not been destroyed already
                if (tree_node_weak_ptr_.expired() == false) {
                    ObservationStateCallbackPrivateInterface::deregisterObservationStateChangeCallback_(ns_, this);
                }
            }
 
            ObservationStateCallback(const ObservationStateCallback&) = delete;
            ObservationStateCallback(ObservationStateCallback&&) = delete;
            ObservationStateCallback& operator= (const ObservationStateCallback&) = delete;
 
            ObservationStateChange getType() const { return type_; }
 
            void operator()(NotificationSourceBase const & ns,
                            uint32_t observers) const
            {
                callback_(ns, observers);
            }
 
            void dump(std::ostream& o) const {
                o << "<ObservationStateCallback type=" << static_cast<int>(type_) << " node=";
                if(tree_node_weak_ptr_.expired()){
                    o << "EXPIRED";
                }else{
                    o << tree_node_weak_ptr_.lock()->getLocation();
                }
                o << ">";
            }
        };
 
        class ObservationStateCallbackPrivateInterface {
        private:
            static void registerObservationStateChangeCallback_(NotificationSourceBase & ns,
                                                                ObservationStateCallback* const cbobject)
            {
                ns.registerObservationStateChangeCallback_(cbobject);
            }
 
 
            static void deregisterObservationStateChangeCallback_(NotificationSourceBase & ns,
                                                                  ObservationStateCallback* const cbobject)
            {
                ns.deregisterObservationStateChangeCallback_(cbobject);
            }
 
            friend class ObservationStateCallback; 
        };
 
        friend class ObservationStateCallbackInterface; 
 
 
 
        NotificationSourceBase(TreeNode* parent,
                               const std::string& name,
                               const std::string& group,
                               TreeNode::group_idx_type group_idx,
                               const std::string& desc,
                               const std::string* notification_name_id,
                               const std::type_info& notification_tinfo) :
            TreeNode(name, group, group_idx, desc),
            noti_id_(notification_name_id),
            noti_tinfo_(notification_tinfo),
            observed_(false),
            num_posts_(0)
        {
            if(nullptr == parent){
                throw SpartaException("NotificationSourceBase ")
                    << getLocation() << " must be constructed with a parent";
            }
 
            setExpectedParent_(parent);
 
            if(nullptr == notification_name_id){
                throw SpartaException("NotificationSourceBase ")
                    << getLocation() << " cannot be constructed with a null notification_name_id";
            }
 
            // Other initialization here
            // ...
 
            validateNotificationName(*notification_name_id);
 
            parent->addChild(this);
 
            determineObs_Nodes_();
        }
 
        NotificationSourceBase(TreeNode* parent,
                               const std::string& name,
                               const std::string& group,
                               TreeNode::group_idx_type group_idx,
                               const std::string& desc,
                               const std::string& notification_name,
                               const std::type_info& notification_tinfo) :
            NotificationSourceBase(parent, name, group, group_idx, desc,
                                   StringManager::getStringManager().internString(notification_name),
                                   notification_tinfo)
        { }
 
 
        virtual ~NotificationSourceBase() {}
 
        bool observed() const noexcept {
            return observed_;
        }
 
        static void validateNotificationName(const std::string& nm)
        {
            for(const char* rsrv : RESERVED_WORDS){
                if(nm == rsrv){
                    throw SpartaException("Notification name \"")
                        << nm << "\" is a reserved word. ";
                }
            }
 
            if(nm.size() > 0 && nm[0] == '_'){
                throw SpartaException(" Notification name \"")
                    << nm << "\" begins with an '_' which is not permitted";
            }
 
            if(nm.find("__") != std::string::npos){
                throw SpartaException(" Notification name \"")
                    << nm << "\" contains two adjacent underscores which is not permitted";
            }
 
            if(nm.find_first_of(DIGIT_CHARS) == 0){
                throw SpartaException(" Notification name \"")
                    << nm << "\" begins with a '" << nm[nm.size()-1] << "' character which is not permitted. "
                    << "A Notification name must not begin with a decimal digit.";
            }
 
            size_t pos = nm.find_first_not_of(ALPHANUM_CHARS);
            if(pos != std::string::npos){
                throw SpartaException("Notification name \"")
                    << nm << "\" contains a '" << nm[pos] << "', which is not permitted. "
                    << "A Notification name must contain only alphanumeric characters and underscores.";
            }
        }
 
 
 
        const std::string* getNotificationID() const {
            return noti_id_;
        }
 
        const std::string& getNotificationName() const {
            return *noti_id_;
        }
 
        const std::type_info& getNotificationType() const {
            return noti_tinfo_;
        }
 
        const std::string getNotificationTypeName() const {
            return demangle(noti_tinfo_.name());
        }
 
 
        const std::vector<TreeNode*>& getObservationPoints() const {
            return obs_nodes_;
        }
 
        uint32_t getNumObservationPoints() const {
            return obs_nodes_.size();
        }
 
        uint32_t getNumObservers() const {
            return dels_.size();
        }
 
        uint64_t getNumPosts() const {
            return num_posts_;
        }
 
    protected:
 
        const std::string* noti_id_;       
        const std::type_info& noti_tinfo_; 
 
        std::vector<TreeNode*> obs_nodes_;
 
        std::vector<delegate> dels_;
 
        bool observed_; 
 
        mutable uint64_t num_posts_;
 
        // Override from TreeNode
        virtual void notificationObserverAdded_(const std::type_info& tinfo,
                                                const std::string* name_id,
                                                TreeNode* obs_node,
                                                const delegate* del) override {
            // Expected to only see observation on the notification that this source can
            // generate. If these assertions are hit, then the framework is broken or
            // canGenerateNotification_ is incorrect
            sparta_assert(tinfo == noti_tinfo_);
            sparta_assert(name_id == noti_id_ || name_id == StringManager::getStringManager().EMPTY);
 
            // Add the observation point node if unique
            auto itr = std::find(obs_nodes_.begin(), obs_nodes_.end(), obs_node);
            if(itr == obs_nodes_.end()){
                obs_nodes_.push_back(obs_node);
            }
 
            dels_.push_back(*del);
 
            const bool was_observed = observed_;
            observed_ = true;
 
            // Callback happen after state changes are complete (or before) in order to allow recursion
            if(not was_observed){
                invokeObservationStateChangeCallbacks_(ObservationStateChange::SOLE_OBSERVER_REGISTERING);
            }
            invokeObservationStateChangeCallbacks_(ObservationStateChange::OBSERVER_REGISTERING);
        }
 
        // Override from TreeNode
        virtual void notificationObserverRemoved_(const std::type_info& tinfo,
                                                  const std::string* name_id,
                                                  TreeNode* obs_node,
                                                  const delegate* del) override {
            // Expected to only see observation on the notification that this source can
            // generate. If these assertions are hit, then the framework is broken or
            // canGenerateNotification_ is incorrect
            sparta_assert(tinfo == noti_tinfo_);
            sparta_assert(name_id == noti_id_ || name_id == StringManager::getStringManager().EMPTY);
 
            const bool was_observed = observed_;
 
            auto delitr = std::find(dels_.begin(), dels_.end(), *del);
            if(delitr != dels_.end()){
                dels_.erase(delitr);
            }
 
            observed_ = dels_.size() > 0;
 
            // Remove the observation point node if no delegates refer to it any more
            bool remaining = false;
            for(auto d : dels_){
                if(d.getObservationPoint() == obs_node){
                    remaining = true;
                    break;
                }
            }
            if(false == remaining){
                auto itr = std::find(obs_nodes_.begin(), obs_nodes_.end(), obs_node);
                if(itr != obs_nodes_.end()){
                    obs_nodes_.erase(itr);
                }
            }
 
            // Callback happen after state changes are complete (or before) in order to allow recursion
            // Reverse order of callback from notificationObserverAdded_.
            invokeObservationStateChangeCallbacks_(ObservationStateChange::OBSERVER_DEREGISTERING);
            if(was_observed && not observed_){
                invokeObservationStateChangeCallbacks_(ObservationStateChange::SOLE_OBSERVER_DEREGISTERING);
            }
        }
 
        // Override from TreeNode
        // Returns true only for matches on node's notification ID or the input pattern
        bool canGenerateNotification_(const std::type_info& tinfo,
                                      const std::string* id,
                                      const std::string*& match) const override {
            if(noti_tinfo_ != tinfo && tinfo != typeid(sparta::TreeNode::ANY_TYPE)){
                return false;
            }
 
            if(notificationCategoryMatch(id, noti_id_)){
                match = noti_id_;
                return true;
            }
 
            return false;
        }
 
        // Override from TreeNode
        virtual std::string stringize(bool pretty=false) const override {
            (void) pretty;
            std::stringstream ss;
            ss << '<' << getLocation() << " name:\""
               << getNotificationName() << "\" datat:(" << getNotificationTypeName()
               << ") " << " observers:" << getNumObservers()
               << " posted:" << getNumPosts() << '>';
            return ss.str();
        }
    private:
 
        // Override from TreeNode
        virtual void onAddedAsChild_() noexcept override final {
            determineObs_Nodes_();
        }
 
 
        void determineObs_Nodes_() {
            obs_nodes_.clear();
            dels_.clear();
            observed_ = false;
 
            TreeNode* node = this;
            while(node){
                node->getDelegatesRegisteredForNotification(noti_tinfo_, noti_id_, dels_);
                if(node->hasObserversRegisteredForNotification(noti_tinfo_, noti_id_)){
                    obs_nodes_.push_back(node);
                }
                node = node->getParent();
            }
 
            node = getVirtualGlobalNode();
            node->getDelegatesRegisteredForNotification(noti_tinfo_, noti_id_, dels_);
            if(node->hasObserversRegisteredForNotification(noti_tinfo_, noti_id_)){
                obs_nodes_.push_back(node);
            }
 
            // Update observed flag
            observed_ = dels_.size() > 0;
        }
 
        // Override from TreeNode
        // Adds this node's notification info
        void getPossibleNotifications_(std::vector<NotificationInfo>& infos) const override {
            infos.emplace_back(this, &noti_tinfo_, noti_id_);
        }
 
        void registerObservationStateChangeCallback_(ObservationStateCallback* const hook) {
            // User errors
            sparta_assert(in_observation_state_change_callback_ == false,
                        "cannot add observation state change callbacks from within a callback");
 
            // Internal errors
            sparta_assert(hook); // Internal-only hook argument is null somehow?
            sparta_assert(std::find(obs_state_change_cbs_.begin(), obs_state_change_cbs_.end(), hook) == obs_state_change_cbs_.end(),
                        "Internal notification hook " << *hook
                        << " was installed a second time to notification source " << *this);
 
            // Track it in a list
            obs_state_change_cbs_.emplace_back(hook);
        }
 
        void deregisterObservationStateChangeCallback_(ObservationStateCallback* const hook) {
            // User errors
            sparta_assert(in_observation_state_change_callback_ == false,
                        "cannot remove observation state change callbacks from within a callback");
 
            const auto itr = std::find(obs_state_change_cbs_.begin(), obs_state_change_cbs_.end(), hook);
 
            // Internal error checking
            sparta_assert(itr != obs_state_change_cbs_.end(),
                        "Internal notification hook " << *hook
                        << " was not found  while attemptint to deregister it from notification source " << *this);
 
            // Remove it so it is no longer called
            obs_state_change_cbs_.erase(itr);
        }
 
        void invokeObservationStateChangeCallbacks_(ObservationStateChange to_call) {
            // User Error
            sparta_assert(in_observation_state_change_callback_ == false,
                        "cannot recursively invoke observation state change callbacks from within a "
                        "callback. User may be changing Notification Observers in response to "
                        "changes in observation state. This is not allowed");
 
            in_observation_state_change_callback_ = true;
 
            // Break on first exception!
            try {
                for(ObservationStateCallback const * cb : obs_state_change_cbs_){
                    if(cb->getType() == to_call){
                        (*cb)(*this, getNumObservers());
                    }
                }
            } catch (...) {
                in_observation_state_change_callback_ = false;
 
                throw; // Re-throw
            }
 
            in_observation_state_change_callback_ = false;
        }
 
        std::vector<ObservationStateCallback*> obs_state_change_cbs_;
 
        bool in_observation_state_change_callback_ = false;
    };
 
 
    template <typename NotificationDataT>
    class NotificationSource : public NotificationSourceBase
    {
    public:
 
        typedef NotificationDataT data_type; 
        typedef NotificationDataT const const_data_type; 
 
 
        NotificationSource(TreeNode* parent,
                           const std::string& name,
                           const std::string& group,
                           TreeNode::group_idx_type group_idx,
                           const std::string& desc,
                           const std::string* notification_name_id) :
            NotificationSourceBase(parent, name, group, group_idx,
                                   desc, notification_name_id,
                                   typeid(NotificationDataT))
        {
            static_assert(std::is_same<
                            typename std::remove_cv<
                              typename std::remove_reference<
                                typename std::remove_pointer<NotificationDataT>::type
                              >::type
                            >::type,
                            NotificationDataT
                          >::value,
                          "NotificationDataT must NOT be a const, volatile, pointer, or reference"
                          "type. It violates at least one of these restrictions");
 
            // Other initialization here
            // ...
        }
 
        // Alternate constructor
        NotificationSource(TreeNode* parent,
                           const std::string& name,
                           const std::string& group,
                           TreeNode::group_idx_type group_idx,
                           const std::string& desc,
                           const std::string& notification_name) :
            NotificationSource(parent,
                               name,
                               group,
                               group_idx,
                               desc,
                               StringManager::getStringManager().internString(notification_name))
        {
            // Initialization handled in constructor delegation
        }
 
        // Alternate constructor
        NotificationSource(TreeNode* parent,
                           const std::string& name,
                           const std::string& desc,
                           const std::string* notification_name_id) :
            NotificationSource(parent,
                               name,
                               TreeNode::GROUP_NAME_NONE,
                               TreeNode::GROUP_IDX_NONE,
                               desc,
                               notification_name_id)
        {
            // Initialization handled in constructor delegation
        }
 
        // Alternate constructor
        NotificationSource(TreeNode* parent,
                           const std::string& name,
                           const std::string& desc,
                           const std::string& notification_name) :
            NotificationSource(parent,
                               name,
                               TreeNode::GROUP_NAME_NONE,
                               TreeNode::GROUP_IDX_NONE,
                               desc,
                               StringManager::getStringManager().internString(notification_name))
        {
            // Initialization handled in constructor delegation
        }
 
        // Alternate constructor with anonymous name
        NotificationSource(TreeNode* parent,
                           const std::string& group,
                           TreeNode::group_idx_type group_idx,
                           const std::string& desc,
                           const std::string* notification_name_id) :
            NotificationSource(parent,
                               "",
                               group,
                               group_idx,
                               desc,
                               notification_name_id)
        {
            // Initialization handled in constructor delegation
        }
 
        // Alternate constructor with anonymous name
        NotificationSource(TreeNode* parent,
                           const std::string& group,
                           TreeNode::group_idx_type group_idx,
                           const std::string& desc,
                           const std::string& notification_name) :
            NotificationSource(parent,
                               "",
                               group,
                               group_idx,
                               desc,
                               StringManager::getStringManager().internString(notification_name))
        {
            // Initialization handled in constructor delegation
        }
 
        ~NotificationSource() {}
 
 
 
 
        template <typename T, void (T::*TMethod)(const TreeNode&, const TreeNode&, const_data_type&)>
        void registerForThis(T* obj) {
            sparta::TreeNode::registerForNotification<data_type, T, TMethod>(obj, *noti_id_);
        }
 
        // Overload accepting a class member function signature having only a data argument
        template <typename T, void (T::*TMethod)(const_data_type&)>
        void registerForThis(T* obj) {
            sparta::TreeNode::registerForNotification<data_type, T, TMethod>(obj, *noti_id_);
        }
 
        template <typename T, void (T::*TMethod)(const TreeNode&, const TreeNode&, const_data_type&)>
        void deregisterForThis(T* obj) {
            sparta::TreeNode::deregisterForNotification<data_type, T, TMethod>(obj, *noti_id_);
        }
 
        // Overload accepting a class member function signature having only a data argument
        template <typename T, void (T::*TMethod)(const_data_type&)>
        void deregisterForThis(T* obj) {
            sparta::TreeNode::deregisterForNotification<data_type, T, TMethod>(obj, *noti_id_);
        }
 
        void postNotification(const NotificationDataT& data) const {
            ++num_posts_;
 
            // Could notify observers at this node and above through TreeNode's propagation interface
            //sparta_assert(getParent() != nullptr,
            //                  "Cannot postNotification from NotificationSource " << getLocation() << " because parent is null");
            //postPropagatingNotification_(this, data, noti_id_);
 
            // Could Notify all observing TreeNodes and allow them to invoke delegates
            //for(TreeNode* o_node : obs_nodes_){
            //    invokeDelegatesOn_(o_node, data, noti_id_);
            //}
 
            // Directly invoke all applicable delegates.
            // Note that this works even if ancestors are destroyed because
            // deregistration does not take place.
            for(const delegate& d : dels_){
                d(*this, data);
            }
        }
 
    };
 
    class SprintfNotificationSource : public NotificationSource<std::string>
    {
    public:
        using NotificationSource<std::string>::NotificationSource;
 
        void setFormatString(const std::string& format_str)
        {
            // The format_str looks something like "%s_$i.json".
            // In the event that we have multiple reports setup
            // to be triggered by the same notif source, we need
            // to ensure that the format specifiers are the same
            // for all ReportDescriptor dest_file's we are given.
            auto specs = parseFormatSpecifiers_(format_str);
            if (!parsed_specs_.empty())
            {
                sparta_assert(specs == parsed_specs_);
            }
            else
            {
                parsed_specs_ = specs;
            }
 
            format_str_ = format_str;
        }
 
        bool hasFormatString() const {
            return !format_str_.empty();
        }
 
        template <typename... Args>
        void postNotification(Args... args) const
        {
            sparta_assert(!format_str_.empty(),
                          "setFormatString() must be called before postNotification() on " << getLocation());
 
            constexpr std::array<SpecType, sizeof...(Args)> expected_types { specTypeFor_<Args>()... };
 
            if(parsed_specs_.size() != sizeof...(Args)){
                throw SpartaException("Sprintf format string \"")
                    << format_str_ << "\" for " << getLocation() << " has " << parsed_specs_.size()
                    << " specifier(s) but " << sizeof...(Args) << " argument(s) were given";
            }
 
            for(std::size_t i = 0; i < parsed_specs_.size(); ++i){
                if(parsed_specs_[i] != expected_types[i]){
                    throw SpartaException("Sprintf format string \"")
                        << format_str_ << "\" for " << getLocation()
                        << " has a type mismatch at specifier index " << i;
                }
            }
 
            // One stream-to-ostringstream lambda per argument, invoked in order as specifiers are encountered
            const std::array<std::function<void(std::ostringstream&)>, sizeof...(Args)> streamers {
                [&args](std::ostringstream& o){ o << args; }...
            };
 
            std::ostringstream oss;
            std::size_t arg_idx = 0;
            for(std::size_t i = 0; i < format_str_.size(); ++i){
                if(format_str_[i] != '%'){
                    oss << format_str_[i];
                    continue;
                }
 
                const char spec = format_str_[++i];
                if(spec == '%'){
                    oss << '%';
                }else{
                    streamers[arg_idx++](oss);
                }
            }
 
            NotificationSource<std::string>::postNotification(oss.str());
        }
 
    private:
        enum class SpecType { STRING, INT };
 
        // Maps an argument type to the specifier it must match (%i for non-bool integrals, %s otherwise)
        template <typename T>
        static constexpr SpecType specTypeFor_()
        {
            using PlainT = typename std::remove_cv<typename std::remove_reference<T>::type>::type;
            if constexpr (std::is_integral<PlainT>::value && !std::is_same<PlainT, bool>::value){
                return SpecType::INT;
            }else{
                return SpecType::STRING;
            }
        }
 
        // Runtime scan of format_str for %s/%i/%% specifiers, in order of appearance
        static std::vector<SpecType> parseFormatSpecifiers_(const std::string& format_str)
        {
            std::vector<SpecType> specs;
            for(std::size_t i = 0; i < format_str.size(); ++i){
                if(format_str[i] != '%'){
                    continue;
                }
 
                if(i + 1 >= format_str.size()){
                    throw SpartaException("Sprintf format string \"")
                        << format_str << "\" ends with a lone '%' character";
                }
 
                const char spec = format_str[++i];
                switch(spec){
                    case 's':
                        specs.push_back(SpecType::STRING);
                        break;
                    case 'i':
                        specs.push_back(SpecType::INT);
                        break;
                    case '%':
                        break; // Literal '%', not a specifier
                    default:
                        throw SpartaException("Sprintf format string \"")
                            << format_str << "\" contains unsupported specifier '%" << spec
                            << "'. Only %s and %i are supported";
                }
            }
            return specs;
        }
 
        std::string format_str_;
        std::vector<SpecType> parsed_specs_;
    };
 
    template<typename NotificationDataT>
    class MirrorNotificationSource : public NotificationSourceBase
    {
        typedef std::vector<NotificationSourceBase*> SrcList;
    public:
        MirrorNotificationSource(TreeNode* parent,
                                 const std::string& name,
                                 const std::string& group,
                                 TreeNode::group_idx_type group_idx,
                                 const std::string& desc,
                                 const std::string* notification_name_id):
            NotificationSourceBase(parent, name, group, group_idx, desc,
                                   notification_name_id,
                                   typeid(NotificationDataT))
        {}
 
        MirrorNotificationSource(TreeNode* parent,
                                 const std::string& name,
                                 const std::string& group,
                                 TreeNode::group_idx_type group_idx,
                                 const std::string& desc,
                                 const std::string& notification_name) :
            NotificationSourceBase(parent, name, group, group_idx,
                                   desc,
                                   notification_name,
                                   typeid(NotificationDataT))
        {}
 
        // Alternate constructor
        MirrorNotificationSource(TreeNode* parent,
                           const std::string& name,
                           const std::string& desc,
                           const std::string& notification_name) :
            MirrorNotificationSource(parent,
                                     name,
                                     TreeNode::GROUP_NAME_NONE,
                                     TreeNode::GROUP_IDX_NONE,
                                     desc,
                                     StringManager::getStringManager().internString(notification_name))
        {}
 
        void addLink(TreeNode *node, const std::string &label) override final
        {
            (void)label; // We do not care about the label.
            sparta_assert(node != nullptr);
            const uint32_t prev_size = concretes_.size();
            findMatchingSourcesBelowNode_(*node, concretes_);
            // Make sure we found atleast 1 node that we are shadowing,
            // otherwise this MirrorNotificationSource is not linked to
            // anyone and should be taken out.
            if (concretes_.size() - prev_size == 0)
            {
                SpartaException ex("MirrorNotificationSource \"");
                ex << getName() << "\" was unable to bind to any real NotificationSources"
                   << " found under the nodes provided to addLink().";
                throw ex;
            }
        }
    private:
 
        void findMatchingSourcesBelowNode_(sparta::TreeNode& node,
                                           SrcList& bases)
        {
            auto* as_src = dynamic_cast<NotificationSourceBase*>(&node);
            if (as_src)
            {
                // If this MirrorNotificationSource happened to live under the search
                // of node, then we would certainly not want to add ourselves as a
                // concrete instance!
                if (as_src != this)
                {
                    // We won't mirror anything that isn't explicitly allowed by the concrete
                    // source.
                    if (as_src->getNotificationID() == getNotificationID() &&
                        as_src->getNotificationType() == getNotificationType())
                    {
                        bases.emplace_back(dynamic_cast<NotificationSourceBase*>(&node));
                    }
                }
            }
 
            for (auto n : node.getChildren())
            {
                findMatchingSourcesBelowNode_(*n, bases);
            }
 
        }
        // Override from TreeNode
        void notificationObserverAdded_(const std::type_info& tinfo,
                                        const std::string* name_id,
                                        TreeNode* obs_node,
                                        const delegate* del) override final
        {
            if (del->revealsOrigin())
            {
                SpartaException ex("Cannot register for notification \"");
                ex << *name_id << "\"" << " because this notification source "
                   << "is only shadowing a private concrete notification source. "
                   << "The callback signature type would reveal access to a private node "
                   << "and be misleading. We do not support this feature at this time.";
                throw ex;
            }
 
            if (concretes_.size() == 0)
            {
                SpartaException ex ("Cannot register for notification \"");
                ex << *name_id << "\" because this is a MirrorNotificationSource "
                   << "that is not linked to any concrete sources. It is possible you "
                   << "are registering for the notification too early and should be registering "
                   << "during onBindTreeLate_()";
                throw ex;
            }
            for(auto concrete : concretes_)
            {
                concrete->notificationObserverAdded_(tinfo, name_id,
                                                     obs_node, del);
            }
        }
        // Override from TreeNode
        void notificationObserverRemoved_(const std::type_info& tinfo,
                                                  const std::string* name_id,
                                                  TreeNode* obs_node,
                                                  const delegate* del) override final
        {
            if (concretes_.size() == 0)
            {
                SpartaException ex ("Cannot deregister for notification \"");
                ex << *name_id << "\" because this is a MirrorNotificationSource "
                   << "that is not linked to any concrete sources. It is possible you "
                   << "are deregistering for the notification too early and should be registering "
                   << "during onBindTreeLate_()";
                throw ex;
            }
 
            for(auto concrete : concretes_)
            {
                concrete->notificationObserverRemoved_(tinfo, name_id,
                                                       obs_node, del);
            }
        }
        // Override from TreeNode
        // Returns true only for matches on node's notification ID or the input pattern
        bool canGenerateNotification_(const std::type_info& tinfo,
                                      const std::string* id,
                                      const std::string*& match) const override final
        {
            if (concretes_.size() == 0)
            {
                return false;
            }
            bool can_generate = true;
            for (auto noti_src : concretes_)
            {
                can_generate &= noti_src->canGenerateNotification_(tinfo, id, match);
            }
            return can_generate;
        }
 
        void validateNode_() const override final
        {
            if (concretes_.size() == 0)
            {
                SpartaException ex("Unbound MirrorNotificationSource ");
                ex << getName() << " was never bound to concrete notification sources.";
                throw ex;
            }
        }
 
        // Override from TreeNode
        virtual std::string stringize(bool pretty=false) const override final {
            (void) pretty;
            std::stringstream ss;
            ss << NotificationSourceBase::stringize(pretty);
            ss << " shadows: ";
            try{
                ss << concretes_.size() << " sources ";
            }
            catch (SpartaException&)
            {
                ss << "[UNAVAILABLE]";
            }
            return ss.str();
        }
        SrcList concretes_;
    };
 
    inline std::ostream& operator<<(std::ostream& o, const NotificationSourceBase::ObservationStateCallback& osc)
    {
        osc.dump(o);
        return o;
    }
 
    inline std::ostream& operator<<(std::ostream& o, const NotificationSourceBase::ObservationStateCallback* osc)
    {
        if(osc == nullptr){
            o << "nullptr";
        }else{
            o << *osc;
        }
        return o;
    }
 
} // namespace sparta