ClientData.h

Go to the documentation of this file.

/*!********************************************************************
 
Audacity: A Digital Audio Editor
 
@file ClientData.h
@brief Utility ClientData::Site to register hooks into a host class that attach client data
 
Paul Licameli
 
**********************************************************************/
 
#ifndef __AUDACITY_CLIENT_DATA__
#define __AUDACITY_CLIENT_DATA__
 
#include "ClientDataHelpers.h"
 
#include <functional>
#include <iterator>
#include <optional>
#include <utility>
#include <vector>
#include "InconsistencyException.h"
 
namespace ClientData {
 
struct REGISTRIES_API Base
{
   virtual ~Base();
};
 
 
template< typename Object > using UniquePtr = std::unique_ptr< Object >;
 
template< typename Object > using BarePtr = Object*;
 
 
template<
   typename Covariant = void, // CRTP derived class when not void
   template<typename> class Owner = UniquePtr
> struct REGISTRIES_API Cloneable
{
   using Base = std::conditional_t<
      std::is_void_v<Covariant>, Cloneable, Covariant
   >;
   using PointerType = Owner< Base >;
 
   Cloneable() = default;
   Cloneable(const Cloneable&) = default;
   Cloneable &operator=(const Cloneable &) = default;
   virtual ~Cloneable() = default;
   virtual PointerType Clone() const = 0;
};
 
extern template struct REGISTRIES_API Cloneable<>;
 
 
template<
   typename Host,
   typename ClientData = Base,
 
   // Remaining parameters are often defaulted
 
   CopyingPolicy ObjectCopyingPolicy = SkipCopying,
 
   template<typename> class Pointer = UniquePtr,
 
   LockingPolicy ObjectLockingPolicy = NoLocking,
   LockingPolicy RegistryLockingPolicy = NoLocking
>
class Site
{
public:
   ~Site()
   {
      static_assert( std::has_virtual_destructor<ClientData>::value,
         "ClientData::Site requires a data class with a virtual destructor" );
   }
 
   using DataType = ClientData;
   using DataPointer = Pointer< ClientData >;
   using DataFactory = std::function< DataPointer( Host& ) >;
 
   Site()
   {
      auto factories = GetFactories();
      auto size = factories.mObject.size();
      mData.reserve( size );
   }
   Site( const Site &other )
      : mData( other.mData )
      { }
   Site& operator =( const Site & other )
      { mData = other.mData; return *this; }
   Site( Site && other )
      : mData( std::move(other.mData) )
      { }
   Site& operator =( Site && other )
      { mData = std::move(other.mData); return *this; }
 
   size_t size() const { return mData.size(); }
 
 
   static size_t numFactories() { return GetFactories().mObject.size(); }
 
 
   class RegisteredFactory
   {
   public:
      RegisteredFactory(
         DataFactory factory
      )
      {
         auto factories = GetFactories();
         mIndex = factories.mObject.size();
         factories.mObject.emplace_back( std::move( factory ) );
      }
      RegisteredFactory( RegisteredFactory &&other )
      {
         mIndex = other.mIndex;
         mOwner = other.mOwner;
         other.mOwner = false;
      }
      ~RegisteredFactory()
      {
         if (mOwner) {
            auto factories = GetFactories();
            // Should always be true, the factory vector never shrinks:
            if ( mIndex < factories.mObject.size() )
               factories.mObject[mIndex] = nullptr;
         }
      }
   private:
      friend Site;
      bool mOwner{ true };
      size_t mIndex;
   };
 
 
 
