buffer-metadata.hpp

Go to the documentation of this file.

/*
  BUFFER-METADATA.hpp  -  internal metadata for data buffer providers

   Copyright (C)
     2011,            Hermann Vosseler <Ichthyostega@web.de>

  **Lumiera** is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License as published by the
  Free Software Foundation; either version 2 of the License, or (at your
  option) any later version. See the file COPYING for further details.

*/

#ifndef STEAM_ENGINE_BUFFR_METADATA_H
#define STEAM_ENGINE_BUFFR_METADATA_H


#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/hash-value.h"
#include "lib/util-foreach.hpp"
#include "include/logging.h"
#include "steam/streamtype.hpp"
#include "steam/engine/type-handler.hpp"
#include "steam/engine/buffer-local-tag.hpp"
#include "lib/nocopy.hpp"

#include <unordered_map>


namespace steam {
namespace engine {
  
  using lib::HashVal;
  using lib::Literal;
  using util::for_each; 
  
  namespace error = lumiera::error;
  
  namespace metadata {
    using Buff = StreamType::ImplFacade::DataBuffer;
    
    class Key;
    class Entry;
  }
  class BufferMetadata;
  
  
  
  
  enum BufferState
    { NIL,        
      FREE,       
      LOCKED,     
      EMITTED,    
      BLOCKED     
    };
  
  
  
  
  
  
  namespace { // internal constants to mark the default case
    
    inline bool
    nontrivial (TypeHandler const& toVerify)
    {
      return TypeHandler::RAW != toVerify;
    }
    
    inline bool
    nontrivial (LocalTag const& toVerify)
    {
      return LocalTag::UNKNOWN != toVerify;
    }
  }
  
  
  
  /* === Metadata Implementation === */
  
  namespace metadata {
    
    namespace { // details of hash calculation
        template<typename VAL>
        HashVal
        chainedHash(HashVal accumulatedHash, VAL changedValue)
        {
          boost::hash_combine (accumulatedHash, changedValue);
          return accumulatedHash;
        }
    }
    
    
    class Key
      {
        HashVal parent_;
        HashVal hashID_;
        
      protected:
        size_t storageSize_;
        TypeHandler instanceFunc_;
        LocalTag specifics_;
        
        
      public:
        Key (HashVal familyID, size_t storageSize)
          : parent_(familyID)
          , hashID_(chainedHash (familyID, storageSize))
          , storageSize_(storageSize)
          , instanceFunc_(TypeHandler::RAW)
          , specifics_(LocalTag::UNKNOWN)
          { }
        
        // standard copy operations permitted
        
        Key (Key const& parent, size_t differingStorageSize) 
          : parent_(parent.hashID_)
          , hashID_(chainedHash (parent_, differingStorageSize))
          , storageSize_(differingStorageSize)  // differing from parent
          , instanceFunc_(parent.instanceFunc_)
          , specifics_(parent.specifics_)
          { }
        
        
        Key (Key const& parent, TypeHandler const& differingTypeHandlerFunctions) 
          : parent_(parent.hashID_)
          , hashID_(chainedHash (parent_, differingTypeHandlerFunctions))
          , storageSize_(parent.storageSize_)
          , instanceFunc_(differingTypeHandlerFunctions)  // differing from parent
          , specifics_(parent.specifics_)
          { }
        
        
        Key (Key const& parent, LocalTag anotherTypeSpecificInternalTag) 
          : parent_(parent.hashID_)
          , hashID_(chainedHash (parent_, anotherTypeSpecificInternalTag))
          , storageSize_(parent.storageSize_)
          , instanceFunc_(parent.instanceFunc_)
          , specifics_(anotherTypeSpecificInternalTag)  // differing from parent
          { }
        
        
        static Key
        forEntry (Key const& parent, const Buff* bufferAddr, LocalTag const& localTag =LocalTag::UNKNOWN)
          {
            Key newKey{parent};  // copy of parent as baseline
            if (nontrivial(localTag))
              {
                if (nontrivial(parent.specifics_))
                  throw error::Logic{"Implementation defined local key should not be overridden. "
                                     "Underlying buffer type already defines a nontrivial LocalTag"};
                newKey.parent_ = HashVal(parent);
                newKey.hashID_ = chainedHash(newKey.hashID_, localTag);
                newKey.specifics_ = localTag;
              }
            if (bufferAddr)
              {
                newKey.parent_ = HashVal(parent);
                newKey.hashID_ = chainedHash(newKey.hashID_, bufferAddr);
              }
            return newKey; 
          }
        
        void
        useTypeHandlerFrom (Key const& ref)
          {
            if (nontrivial(this->instanceFunc_))
              throw error::Logic ("unable to supersede an already attached TypeHandler"
                                 , LERR_(LIFECYCLE));
            instanceFunc_ = ref.instanceFunc_;
          }
        
        
        LocalTag const& localTag() const { return specifics_;}
        size_t storageSize() const { return storageSize_; }
        
