notice.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_BASE_TF_NOTICE_H
#define PXR_BASE_TF_NOTICE_H


#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/anyWeakPtr.h"
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/type.h"
#include "pxr/base/tf/weakPtr.h"
#include "pxr/base/arch/demangle.h"
#include "pxr/base/arch/hints.h"

#include <list>
#include <typeinfo>

PXR_NAMESPACE_OPEN_SCOPE

class Tf_NoticeRegistry;

class TfNotice {
private:
    class _DelivererBase;
    typedef TfWeakPtr<_DelivererBase> _DelivererWeakPtr;
    typedef std::list<_DelivererBase*> _DelivererList;
    
    // Per-sender delivery, listener gets sender.
    template <class LPtr, class L,
              class Notice, class SPtr, class DeliveredSPtr>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener, 
                   void (L::*method)
                   (const Notice &, DeliveredSPtr const &),
                   SPtr const &sender) {
        DeliveredSPtr weakSender(sender);
        return new _DelivererWithSender<
            LPtr, DeliveredSPtr,
            void (L::*)(const Notice &, DeliveredSPtr const &),
            Notice
        >(listener, method, weakSender);
    }

    template <class LPtr, class L,
              class Notice, class SPtr, class DeliveredSPtr>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener, 
                   void (L::*method)
                   (const Notice &, DeliveredSPtr const &) const,
                   SPtr const &sender) {
        DeliveredSPtr weakSender(sender);
        return new _DelivererWithSender<
            LPtr, DeliveredSPtr,
            void (L::*)(const Notice &, DeliveredSPtr const &) const,
            Notice
        >(listener, method, weakSender);
    }

    // Per-sender delivery, listener does not get sender.
    template <class LPtr, class L, class SPtr, class Notice>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener,
                   void (L::*method)(const Notice &),
                   SPtr const &sender) {
        return new _Deliverer<
            LPtr, SPtr, void (L::*)(const Notice &), Notice
        >(listener, method, sender);
    }

    template <class LPtr, class L, class SPtr, class Notice>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener,
                   void (L::*method)(const Notice &) const,
                   SPtr const &sender) {
        return new _Deliverer<
            LPtr, SPtr, void (L::*)(const Notice &) const, Notice
        >(listener, method, sender);
    }

    // Global delivery.
    template <class LPtr, class L, class Notice>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener,
                   void (L::*method)(const Notice &)) {
        return new _Deliverer<
            LPtr, TfAnyWeakPtr, void (L::*)(const Notice &), Notice
        >(listener, method);
    }

    template <class LPtr, class L, class Notice>
    static _DelivererBase *
    _MakeDeliverer(LPtr const &listener,
                   void (L::*method)(const Notice &) const) {
        return new _Deliverer<
            LPtr, TfAnyWeakPtr, void (L::*)(const Notice &) const, Notice
        >(listener, method);
    }

    // Generic (raw) delivery.
    template <class LPtr, class L>
    static _DelivererBase *
    _MakeDeliverer(TfType const &noticeType,
                   LPtr const &listener,
                   void (L::*method)(const TfNotice &,
                                     const TfType &,
                                     TfWeakBase*, const void *,
                                     const std::type_info&),
                   TfAnyWeakPtr const &sender) {
        return new _RawDeliverer<LPtr,
            void (L::*)(const TfNotice &, const TfType &,
                        TfWeakBase *, const void *,
                        const std::type_info &)>
            (listener, method, sender, noticeType);
    }

    template <class LPtr, class L>
    static _DelivererBase *
    _MakeDeliverer(TfType const &noticeType,
                   LPtr const &listener,
                   void (L::*method)(const TfNotice &,
                                     const TfType &,
                                     TfWeakBase*, const void *,
                                     const std::type_info&) const,
                   TfAnyWeakPtr const &sender)
    {
        return new _RawDeliverer<LPtr,
            void (L::*)(const TfNotice &, const TfType &,
                        TfWeakBase *, const void *,
                        const std::type_info &) const>
            (listener, method, sender, noticeType);
    }

    
    