   template< typename Subclass = ClientData >
   Subclass &Get( const RegisteredFactory &key )
   {
      auto data = GetData();
      return DoGet< Subclass >( data, key );
   }
 
 
   template< typename Subclass = const ClientData >
   auto Get( const RegisteredFactory &key ) const ->
      std::enable_if_t< std::is_const< Subclass >::value, Subclass & >
   {
      auto data = GetData();
      return DoGet< Subclass >( data, key );
   }
 
 
   template< typename Subclass = ClientData >
   Subclass *Find( const RegisteredFactory &key )
   {
      auto data = GetData();
      return DoFind< Subclass >( data, key );
   }
 
 
   template< typename Subclass = const ClientData >
   auto Find( const RegisteredFactory &key ) const ->
      std::enable_if_t< std::is_const< Subclass >::value, Subclass * >
   {
      auto data = GetData();
      return DoFind< Subclass >( data, key );
   }
 
 
   template< typename ReplacementPointer >
   void Assign(
      const RegisteredFactory &key, 
      ReplacementPointer &&replacement 
   )
   {
      auto index = key.mIndex;
      auto data = GetData();
      EnsureIndex( data, index );
      auto iter = GetIterator( data, index );
      // Copy or move as appropriate:
      *iter = std::forward< ReplacementPointer >( replacement );
   }
   
 
protected:
 
 
   template< typename Function >
   void ForEach( const Function &function )
   {
      auto data = GetData();
      for( auto &pObject : data.mObject ) {
         const auto &ptr = Dereferenceable(pObject);
         if ( ptr )
            function( *ptr );
      }
   }
 
 
   template< typename Function >
   void ForEach( const Function &function ) const
   {
      auto data = GetData();
      for( auto &pObject : data.mObject ) {
         const auto &ptr = Dereferenceable(pObject);
         if ( ptr ) {
            const auto &c_ref = *ptr;
            function( c_ref );
         }
      }
   }
 
 
   template<typename Function>
   void ForCorresponding(Site &other, const Function &function,
      bool create = true)
   {
      size_t size;
      {
         auto factories = GetFactories();
         size = factories.mObject.size();
         // Release lock on factories before getting one on data -- otherwise
         // there would be a deadlock possibility inside EnsureIndex
      }
 
      // Lock two containers, carefully avoiding deadlock possibility by
      // ordering them by address in memory
      std::optional<decltype(GetData())> oOtherData;
      if (std::addressof(other) < std::addressof(*this))
         oOtherData.emplace(other.GetData());
      auto data = GetData();
      if (!oOtherData)
         oOtherData.emplace(other.GetData());
      auto &otherData = *oOtherData;
 
      // Like BuildAll but needing correspondence
      EnsureIndex(data, size - 1);
      EnsureIndex(otherData, size - 1);
 
      auto iter = GetIterator(data, 0);
      auto otherIter = GetIterator(otherData, 0);
 
      for (size_t ii = 0; ii < size; ++ii, ++iter, ++otherIter) {
         auto &pObject = *iter;
         auto &pOtherObject = *otherIter;
         // These lines might lock weak pointers, depending on template
         // arguments of the class
         auto deref = &Dereferenceable(pObject);
         auto otherDeref = &Dereferenceable(pOtherObject);
         if (!*deref && !*otherDeref)
            continue;
         else if (!*deref && create) {
            // creation on demand
            auto factories = GetFactories();
            auto &factory = factories.mObject[ii];
            pObject = factory
               ? factory(static_cast<Host&>(*this))
               : DataPointer{};
            deref = &Dereferenceable(pObject);
         }
         else if (!*otherDeref && create) {
            // creation on demand
            auto factories = GetFactories();
            auto &factory = factories.mObject[ii];
            pOtherObject = factory
               ? factory(static_cast<Host&>(other))
               : DataPointer{};
            otherDeref = &Dereferenceable(pOtherObject);
         }
 
         function(
            (*deref ? &**deref : nullptr),
            (*otherDeref ? &**otherDeref : nullptr));
      }
   }
 
 
   template< typename Function >
   ClientData *FindIf( const Function &function )
   {
      auto data = GetData();
      for( auto &pObject : data.mObject ) {
         const auto &ptr = Dereferenceable(pObject);
         if ( ptr && function ( *ptr ) )
            return &*ptr;
      }
      return nullptr;
   }
 
 
   template< typename Function >
   const ClientData *FindIf( const Function &function ) const
   {
      auto data = GetData();
      for( auto &pObject : data.mObject ) {
         const auto &ptr = Dereferenceable(pObject);
         if ( ptr ) {
            const auto &c_ref = *ptr;
            if ( function( c_ref ) )
               return &*c_ref;
         }
      }
      return nullptr;
   }
 
 
   template<typename Function>
   void EraseIf(const Function &function)
   {
      auto data = GetData();
      for (auto &pObject : data.mObject) {
         const auto &ptr = Dereferenceable(pObject);
         if (ptr) {
            auto &ref = *ptr;
            if (function(ref))
               pObject = nullptr;
         }
      }
   }
 