        HashVal parentKey()  const { return parent_;}
        operator HashVal()   const { return hashID_;}
      };
    
    
    class Entry
      : public Key
      {
        BufferState state_;
        Buff*       buffer_;
        
      protected:
        Entry (Key const& parent
              ,Buff* bufferPtr =nullptr
              ,LocalTag const& specialTag =LocalTag::UNKNOWN
              )
          : Key{Key::forEntry (parent, bufferPtr, specialTag)}
          , state_{bufferPtr? LOCKED:NIL}
          , buffer_{bufferPtr}
          { }
        
        friend class engine::BufferMetadata;
        
        // standard copy operations permitted
        
      public:
        bool
        isLocked()  const
          {
            ASSERT (!buffer_ or (NIL != state_ and FREE != state_));
            return bool(buffer_);
          }
        
        bool
        isTypeKey()  const
          {
            return NIL == state_ and not buffer_;
          }
        
        
        BufferState
        state()  const
          {
            return state_;
          }
        
        Buff*
        access()
          {
            __must_not_be_NIL();
            __must_not_be_FREE();
            
            ENSURE (buffer_);
            return buffer_;
          }
        
        Entry&
        mark (BufferState newState)
          {
            __must_not_be_NIL();
            
            if (  (state_ == FREE    and newState == LOCKED)
               or (state_ == LOCKED  and newState == EMITTED)
               or (state_ == LOCKED  and newState == BLOCKED)
               or (state_ == LOCKED  and newState == FREE)
               or (state_ == EMITTED and newState == BLOCKED)
               or (state_ == EMITTED and newState == FREE)
               or (state_ == BLOCKED and newState == FREE))
              {
                // allowed transition
                if (newState == FREE)
                  invokeEmbeddedDtor_and_clear();
                if (newState == LOCKED)
                  invokeEmbeddedCtor();
                state_ = newState;
                return *this;
              }
            
            throw error::Fatal ("Invalid buffer state transition.");
          }
        
        Entry&
        lock (Buff* newBuffer)
          {
            __must_be_FREE();
            buffer_ = newBuffer;
            return mark (LOCKED);
          }
        
        Entry&
        invalidate (bool invokeDtor =true)
          {
            if (buffer_ and invokeDtor)
              invokeEmbeddedDtor_and_clear();
            buffer_ = nullptr;
            state_ = FREE;
            return *this;
          }
        
        
      protected:
        void
        invokeEmbeddedCtor()
          {
            __buffer_required();
            if (nontrivial (instanceFunc_))
              instanceFunc_.createAttached (buffer_);
          }
        
        void
        invokeEmbeddedDtor_and_clear()
          {
            __buffer_required();
            if (nontrivial (instanceFunc_))
              instanceFunc_.destroyAttached (buffer_);
            buffer_ = 0;
          }
        
      private:
        void
        __must_not_be_NIL()  const
          {
            if (NIL == state_)
              throw error::Fatal ("Buffer metadata entry with state==NIL encountered."
                                  "State transition logic broken (programming error)"
                                 , LERR_(LIFECYCLE));
          }
        
        void
        __must_not_be_FREE()  const
          {
            if (FREE == state_)
                throw error::Logic ("Buffer is inaccessible (marked as free). "
                                    "Need a new buffer pointer in order to lock an entry. "
                                    "You should invoke markLocked(buffer) prior to access."
                                   , LERR_(LIFECYCLE));
          }
        
        void
        __must_be_FREE()  const
          {
            if (FREE != state_)
                throw error::Logic ("Buffer already in use"
                                   , LERR_(LIFECYCLE));
            REQUIRE (!buffer_, "Buffer marked as free, "
                               "but buffer pointer is set.");
          }
        
        void
        __buffer_required()  const
          {
            if (!buffer_)
                throw error::Fatal ("Need concrete buffer for any further operations");
          }
      };
    
    
      
    class Table
      {
        typedef std::unordered_map<HashVal,Entry> MetadataStore;
        
        MetadataStore entries_;

      public:
       ~Table() { verify_all_buffers_freed(); }
        
        Entry*
        fetch (HashVal hashID)
          {
            MetadataStore::iterator pos = entries_.find (hashID);
            if (pos != entries_.end())
              return &(pos->second);
            else
              return NULL;
          }
        
        const Entry*
        fetch (HashVal hashID)  const
          {
            MetadataStore::const_iterator pos = entries_.find (hashID);
            if (pos != entries_.end())
              return &(pos->second);
            else
              return NULL;
          }
        
        Entry&
        store (Entry const& newEntry)
          {
            REQUIRE (!fetch (newEntry), "duplicate buffer metadata entry");
            MetadataStore::iterator pos = entries_.emplace (HashVal(newEntry), newEntry)
                                                  .first;
            
            ENSURE (pos != entries_.end());
            return pos->second;
          }
        
        void
        remove (HashVal hashID)
          {
            uint cnt = entries_.erase (hashID);
            ENSURE (cnt, "entry to remove didn't exist");
          }
        
      private:
        void
        verify_all_buffers_freed()
          try
            {
              for_each (entries_, verify_is_free);
            }
          ERROR_LOG_AND_IGNORE (engine,"Shutdown of BufferProvider metadata store")
          
