mobject-ref.hpp

Go to the documentation of this file.

/*
  MOBJECT-REF.hpp  -  active external reference to an MObject within the Session

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

#include "lib/handle.hpp"
#include "steam/mobject/placement.hpp"
#include "steam/mobject/placement-ref.hpp"
#include "steam/mobject/session/session-service-mutate.hpp"

#include <string>



namespace lumiera {
namespace error {
  LUMIERA_ERROR_DECLARE (BOTTOM_MOBJECTREF);  
}}

namespace steam {
namespace mobject {
  
  namespace error = lumiera::error;
  
  class MObject;
  
  
  template<class MO =MObject>
  class MORef
    : public lib::Handle<MO>
    {
      typedef lib::Handle<MO> _Handle;
      typedef PlacementMO::Id<MO> _Id;

      
      PlacementRef<MO> pRef_;
      using _Handle::smPtr_;
      
      
      
    public:
      
      MO*
      operator-> ()  const
        {
          if (!smPtr_)
            throw error::State("Lifecycle error: MObject ref not activated"
                              , LERR_(BOTTOM_MOBJECTREF));
          
          ENSURE (INSTANCEOF (MO, smPtr_.get()));
          return smPtr_.operator-> ();
        }
      
      
      Placement<MO>& getPlacement()  const
        {
          if (!isValid())
            throw error::State("Accessing inactive MObject ref"
                              , LERR_(BOTTOM_MOBJECTREF));
          
          ENSURE (INSTANCEOF (MO, smPtr_.get()));
          return *pRef_;
        }
      
      
      PlacementRef<MO> const&
      getRef() const
        {
          return pRef_;
        }
                            
      operator _Id const&()  const
        {
          return pRef_;
        }
      
      
      
      lib::time::Time
      getStartTime()
        {
          return pRef_.resolve().time;
        }
      
      
      template<class MOX>
      MORef<MOX>
      attach (Placement<MOX> const& newPlacement)
        {
          if (!isValid())
            throw error::State("Attempt to attach a child to an inactive MObject ref"
                              , LERR_(BOTTOM_MOBJECTREF));
          MORef<MOX> newInstance;
          PlacementMO::ID thisScope = pRef_;
          return newInstance.activate (
                    session::SessionServiceMutate::attach_toModel (newPlacement, thisScope));
        }
      
      
      void
      purge ()
        {
          if (isValid())
            session::SessionServiceMutate::detach_and_clear (pRef_);
          
          ENSURE (!isValid());
        }
      
      
      
      /* === Lifecycle === */
      
      MORef&
      activate (Placement<MO> const& placement)
        {
          ASSERT (placement.isValid());
          pRef_ = placement;                       // STRONG exception safe
          placement.extendOwnershipTo(smPtr_);     // never throws
          return *this;
        }
      
      template<typename REF>
      MORef&
      activate (REF const& pRefID)
        {
          PlacementRef<MO> newRef (pRefID);
          
          if (isValid() && pRef_ == newRef )
            return *this;                // self assignment detected
          else
            return activate (*newRef); // STRONG exception safe
        }
      
      MORef&
      activate (MORef const& oRef)
        {
          return activate (oRef.getPlacement());
        }
      
      template<typename MOX>
      MORef&
      activate (MORef<MOX> const& oRef)
        {
          return activate (oRef.getPlacement().getID());
        }
      
      template<typename MOX>
      MORef&
      operator= (MORef<MOX> const& oRef)
        {
          return activate (oRef);
        }
      
      
      
      
      /* == diagnostics == */
      bool
      isValid()  const
        {
          return _Handle::isValid()
              && pRef_.isValid();
        }
      
      size_t
      use_count()  const
        {
          return isValid()? pRef_.use_count() : 0;
        }
      
      template<class MOX>
      bool
      isCompatible()  const
        {
          return pRef_
              && (*pRef_).template isCompatible<MOX>();
        }
      
      operator string()   const                      
        {
          return isValid()? string(getPlacement())
                          : "MRef-NIL";
        }
      
      
      
      
      /* == equality comparisons == */
      
      template<class MOX>
      bool
      operator== (MORef<MOX> const& oRef)  const
        {
          return isValid()
              && oRef == this->pRef_;
        }
      
      template<class MOX>
      bool
      operator!= (MORef<MOX> const& oRef)  const
        {
          return not isValid()
              or oRef != this->pRef_;
        }
      
      template<class MOX>
      friend bool
      operator== (MORef const& oRef, PlacementRef<MOX> const& pRef)
        {
          return oRef.isValid()
             and oRef.pRef_ == pRef;
        }
      
      template<class MOX>
      friend bool
      operator!= (MORef const& oRef, PlacementRef<MOX> const& pRef)
        {
          return not oRef.isValid()
              or oRef.pRef_ != pRef;
        }
      
      template<class MOX>
      friend bool
      operator== (PlacementRef<MOX> const& pRef, MORef const& oRef)
        {
          return oRef.isValid()
             and pRef == oRef.pRef_;
        }
      
      template<class MOX>
      friend bool
      operator!= (PlacementRef<MOX> const& pRef, MORef const& oRef)
        {
          return not oRef.isValid()
              or pRef != oRef.pRef_;
        }
      
      bool
      operator== (PlacementMO::ID const& pID)  const
        {
          return isValid()
             and PlacementMO::ID (pRef_) == pID;
        }
      
      bool
      operator!= (PlacementMO::ID const& pID)  const
        {
          return not isValid()
              or PlacementMO::ID (pRef_) != pID;
        }
      
    };
  
  
  typedef MORef<MObject> MObjectRef;
  
  
  /* === convenience shortcuts === */
  
  template<class MOX, class MOY>
  inline bool
  isSharedPointee (MORef<MOX> const& ref1, MORef<MOY> const& ref2)
  {
    return ref1.isValid() && ref2.isValid()
        && isSharedPointee (ref1.getPlacement(), ref2.getPlacement());
  }
  
  template<class MOX, class MOY>
  inline bool
  isEquivalentPlacement (MORef<MOX> const& ref1, MORef<MOY> const& ref2)
  {
    return ref1.isValid() && ref2.isValid()
        && isSameDef (ref1.getPlacement(), ref2.getPlacement());
  }
  
  
}} // namespace steam::mobject
#endif