   void BuildAll()
   {
      // Note that we cannot call this function in the Site constructor as we
      // might wish, because we pass *this to the factories, but this is not yet
      // fully constructed as the ultimate derived class.  So delayed calls to
      // this function are needed.
      size_t size;
      {
         auto factories = GetFactories();
         size = factories.mObject.size();
         // Release lock on factories before getting one on data -- otherwise
         // there would be a deadlock possibility inside EnsureIndex
      }
      auto data = GetData();
      EnsureIndex( data, size - 1 );
      auto iter = GetIterator( data, 0 );
      for ( size_t ii = 0; ii < size; ++ii, ++iter )
         static_cast< void >( Build( data, iter, ii ) );
   }
 
 
private:
   using DataFactories =
      Lockable< std::vector< DataFactory >, RegistryLockingPolicy >;
   using DataContainer =
      Lockable<
         Copyable< std::vector< DataPointer >, ObjectCopyingPolicy >,
         ObjectLockingPolicy
      >;
 
   decltype( Dereferenceable( std::declval<DataPointer&>() ) )
   Slot( Locked<DataContainer> &data, const RegisteredFactory &key, bool create )
   {
      auto index = key.mIndex;
      EnsureIndex( data, index );
      auto iter = GetIterator( data, index );
      auto &pointer = create ? Build( data, iter, index ) : *iter;
      return Dereferenceable( pointer );
   }
 
   template< typename Subclass >
   Subclass &DoGet( Locked<DataContainer> &data, const RegisteredFactory &key )
   {
      const auto &d = Slot( data, key, true );
      if (!d)
         // Oops, a factory was deregistered too soon, or returned a null, or
         // the pointer was reassigned null
         THROW_INCONSISTENCY_EXCEPTION;
      return static_cast< Subclass& >( *d );
   }
 
   template< typename Subclass >
   Subclass *DoFind( Locked<DataContainer> &data, const RegisteredFactory &key )
   {
      const auto &d = Slot( data, key, false );
      if (!d)
         return nullptr;
      else
         return static_cast< Subclass* >( &*d );
   }
 
   static Locked< DataFactories > GetFactories()
   {
      // C++11 does not need extra thread synch for static initialization
      // Note that linker eliminates duplicates of this function
      static DataFactories factories;
 
      // But give back a scoped lock to the user of this function, in case
      // there is contention to resize the vector
      return Locked< DataFactories >{ factories };
   }
 
   Locked<DataContainer> GetData()
   {
      return Locked< DataContainer >{ mData };
   }
   
   Locked<const DataContainer> GetData() const
   {
      return Locked< const DataContainer >{ mData };
   }
   
   static void EnsureIndex( Locked<DataContainer> &data, size_t index )
   {
      if (data.mObject.size() <= index)
         data.mObject.resize(index + 1);
   }
 
   static typename DataContainer::iterator inline
   GetIterator( Locked<DataContainer> &data, size_t index )
   {
      // This function might help generalize Site with different kinds of
      // containers for pointers to ClientData that are not random-access.
      // Perhaps non-relocation of elements will be needed.
      // Perhaps another template-template parameter could vary the kind of
      // container.
      auto result = data.mObject.begin();
      std::advance( result, index );
      return result;
   }
 
   DataPointer &Build( Locked<DataContainer> &,
      typename DataContainer::iterator iter, size_t index )
   {
      // If there is no object at index, then invoke the factory, else do
      // nothing.
      // The factory may be null or may return null, in which case do nothing.
      auto &result = *iter;
      if (!Dereferenceable(result)) {
         // creation on demand
         auto factories = GetFactories();
         auto &factory = factories.mObject[index];
         result = factory
            ? factory( static_cast< Host& >( *this ) )
            : DataPointer{};
      }
      return result;
   }
 
 
   DataContainer mData;
};
 
}
 
#endif