        static void
        verify_is_free (std::pair<HashVal, Entry> const& e)
          {
            WARN_IF (e.second.isLocked(), engine,
                     "Buffer still in use while shutting down BufferProvider? ");
          }
      };
    
  }//namespace metadata
  
  
  
  
  
  /* ===== Buffer Metadata Frontend ===== */
  
  class BufferMetadata
    : util::NonCopyable
    {
      Literal id_;
      HashVal family_;
      
      metadata::Table table_;
      
    public:
      using Key   = metadata::Key;
      using Entry = metadata::Entry;
      
      BufferMetadata (Literal implementationID)
        : id_(implementationID)
        , family_(hash_value(id_))
        { }
      
      Key
      key ( size_t storageSize
          , TypeHandler instanceFunc =TypeHandler::RAW
          , LocalTag specifics       =LocalTag::UNKNOWN)
        {
          REQUIRE (storageSize);
          Key typeKey = trackKey (family_, storageSize);
          
          if (nontrivial(instanceFunc))
              typeKey = trackKey (typeKey, instanceFunc);
          
          if (nontrivial(specifics))
              typeKey = trackKey (typeKey, specifics);
          
          return typeKey;
        }
      
      Key
      key (Key const& parentKey, TypeHandler const& instanceFunc)
        {
          return trackKey (parentKey, instanceFunc);
        }
      
      Key
      key (Key const& parentKey, LocalTag specifics)
        {
          return trackKey (parentKey, specifics);
        }
      
      Key const&
      key (Key const& parentKey, metadata::Buff* concreteBuffer, LocalTag const& specifics =LocalTag::UNKNOWN)
        {
          Key derivedKey = Key::forEntry (parentKey, concreteBuffer, specifics);
          Entry* existing = table_.fetch (derivedKey);
          
          return existing? *existing
                         : markLocked (parentKey,concreteBuffer,specifics);
        }
      
      Entry&
      lock (Key const& parentKey
           ,metadata::Buff* concreteBuffer
           ,LocalTag const& specifics =LocalTag::UNKNOWN
           ,bool onlyNew =false)
        {
          if (!concreteBuffer)
            throw error::Invalid{"Attempt to lock a slot for a NULL buffer"
                                , LERR_(BOTTOM_VALUE)};
          
          Entry newEntry{parentKey, concreteBuffer, specifics};
          Entry* existing = table_.fetch (newEntry);
          
          if (existing and onlyNew)
            throw error::Logic{"Attempt to lock a slot for a new buffer, "
                               "while actually the old buffer is still locked"
                              , LERR_(LIFECYCLE)};
          if (existing and existing->isLocked())
            throw error::Logic{"Attempt to re-lock a buffer still in use"
                              , LERR_(LIFECYCLE)};
          
          if (not existing)
            return store_as_locked (newEntry); // actual creation
          else
            return existing->lock (concreteBuffer);
        }
      
      Entry&
      get (HashVal hashID)
        {
          Entry* entry = table_.fetch (hashID);
          if (!entry)
            throw error::Invalid ("Attempt to access an unknown buffer metadata entry");
          
          return *entry;
        }
      
      bool
      isKnown (HashVal key)  const
        {
          return bool(table_.fetch (key));
        }
      
      bool
      isLocked (HashVal key)  const
        {
          const Entry* entry = table_.fetch (key);
          return entry
             and entry->isLocked();
        }
      
      
      
      /* == memory management operations == */
      
      Entry&
      markLocked (Key const& parentKey, metadata::Buff* buffer, LocalTag const& specifics =LocalTag::UNKNOWN)
        {
          if (!buffer)
            throw error::Fatal{"Attempt to lock for a NULL buffer. Allocation floundered?"
                              , LERR_(BOTTOM_VALUE)};
          
          return this->lock (parentKey, buffer, specifics, true); // force creation of a new entry
        }
      
      void
      release (HashVal key)
        {
          Entry* entry = table_.fetch (key);
          if (!entry) return;
          
          ASSERT (entry and (key == HashVal(*entry)));
          release (*entry);
        }
      
      void
      release (Entry const& entry)
        {
          if (FREE != entry.state())
            throw error::Logic{"Attempt to release a buffer still in use"
                              , LERR_(LIFECYCLE)};
          
          table_.remove (HashVal(entry));
        }
      
      
      
    private: 
            
      template<typename PAR, typename DEF>
      Key
      trackKey (PAR parent, DEF specialisation)
        {
          Key newKey{parent, specialisation};
          maybeStore (newKey);
          return newKey;
        }
      
      void
      maybeStore (Key const& key)
        {
          if (isKnown (key)) return;
          table_.store (Entry{key, nullptr});
        }
      
      Entry&
      store_as_locked (Entry const& metadata)
        {
          REQUIRE (metadata.isLocked());
          Entry& newEntry = table_.store (metadata);
          try
            {
              newEntry.invokeEmbeddedCtor();
              ENSURE (LOCKED == newEntry.state());
              ENSURE (newEntry.access());
            }
          catch(...)
            {
              newEntry.mark(FREE);
              throw;
            }
          return newEntry;
        }
    };
  
  
  
  
}} // namespace steam::engine
#endif /*STEAM_ENGINE_BUFFR_METADATA_H*/