Observer.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  @file Observer.h
  @brief Publisher-subscriber pattern, also known as Observer
 
  Paul Licameli
 
**********************************************************************/
#ifndef __AUDACITY_OBSERVER__
#define __AUDACITY_OBSERVER__
 
#include <cassert>
#include <functional>
#include <memory>
#include <type_traits>
 
namespace Observer {
 
// See below
template<typename Message, bool NotifyAll>
class Publisher;
 
struct Message {};
 
struct UTILITY_API ExceptionPolicy {
   virtual ~ExceptionPolicy() noexcept;
   virtual void OnBeginPublish() = 0;
   // In a catch block, can rethrow or store std::current_exception()
   virtual bool OnEachFailedCallback() noexcept(false) = 0;
   virtual void OnEndPublish() noexcept(false) = 0;
};
 
class Subscription;
 
namespace detail {
struct RecordBase;
struct RecordLink{
   std::shared_ptr<RecordBase> next;
};
struct UTILITY_API RecordBase : RecordLink {
   std::weak_ptr<RecordLink> prev;
   void Unlink() noexcept;
};
struct UTILITY_API RecordList
   : RecordLink, std::enable_shared_from_this<RecordLink> {
   using Visitor = bool(*)(const RecordBase &record, const void *arg);
   explicit RecordList(ExceptionPolicy *pPolicy, Visitor visitor);
   ~RecordList() noexcept;
   Subscription Subscribe(std::shared_ptr<RecordBase> pRecord);
   bool Visit(const void *arg);
private:
   ExceptionPolicy *const m_pPolicy;
   const Visitor m_visitor;
};
}
 
class UTILITY_API Subscription {
public:
   Subscription();
   Subscription(Subscription &&);
   Subscription &operator=(Subscription &&);
 
   ~Subscription() noexcept { Reset(); }
 
   void Reset() noexcept;
 
   bool Expired() const { return m_wRecord.expired(); }
 
   explicit operator bool() const { return !Expired(); }
 
private:
   friend detail::RecordList;
   explicit Subscription(std::weak_ptr<detail::RecordBase> pRecord);
   std::weak_ptr<detail::RecordBase> m_wRecord;
};
 
 
template<typename Message = Message, bool NotifyAll = true>
class Publisher {
public:
   struct Record;
 
   static constexpr bool notifies_all = NotifyAll;
   using message_type = Message;
 
 
   template<typename Alloc = std::allocator<Record>>
   explicit Publisher(ExceptionPolicy *pPolicy = nullptr, Alloc a = {});
 
   Publisher(Publisher&&) = default;
   Publisher& operator=(Publisher&&) = default;
 
   using CallbackReturn = std::conditional_t<NotifyAll, void, bool>;
 
   using Callback = std::function< CallbackReturn(const Message&) >;
 
 
   [[nodiscard]] Subscription Subscribe(Callback callback);
 
   template<typename Object, typename Return, typename... Args>
   Subscription Subscribe(
      Object &obj, Return (Object::*callback)(Args...))
   {
      return Subscribe( [&obj, callback](const Message &message){
         return (obj.*callback)(message);
      } );
   }
 
   struct Record : detail::RecordBase {
      explicit Record(Callback callback) : callback{ move(callback) } {}
      Callback callback;
   };
 
protected:
 
   CallbackReturn Publish(const Message &message);
 
private:
   // RecordList needs to be non-relocating but the Publisher object is movable
   std::shared_ptr<detail::RecordList> m_list;
   std::function<std::shared_ptr<detail::RecordBase>(Callback)> m_factory;
};
 
template<typename Message, bool NotifyAll>
template<typename Alloc> inline
Publisher<Message, NotifyAll>::Publisher(ExceptionPolicy *pPolicy, Alloc a)
: m_list{ std::allocate_shared<detail::RecordList>( a, pPolicy,
    []( // The visitor.  Lambda with no capture converts to pointer-to-function
      const detail::RecordBase &recordBase, const void *arg){
      auto &record = static_cast<const Record&>(recordBase);
      assert(arg);
      auto &message = *static_cast<const Message*>(arg);
      assert(record.callback);
      // Calling foreign code!  Which is why we have an exception policy.
      if constexpr (NotifyAll)
         return (record.callback(message), false);
      else
         return record.callback(message);
   }
) }
, m_factory( [a = move(a)](Callback callback) {
   return std::allocate_shared<Record>(a, move(callback));
} )
{}
 
// Thin wrappers of type-erased worker functions:
 
template<typename Message, bool NotifyAll>
auto Publisher<Message, NotifyAll>::Subscribe(Callback callback)
   -> Subscription
{
   assert(callback); // precondition
   return m_list->Subscribe(m_factory(move(callback)));
}
 
template<typename Message, bool NotifyAll> inline
auto Publisher<Message, NotifyAll>::Publish(const Message &message)
   -> CallbackReturn
{
   bool result = m_list->Visit(&message);
   if constexpr (!NotifyAll)
      return result;
}
 
}
 
#endif