advice.hpp

Go to the documentation of this file.

/*
  ADVICE.hpp  -  generic loosely coupled interaction guided by symbolic pattern

  Copyright (C)         Lumiera.org
    2010,               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 LUMIERA_ADVICE_H
#define LUMIERA_ADVICE_H


#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/null-value.hpp"
#include "lib/symbol.hpp"
#include "lib/util.hpp"

#include "common/advice/binding.hpp"


namespace lumiera{
namespace advice {
  
  using lib::Literal;
  using util::isSameObject;
  
  
  class PointOfAdvice
    {
      Binding::Matcher pattern_;
      PointOfAdvice* resolution_;
      
    protected:
      void setBindingPattern (Binding const& binding)
        {
          pattern_ = binding.buildMatcher();
        }
      
    public:
      explicit
      PointOfAdvice (Binding const& binding)
        : pattern_(binding.buildMatcher())
        , resolution_(nullptr)
        { }
      
      // using default copy/assignment
      
      
      
      /* == Adapter interface for use within the Index == */
      
      void
      setSolution (PointOfAdvice* solution =0)
        {
          resolution_ = solution;
        }
        
      const PointOfAdvice*
      getSolution ()  const
        {
          return resolution_;
        }
      
      Binding::Matcher
      getMatcher ()  const
        {
          return pattern_;
        }
      
      friend HashVal
      hash_value (PointOfAdvice const& entry)
      {
        return hash_value (entry.pattern_);
      }
    };
  
  
  
  
  class AdviceLink
    : public PointOfAdvice
    {
    protected:
      void publishProvision (PointOfAdvice*);
      void discardSolutions ();
      void publishRequestBindingChange(HashVal);
      
      void registerRequest();
      void deregisterRequest();
      
      static void* getBuffer(size_t);
      static void  releaseBuffer (void*, size_t);
      
      typedef void (DeleterFunc)(void*);
      static void manageAdviceData (PointOfAdvice*, DeleterFunc*);
      
    public:
      explicit
      AdviceLink (Binding const& binding)
        : PointOfAdvice(binding)
        { }
      
      // using default copy/assignment
    };
  
  
  
  
  
  template<class AD>
  class Provision
    : protected AdviceLink
    {
      
      
      /* == policy definitions == */    
      
      void deregister() { /* NOP */ }
      
      
    public:
      explicit
      Provision (Literal bindingSpec =0)
        : AdviceLink (Binding(bindingSpec).addTypeGuard<AD>())
        { }
      
     ~Provision()
        {
          this->deregister();
        }
      
      Provision (Provision const& o)
        : AdviceLink(o)
        {
          setSolution ( NULL );
        }
      
      Provision&
      operator= (Provision const& o)
        {
          if (!isSameObject(*this, o))
            {
              AdviceLink::operator= (o);
              setSolution ( NULL );
            }
          return *this;
        }
      
      
      void setAdvice (AD const& pieceOfAdvice)
        {
          publishProvision(
            storeCopy (pieceOfAdvice));
        }
      
      void retractAdvice()
        {
          discardSolutions();
        }
      
      bool
      isGiven()  const
        {
          return bool{this->getSolution()};
        }
      
      void
      defineBinding (Literal topic)
        {
          setBindingPattern (Binding(topic).addTypeGuard<AD>());
          maybe_rePublish();
        }
      
    private:
      PointOfAdvice* storeCopy (AD const& advice_given);
      static void releaseAdviceData (void*);
      void maybe_rePublish ();
    };
  
  
  template<class AD>
  class ActiveProvision
    : public PointOfAdvice
    , util::NonCopyable
    {
      AD theAdvice_;
      
    public:
      AD const&
      getAdvice()  const
        {
          return theAdvice_;
        }
      
    protected:
      ActiveProvision (PointOfAdvice const& refPoint, AD const& advice_given)
        : PointOfAdvice(refPoint)
        , theAdvice_(advice_given)
        {
          this->setSolution (this); // not used currently (5/10)
        }
      
      friend class Provision<AD>;
    };
  
  
  /*  ==== memory management for Provision data ===== */
  
  template<class AD>
  inline PointOfAdvice*
  Provision<AD>::storeCopy (AD const& advice_given)
  {
    typedef ActiveProvision<AD> Holder;
    void* storage = getBuffer(sizeof(Holder));
    try
      {
        Holder* storedProvision = new(storage) Holder (*this, advice_given);
        manageAdviceData (storedProvision, &releaseAdviceData);
        return storedProvision;
      }
    catch(...)
      {
        Literal errID = lumiera_error();
        releaseBuffer (storage, sizeof(Holder));
        throw lumiera::error::Fatal ("Failure to store advice data", errID);
      }
  }
  
  
  template<class AD>
  inline void
  Provision<AD>::releaseAdviceData (void* entry)
  {
    typedef ActiveProvision<AD> Holder;
    if (entry)
      {
        Holder* obj = static_cast<Holder*> (entry);
        obj->~Holder();
        releaseBuffer (entry, sizeof(Holder));
      }
  }
  
  
  template<class AD>
  inline void
  Provision<AD>::maybe_rePublish ()
  {
    typedef const ActiveProvision<AD> AdviceProvision;
    AdviceProvision* solution = static_cast<AdviceProvision*> (getSolution());
    
    if (solution)    // create copy of the data holder, using the new binding
      publishProvision(
        storeCopy (solution->getAdvice()));
  }
  
  
  
  
  
  
  
  template<class AD>
  class Request
    : protected AdviceLink
    {
      typedef const ActiveProvision<AD> AdviceProvision;
      
      
      /* == policy definitions == */    
      
      AD const&
      handleMissingSolution()  const  
        {
          return lib::NullValue<AD>::get();
        }
      
      
    public:
      explicit
      Request (Literal bindingSpec =0)
        : AdviceLink (Binding(bindingSpec).addTypeGuard<AD>())
        {
          registerRequest();
        }
      
     ~Request()
        {
          deregisterRequest();
        }
      
      // copying Requests is allowed, using default
      
      
      AD const&
      getAdvice()  const
        {
          AdviceProvision* solution = static_cast<AdviceProvision*> (this->getSolution());
          if (!solution)
            return this->handleMissingSolution();
          else
            return solution->getAdvice();
        }
      
      
      bool
      isMatched()  const
        {
          return bool{this->getSolution()};
        }
      
      
      void
      defineBinding (Literal topic)
        {
          HashVal previous_bindingKey (hash_value(*this));
          setBindingPattern (Binding(topic).addTypeGuard<AD>());
          publishRequestBindingChange (previous_bindingKey);
        }
    };
  
  
  
  
  
}} // namespace lumiera::advice
#endif