buffer-metadata.hpp

Go to the documentation of this file.

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

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

  This program 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.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#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/engine/type-handler.hpp"
#include "steam/engine/buffer-local-key.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 {
    class Key;
    class Entry;
  }
  class BufferMetadata;
  
  
  
  
  enum BufferState
    { NIL,        
      FREE,       
      LOCKED,     
      EMITTED,    
      BLOCKED     
    };
  
  
  
  
  
  
  namespace { // internal constants to mark the default case
    
    const LocalKey UNSPECIFIC;
    const TypeHandler RAW_BUFFER;
    
    inline bool
    nontrivial (TypeHandler const& toVerify)
    {
      return RAW_BUFFER != toVerify;
    }
    
    inline bool
    nontrivial (LocalKey const& toVerify)
    {
      return UNSPECIFIC != 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_;
        LocalKey specifics_;
        
        
      public:
        Key (HashVal familyID, size_t storageSize)
          : parent_(familyID)
          , hashID_(chainedHash (familyID, storageSize))
          , storageSize_(storageSize)
          , instanceFunc_(RAW_BUFFER)
          , specifics_(UNSPECIFIC)
          { }
        
        // 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, LocalKey anotherTypeSpecificInternalID) 
          : parent_(parent.hashID_)
          , hashID_(chainedHash (parent_, anotherTypeSpecificInternalID))
          , storageSize_(parent.storageSize_)
          , instanceFunc_(parent.instanceFunc_)
          , specifics_(anotherTypeSpecificInternalID)  // differing from parent
          { }
        
        
        static Key
        forEntry (Key const& parent, const void* bufferAddr, LocalKey const& implID =UNSPECIFIC)
          {
            Key newKey(parent);
            if (bufferAddr)
              {
                newKey.parent_ = HashVal(parent);
                newKey.hashID_ = chainedHash(parent, bufferAddr);
                if (nontrivial(implID))
                  {
                    REQUIRE (!newKey.specifics_.isDefined(),
                             "Implementation defined local key should not be overridden. "
                             "Underlying buffer type already defines a nontrivial LocalKey");
                    newKey.specifics_ = implID;
              }   }
            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_;
          }
        
        
        LocalKey const& localKey() 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_;
        void*       buffer_;
        
      protected:
        Entry (Key const& parent, void* bufferPtr =0, LocalKey const& implID =UNSPECIFIC)
          : Key (Key::forEntry (parent, bufferPtr, implID))
          , state_(bufferPtr? LOCKED:NIL)
          , buffer_(bufferPtr)
          { }
        
        friend class engine::BufferMetadata;
        
        // standard copy operations permitted
        
      public:
        bool
        isLocked()  const
          {
            ASSERT (!buffer_ || (NIL != state_ && FREE != state_));
            return bool(buffer_);
          }
        
        bool
        isTypeKey()  const
          {
            return NIL == state_ && !buffer_;
          }
        
        
        BufferState
        state()  const
          {
            return state_;
          }
        
        void*
        access()
          {
            __must_not_be_NIL();
            __must_not_be_FREE();
            
            ENSURE (buffer_);
            return buffer_;
          }
        
        Entry&
        mark (BufferState newState)
          {
            __must_not_be_NIL();
            
            if ( (state_ == FREE    && newState == LOCKED)
               ||(state_ == LOCKED  && newState == EMITTED)
               ||(state_ == LOCKED  && newState == BLOCKED)
               ||(state_ == LOCKED  && newState == FREE)
               ||(state_ == EMITTED && newState == BLOCKED)
               ||(state_ == EMITTED && newState == FREE)
               ||(state_ == BLOCKED && 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 (void* newBuffer)
          {
            __must_be_FREE();
            buffer_ = newBuffer;
            return mark (LOCKED);
          }
        
        Entry&
        invalidate (bool invokeDtor =true)
          {
            if (buffer_ && invokeDtor)
              invokeEmbeddedDtor_and_clear();
            buffer_ = 0;
            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)
          {
            using std::make_pair;
            REQUIRE (!fetch (newEntry), "duplicate buffer metadata entry");
            MetadataStore::iterator pos = entries_.insert (make_pair (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:
      typedef metadata::Key Key;
      typedef metadata::Entry Entry;
      
      BufferMetadata (Literal implementationID)
        : id_(implementationID)
        , family_(hash_value(id_))
        { }
      
      Key
      key ( size_t storageSize
          , TypeHandler instanceFunc =RAW_BUFFER
          , LocalKey specifics       =UNSPECIFIC)
        {
          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, LocalKey specifics)
        {
          return trackKey (parentKey, specifics);
        }
      
      Key const&
      key (Key const& parentKey, void* concreteBuffer, LocalKey const& implID =UNSPECIFIC)
        {
          Key derivedKey = Key::forEntry (parentKey, concreteBuffer);
          Entry* existing = table_.fetch (derivedKey);
          
          return existing? *existing
                         : markLocked (parentKey,concreteBuffer,implID);
        }
      
      Entry&
      lock (Key const& parentKey
           ,void* concreteBuffer
           ,LocalKey const& implID =UNSPECIFIC
           ,bool onlyNew =false)
        {
          if (!concreteBuffer)
            throw error::Invalid{"Attempt to lock a slot for a NULL buffer"
                                , LERR_(BOTTOM_VALUE)};
          
          Entry newEntry(parentKey, concreteBuffer, implID);
          Entry* existing = table_.fetch (newEntry);
          
          if (existing && 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 && existing->isLocked())
            throw error::Logic{"Attempt to re-lock a buffer still in use"
                              , LERR_(LIFECYCLE)};
          
          if (!existing)
            return store_and_lock (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
              && entry->isLocked();
        }
      
      
      
      /* == memory management operations == */
      
      Entry&
      markLocked (Key const& parentKey, void* buffer, LocalKey const& implID =UNSPECIFIC)
        {
          if (!buffer)
            throw error::Fatal{"Attempt to lock for a NULL buffer. Allocation floundered?"
                              , LERR_(BOTTOM_VALUE)};
          
          return this->lock(parentKey, buffer, implID, true); // force creation of a new entry
        }
      
      void
      release (HashVal key)
        {
          Entry* entry = table_.fetch (key);
          if (!entry) return;
          
          ASSERT (entry && (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, NULL));
        }
      
      Entry&
      store_and_lock (Entry const& metadata)
        {
          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