public:

    class Probe;
    typedef TfWeakPtr<Probe> WeakProbePtr;
    
    class Probe : public TfWeakBase {
      public:
        TF_API
        virtual ~Probe() = 0;

        virtual void BeginSend(const TfNotice &notice,
                               const TfWeakBase *sender,
                               const std::type_info &senderType) = 0;

        virtual void EndSend() = 0;

        virtual void BeginDelivery(const TfNotice &notice,
                                   const TfWeakBase *sender,
                                   const std::type_info &senderType,
                                   const TfWeakBase *listener,
                                   const std::type_info &listenerType) = 0;

        virtual void EndDelivery() = 0;
    };

    class Key {
    public:
        Key() {}

        bool IsValid() const {
            return _deliverer && _deliverer->_IsActive();
        }

        operator bool() const {
            return IsValid();
        }

    private:
        Key(const _DelivererWeakPtr & d) : _deliverer(d) {}

        _DelivererWeakPtr _deliverer;

        friend class Tf_NoticeRegistry;
        friend class TfNotice;
    };

    typedef std::vector<Key> Keys;

    TF_API
    static void InsertProbe(const WeakProbePtr &probe);

    TF_API
    static void RemoveProbe(const WeakProbePtr &probe);

    template <class LPtr, class MethodPtr>
    static TfNotice::Key
    Register(LPtr const &listener, MethodPtr method) {
        return _Register(_MakeDeliverer(listener, method));
    }

    template <class LPtr, class MethodPtr, class SenderPtr>
    static TfNotice::Key
    Register(LPtr const &listener, MethodPtr method, SenderPtr const &sender) {
        return _Register(_MakeDeliverer(listener, method, sender));
    }

    template <class LPtr, class MethodPtr>
    static TfNotice::Key
    Register(LPtr const &listener, MethodPtr method,
             const TfType &noticeType, const TfAnyWeakPtr &sender) {
        return _Register(_MakeDeliverer(noticeType, listener, method, sender));
    }
    
    TF_API
    static bool Revoke(TfNotice::Key& key);
    
    TF_API
    static void Revoke(TfNotice::Keys* keys);

    TF_API 
    size_t Send() const;
    
    template <typename SenderPtr>
    size_t Send(SenderPtr const &s) const;
    
    TF_API 
    size_t SendWithWeakBase(const TfWeakBase *senderWeakBase,
                            const void *senderUniqueId,
                            const std::type_info &type) const;

    TF_API
    virtual ~TfNotice();

    class Block {
    public:
        TF_API Block();
        TF_API ~Block();
    };

