handle.hpp

/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */

/*
 Copyright (C) 2000, 2001, 2002, 2003 RiskMap srl
 Copyright (C) 2003, 2004, 2005, 2006, 2007 StatPro Italia srl

 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/

 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 <quantlib-dev@lists.sf.net>. The license is also available online at
 <http://quantlib.org/license.shtml>.

 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 license for more details.
*/

/*! \file handle.hpp
    \brief Globally accessible relinkable pointer
*/

#ifndef quantlib_handle_hpp
#define quantlib_handle_hpp

#include <ql/patterns/observable.hpp>

namespace QuantLib {

    //! Shared handle to an observable
    /*! All copies of an instance of this class refer to the same
        observable by means of a relinkable smart pointer. When such
        pointer is relinked to another observable, the change will be
        propagated to all the copies.

        \pre Class T must inherit from Observable
    */
    template <class T>
    class Handle {
      protected:
        class Link : public Observable, public Observer {
          public:
            explicit Link(const boost::shared_ptr<T>& h,
                          bool registerAsObserver);
            void linkTo(const boost::shared_ptr<T>&,
                        bool registerAsObserver);
            bool empty() const { return !h_; }
            const boost::shared_ptr<T>& currentLink() const { return h_; }
            void update() { notifyObservers(); }
          private:
            boost::shared_ptr<T> h_;
            bool isObserver_;
        };
        boost::shared_ptr<Link> link_;
      public:
        /*! \name Constructors

            \warning <tt>registerAsObserver</tt> is left as a backdoor
                     in case the programmer cannot guarantee that the
                     object pointed to will remain alive for the whole
                     lifetime of the handle---namely, it should be set
                     to <tt>false</tt> when the passed shared pointer
                     does not own the pointee (this should only happen
                     in a controlled environment, so that the
                     programmer is aware of it). Failure to do so can
                     very likely result in a program crash.  If the
                     programmer does want the handle to register as
                     observer of such a shared pointer, it is his
                     responsibility to ensure that the handle gets
                     destroyed before the pointed object does.
        */
        //@{
        explicit Handle(const boost::shared_ptr<T>& p = boost::shared_ptr<T>(),
                        bool registerAsObserver = true)
        : link_(new Link(p,registerAsObserver)) {}
        //@}
        //! dereferencing
        const boost::shared_ptr<T>& currentLink() const;
        const boost::shared_ptr<T>& operator->() const;
        const boost::shared_ptr<T>& operator*() const;
        //! checks if the contained shared pointer points to anything
        bool empty() const;
        //! allows registration as observable
        operator boost::shared_ptr<Observable>() const;
        //! equality test
        template <class U>
        bool operator==(const Handle<U>& other) { return link_==other.link_; }
        //! disequality test
        template <class U>
        bool operator!=(const Handle<U>& other) { return link_!=other.link_; }
        //! strict weak ordering
        template <class U>
        bool operator<(const Handle<U>& other) { return link_ < other.link_; }
    };

    //! Relinkable handle to an observable
    /*! An instance of this class can be relinked so that it points to
        another observable. The change will be propagated to all
        handles that were created as copies of such instance.

        \pre Class T must inherit from Observable

        \warning see the Handle documentation for issues
                 relatives to <tt>registerAsObserver</tt>.
    */
    template <class T>
    class RelinkableHandle : public Handle<T> {
      public:
        explicit RelinkableHandle(
                       const boost::shared_ptr<T>& p = boost::shared_ptr<T>(),
                       bool registerAsObserver = true);
        explicit RelinkableHandle(
                       T* p,
                       bool registerAsObserver = true);
        void linkTo(const boost::shared_ptr<T>&,
                    bool registerAsObserver = true);
    };


    // inline definitions

    template <class T>
    inline Handle<T>::Link::Link(const boost::shared_ptr<T>& h,
                                 bool registerAsObserver)
    : isObserver_(false) {
        linkTo(h,registerAsObserver);
    }

    template <class T>
    inline void Handle<T>::Link::linkTo(const boost::shared_ptr<T>& h,
                                        bool registerAsObserver) {
        if ((h != h_) || (isObserver_ != registerAsObserver)) {
            if (h_ && isObserver_)
                unregisterWith(h_);
            h_ = h;
            isObserver_ = registerAsObserver;
            if (h_ && isObserver_)
                registerWith(h_);
            notifyObservers();
        }
    }


    template <class T>
    inline const boost::shared_ptr<T>& Handle<T>::currentLink() const {
        QL_REQUIRE(!empty(), "empty Handle cannot be dereferenced");
        return link_->currentLink();
    }

    template <class T>
    inline const boost::shared_ptr<T>& Handle<T>::operator->() const {
        QL_REQUIRE(!empty(), "empty Handle cannot be dereferenced");
        return link_->currentLink();
    }

    template <class T>
    inline const boost::shared_ptr<T>& Handle<T>::operator*() const {
        QL_REQUIRE(!empty(), "empty Handle cannot be dereferenced");
        return link_->currentLink();
    }

    template <class T>
    inline bool Handle<T>::empty() const {
        return link_->empty();
    }

    template <class T>
    inline Handle<T>::operator boost::shared_ptr<Observable>() const {
        return link_;
    }


    template <class T>
    inline RelinkableHandle<T>::RelinkableHandle(const boost::shared_ptr<T>& p,
                                                 bool registerAsObserver)
    : Handle<T>(p,registerAsObserver) {}

    template <class T>
    inline RelinkableHandle<T>::RelinkableHandle(T* p,
                                                 bool registerAsObserver)
    : Handle<T>(p,registerAsObserver) {}

    template <class T>
    inline void RelinkableHandle<T>::linkTo(const boost::shared_ptr<T>& h,
                                            bool registerAsObserver) {
        this->link_->linkTo(h,registerAsObserver);
    }

}

#endif