rcu.h

Go to the documentation of this file.

/*
    Copyright (C) 2000-2007 Paul Davis

    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 __pbd_rcu_h__
#define __pbd_rcu_h__

#include "boost/shared_ptr.hpp"
#include "glibmm/threads.h"

#include <list>

#include "pbd/libpbd_visibility.h"

template<class T>
class /*LIBPBD_API*/ RCUManager
{
  public:

        RCUManager (T* new_rcu_value) {
                x.m_rcu_value = new boost::shared_ptr<T> (new_rcu_value);
        }

        virtual ~RCUManager() { delete x.m_rcu_value; }

        boost::shared_ptr<T> reader () const { return *((boost::shared_ptr<T> *) g_atomic_pointer_get (&x.gptr)); }

        /* this is an abstract base class - how these are implemented depends on the assumptions
           that one can make about the users of the RCUManager. See SerializedRCUManager below
           for one implementation.
        */

        virtual boost::shared_ptr<T> write_copy () = 0;
        virtual bool update (boost::shared_ptr<T> new_value) = 0;

  protected:
        /* ordinarily this would simply be a declaration of a ptr to a shared_ptr<T>. however, the atomic
           operations that we are using (from glib) have sufficiently strict typing that it proved hard
           to get them to accept even a cast value of the ptr-to-shared-ptr() as the argument to get()
           and comp_and_exchange(). Consequently, we play a litle trick here that relies on the fact
           that sizeof(A*) == sizeof(B*) no matter what the types of A and B are. for most purposes
           we will use x.m_rcu_value, but when we need to use an atomic op, we use x.gptr. Both expressions
           evaluate to the same address.
        */

        union {
            boost::shared_ptr<T>* m_rcu_value;
            mutable volatile gpointer gptr;
        } x;
};


template<class T>
class /*LIBPBD_API*/ SerializedRCUManager : public RCUManager<T>
{
public:

        SerializedRCUManager(T* new_rcu_value)
                : RCUManager<T>(new_rcu_value)
        {
        }

        boost::shared_ptr<T> write_copy ()
        {
                m_lock.lock();

                // clean out any dead wood

                typename std::list<boost::shared_ptr<T> >::iterator i;

                for (i = m_dead_wood.begin(); i != m_dead_wood.end(); ) {
                        if ((*i).unique()) {
                                i = m_dead_wood.erase (i);
                        } else {
                                ++i;
                        }
                }

                /* store the current so that we can do compare and exchange
                   when someone calls update(). Notice that we hold
                   a lock, so this store of m_rcu_value is atomic.
                */

                current_write_old = RCUManager<T>::x.m_rcu_value;

                boost::shared_ptr<T> new_copy (new T(**current_write_old));

                return new_copy;

                /* notice that the write lock is still held: update() MUST
                   be called or we will cause another writer to stall.
                */
        }

        bool update (boost::shared_ptr<T> new_value)
        {
                /* we still hold the write lock - other writers are locked out */

                boost::shared_ptr<T>* new_spp = new boost::shared_ptr<T> (new_value);

                /* update, by atomic compare&swap. Only succeeds if the old
                   value has not been changed.

                   XXX but how could it? we hold the freakin' lock!
                */

                bool ret = g_atomic_pointer_compare_and_exchange (&RCUManager<T>::x.gptr,
                                                                  (gpointer) current_write_old,
                                                                  (gpointer) new_spp);

                if (ret) {

                        // successful update : put the old value into dead_wood,

                        m_dead_wood.push_back (*current_write_old);

                        // now delete it - this gets rid of the shared_ptr<T> but
                        // because dead_wood contains another shared_ptr<T> that
                        // references the same T, the underlying object lives on

                        delete current_write_old;
                }

                /* unlock, allowing other writers to proceed */

                m_lock.unlock();

                return ret;
        }

        void flush () {
                Glib::Threads::Mutex::Lock lm (m_lock);
                m_dead_wood.clear ();
        }

private:
        Glib::Threads::Mutex                      m_lock;
        boost::shared_ptr<T>*            current_write_old;
        std::list<boost::shared_ptr<T> > m_dead_wood;
};

template<class T>
class /*LIBPBD_API*/ RCUWriter
{
public:

        RCUWriter(RCUManager<T>& manager)
                : m_manager(manager) {
                m_copy = m_manager.write_copy();
        }

        ~RCUWriter() {
                if (m_copy.unique()) {
                        /* As intended, our copy is the only reference
                           to the object pointed to by m_copy. Update
                           the manager with the (presumed) modified
                           version.
                        */
                        m_manager.update(m_copy);
                } else {
                        /* This means that some other object is using our copy
                           of the object. This can only happen if the scope in
                           which this RCUWriter exists passed it to a function
                           that created a persistent reference to it, since the
                           copy was private to this particular RCUWriter. Doing
                           so will not actually break anything but it violates
                           the design intention here and so we do not bother to
                           update the manager's copy.

                           XXX should we print a warning about this?
                        */
                }

        }

        boost::shared_ptr<T> get_copy() const { return m_copy; }

private:
        RCUManager<T>& m_manager;
        boost::shared_ptr<T> m_copy;
};

#endif /* __pbd_rcu_h__ */