private:
    // Abstract base class for calling listeners.
    // A typed-version derives (via templating) off this class.
    class _DelivererBase : public TfWeakBase {
    public:
        _DelivererBase()
            : _list(0), _active(true), _markedForRemoval(false)
        {
        }
        
        TF_API
        virtual ~_DelivererBase();

        TF_API 
        void _BeginDelivery(const TfNotice &notice,
                            const TfWeakBase *sender,
                            const std::type_info &senderType,
                            const TfWeakBase *listener,
                            const std::type_info &listenerType,
                            const std::vector<TfNotice::WeakProbePtr> &probes);

        TF_API 
        void _EndDelivery(const std::vector<TfNotice::WeakProbePtr> &probes);

        // The derived class converts n to the proper type and delivers it by
        // calling the listener's method.  The function returns \c true,
        // unless the listener has expired or been marked in active (i.e. by
        // TfNotice::Revoke()), in which case the method call is skipped and
        // \c false is returned.
        virtual bool
        _SendToListener(const TfNotice &n,
                        const TfType &type,
                        const TfWeakBase *s,
                        const void *senderUniqueId,
                        const std::type_info &senderType,
                        const std::vector<TfNotice::WeakProbePtr> &probes) = 0;

        void _Deactivate() {
            _active = false;
        }
        
        bool _IsActive() const {
            return _active;
        }

        void _MarkForRemoval() {
            _markedForRemoval = true;
        }
        
        // True if the entry has been added to the _deadEntries list for
        // removal.  Used to avoid adding it more than once to the list.
        bool _IsMarkedForRemoval() const {
            return _markedForRemoval;
        }

        virtual TfType GetNoticeType() const = 0;
        
        virtual bool Delivers(TfType const &noticeType,
                              const TfWeakBase *sender) const = 0;
        
        virtual TfWeakBase const *GetSenderWeakBase() const = 0;

        virtual _DelivererBase *Clone() const = 0;
        
    protected:
        
        template <class ToNoticeType, class FromNoticeType>
        static inline ToNoticeType const *
        _CastNotice(FromNoticeType const *from) {
            // Dynamic casting in deliverers is significant overhead, so only
            // do error checking in debug builds.
            if (TF_DEV_BUILD) {
                if (!dynamic_cast<ToNoticeType const *>(from)) {
                    ToNoticeType const *castNotice =
                        TfSafeDynamic_cast<ToNoticeType const *>(from);
                    // this will abort with a clear error message if
                    // castNotice is NULL
                    TfNotice::_VerifyFailedCast(typeid(ToNoticeType),
                                                *from, castNotice);
                }
            }
            return static_cast<ToNoticeType const *>(from);
        }
        
    private:
        // Linkage to the containing _DelivererList in the Tf_NoticeRegistry
        _DelivererList *_list;
        _DelivererList::iterator _listIter;
        
        bool _active;
        bool _markedForRemoval;
        
        friend class Tf_NoticeRegistry;
    };

    template <class Derived>
    class _StandardDeliverer : public _DelivererBase {
    public:
        virtual ~_StandardDeliverer() {}

        virtual TfType GetNoticeType() const {
            typedef typename Derived::NoticeType NoticeType;
            TfType ret = TfType::Find<NoticeType>();
            if (ret.IsUnknown())
                TF_FATAL_ERROR("notice type " + ArchGetDemangled<NoticeType>() +
                               " undefined in the TfType system");
            return ret;
        }

        virtual bool Delivers(TfType const &noticeType,
                              TfWeakBase const *sender) const {
            Derived const *derived = this->AsDerived();
            return noticeType.IsA(GetNoticeType()) &&
                !derived->_sender.IsInvalid() &&
                sender && derived->_sender.GetWeakBase() == sender;
        }

        virtual TfWeakBase const *GetSenderWeakBase() const {
            Derived const *derived = this->AsDerived();
            return derived->_sender ? derived->_sender.GetWeakBase() : 0;
        }

        virtual _DelivererBase *Clone() const {
            Derived const *derived = this->AsDerived();
            return new Derived(derived->_listener,
                               derived->_method,
                               derived->_sender,
                               GetNoticeType());
        }
        
        virtual bool
        _SendToListener(const TfNotice &notice,
                        const TfType &noticeType,
                        const TfWeakBase *sender,
                        const void *senderUniqueId,
                        const std::type_info &senderType,
                        const std::vector<TfNotice::WeakProbePtr> &probes)
        {
            Derived *derived = this->AsDerived();
            typedef typename Derived::ListenerType ListenerType;
            typedef typename Derived::NoticeType NoticeType;
            ListenerType *listener = get_pointer(derived->_listener);

            if (listener && !derived->_sender.IsInvalid()) {
                if (ARCH_UNLIKELY(!probes.empty())) {
                    TfWeakBase const *senderWeakBase = GetSenderWeakBase(),
                        *listenerWeakBase = derived->_listener.GetWeakBase();
                    _BeginDelivery(notice, senderWeakBase,
                                   senderWeakBase ?
                                   senderType : typeid(void),
                                   listenerWeakBase,
                                   typeid(ListenerType), probes);
                }

                derived->
                    _InvokeListenerMethod(listener,
                                          *_CastNotice<NoticeType>(&notice),
                                          noticeType, sender,
                                          senderUniqueId, senderType);
                
                if (ARCH_UNLIKELY(!probes.empty()))
                    _EndDelivery(probes);

                return true;
            }
            return false;
        }
        
    private:
        Derived *AsDerived() {
            return static_cast<Derived *>(this);
        }

        Derived const *AsDerived() const {
            return static_cast<Derived const *>(this);
        }
    };
    
    
    template <typename LPtr, typename SPtr, typename Method, typename Notice>
    class _Deliverer :
        public _StandardDeliverer<_Deliverer<LPtr, SPtr, Method, Notice> >
    {
    public:
        typedef Notice NoticeType;
        typedef typename LPtr::DataType ListenerType;
        typedef Method MethodPtr;
        
        _Deliverer(LPtr const &listener,
                   MethodPtr const &methodPtr,
                   SPtr const &sender = SPtr(),
                   TfType const &noticeType = TfType())
            : _listener(listener)
            , _sender(sender)
            , _method(methodPtr)
        {
        }

        void _InvokeListenerMethod(ListenerType *listener,
                                   const NoticeType &notice,
                                   const TfType &noticeType,
                                   const TfWeakBase *,
                                   const void *,
                                   const std::type_info &)
        {
            (listener->*_method)(notice);
        }
        
        LPtr _listener;
        SPtr _sender;
        MethodPtr _method;
    };
    
    template <class LPtr, class Method>
    class _RawDeliverer :
        public _StandardDeliverer<_RawDeliverer<LPtr, Method> >
    {
    public:
        typedef TfNotice NoticeType;
        typedef typename LPtr::DataType ListenerType;
        typedef Method MethodPtr;

        _RawDeliverer(LPtr const &listener,
                      MethodPtr const &methodPtr,
                      TfAnyWeakPtr const &sender,
                      TfType const &noticeType)
            : _noticeType(noticeType),
              _listener(listener),
              _method(methodPtr),
              _sender(sender)
        {
        }

        virtual TfType GetNoticeType() const {
            return _noticeType;
        }

        void _InvokeListenerMethod(ListenerType *listener,
                                   const NoticeType &notice,
                                   const TfType &noticeType,
                                   const TfWeakBase *sender,
                                   const void *senderUniqueId,
                                   const std::type_info &senderType)
        {
            (listener->*_method)(notice, noticeType,
                                 const_cast<TfWeakBase *>(sender),
                                 senderUniqueId, senderType);
        }
        
        TfType _noticeType;
        LPtr _listener;
        MethodPtr _method;
        TfAnyWeakPtr _sender;
    };

    template <class LPtr, class SPtr, class Method, class Notice>
    class _DelivererWithSender :
        public _StandardDeliverer<
            _DelivererWithSender<LPtr, SPtr, Method, Notice>
        >
    {
    public:
        typedef Notice NoticeType;
        typedef Method MethodPtr;
        typedef typename LPtr::DataType ListenerType;

        typedef typename SPtr::DataType SenderType;

        _DelivererWithSender(LPtr const &listener,
                             MethodPtr const &methodPtr,
                             SPtr const &sender,
                             TfType const &noticeType = TfType())
            : _listener(listener),
              _sender(sender),
              _method(methodPtr)
        {
        }
 
        void _InvokeListenerMethod(ListenerType *listener,
                                   const NoticeType &notice,
                                   const TfType &noticeType,
                                   const TfWeakBase *sender,
                                   const void *,
                                   const std::type_info &)
        {
            SenderType *deliveredSender =
                static_cast<SenderType *>(const_cast<TfWeakBase *>(sender));
            SPtr deliveredSPtr(deliveredSender);
            (listener->*_method)(notice, deliveredSPtr);
        }
        
        LPtr _listener;
        SPtr _sender;
        MethodPtr _method;
    };

private:
    // Internal non-templated function to install listeners.
    TF_API
    static Key _Register(_DelivererBase*);

    TF_API
    static void _VerifyFailedCast(const std::type_info& toType,
                                  const TfNotice& notice,
                                  const TfNotice* castNotice);

    TF_API 
    size_t _Send(const TfWeakBase* sender,
                 const void *senderUniqueId,
                 const std::type_info & senderType) const;
    TF_API
    size_t _SendWithType(const TfType & noticeType,
                         const TfWeakBase* sender,
                         const void *senderUniqueId,
                         const std::type_info & senderType) const;

    friend class Tf_NoticeRegistry;

    // Befriend the wrapping so it can access _SendWithType() directly
    // in order to provide dynamic downcasting of Python notice types.
    friend class Tf_PyNotice;
};

template <typename SenderPtr> 
size_t 
TfNotice::Send(SenderPtr const &s) const
{
    const TfWeakBase *senderWeakBase = s ? s.GetWeakBase() : NULL;
    return _Send(senderWeakBase, senderWeakBase ? s.GetUniqueIdentifier() : 0,
                 senderWeakBase ?
                 typeid(typename SenderPtr::DataType) : typeid(void));
}

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_BASE_TF_NOTICE_H