Boost :

Gtalbot_at_[hidden]

--
George T. Talbot
gtalbot_at_[hidden]
/** \file           atomic_shared.h
 *
 *  \author         George T. Talbot
 *  \author         Peter Dimov
 *
 *  \brief          This file defines a template class that can wrap
 *                  boost::shared_ptr and provide thread-safe atomic
 *                  get/set operations on them.
 *
 *  (C) Copyright Locus Pharmaceuticals, Inc., Peter Dimov 2006.
 *
 *  Distributed under the Boost Software License, Version 1.0. (See
 *  accompanying file LICENSE_1_0.txt or copy at
 *  http://www.boost.org/LICENSE_1_0.txt)
 */
#ifndef ATOMIC_SHARED_H
#define ATOMIC_SHARED_H
#include <boost/shared_ptr.hpp>
#include <boost/pointer_cast.hpp>
#include <boost/thread/recursive_mutex.hpp>
/** atomic_shared<T> wraps boost::shared_ptr<T> with a mutex and a very
 *  restricted set of operations so that a large composite data
structure
 *  may be accessed by multiple threads with a minimum of locking
contention.
 *
 *  Threads working on a large composite data structure create their own
 *  private boost::shared_ptr<T> around their own new nodes and then use
 *  compare_and_set() to place their new nodes in the composite data
 *  structure.
 *
 *  Threads that are viewing the composite data structure may call get()
to
 *  get a private copy of the pointer so they can do some work with it.
The
 *  intended idiom for modifications to nodes is like so:
 *
 *  \code
 *
 *      atomic_shared<const Blah>   global_blah;
 *
 *      void    modify_the_global_blah_in_many_threads_with_no_locking()
 *      {
 *          bool    done = false;
 *          do
 *          {
 *              boost::shared_ptr<const Blah>
my_blah(global_blah.get());
 *
 *              boost::shared_ptr<Blah>         new_blah(*my_blah);
 *              new_blah->some_modification();
 *              done    = global_blah.compare_and_set(my_blah,
new_blah);
 *          }
 *          while (!done);
 *      }
 *
 *  \endcode
 *
 *  Threads that just need to do some work looking at the node:
 *
 *  \code
 *
 *      void    print_the_global_blah_in_many_threads_with_no_locking()
 *      {
 *          boost::shared_ptr<const Blah>   my_blah(global_blah.get());
 *
 *          my_blah->print();
 *      }
 *
 *  \endcode
 *
 *  Using atomic_shared<T> this way satisfies the Thread Safety portion
of
 *  the boost::shared_ptr<T> documentation.
 */
template<class T>
class atomic_shared
{
    atomic_shared&  operator=(const atomic_shared&);
public:
    typedef boost::shared_ptr<T>            base_ptr;
    /** construct an empty pointer. */
    atomic_shared()
        : ptr(),
          mutex()
    {
    }
    /** copy constructor.  Since we like to put atomic_shared<> in
std::map<>
     *  via std::map<atomic_shared<T> >::insert(std::make_pair(key,
value)),
     *  this needs to be here.
     */
    atomic_shared(const atomic_shared& p)
        : ptr(p.get()),
          mutex()
    {
    }
    /** construct a protected pointer from a bare one. */
    template<class Y>
    explicit atomic_shared(Y* p)
        : ptr(p),
          mutex()
    {
    }
    /** construct a protected pointer from a shared_ptr. */
    template<class U>
    explicit atomic_shared(const boost::shared_ptr<U>& p)
        : ptr(p),
          mutex()
    {
    }
    ~atomic_shared()
    {
    }
    /** Is it not null? */
    operator bool() const
    {
        bool    rv;
        
        {
            boost::recursive_try_mutex::scoped_lock  l(mutex);
            rv  = ptr;
        }
        
        return rv;
    }
    /** Is it null? */
    bool    operator!() const
    {
        bool    rv;
        
        {
            boost::recursive_try_mutex::scoped_lock  l(mutex);
            rv  = !ptr;
        }
        
        return rv;
    }
    /** Right here is the only way to _use_ the pointer.  To use what
the
     *  pointer is pointing to, you must make a private copy in your
     *  thread.
     */
    inline base_ptr get() const
    {
        base_ptr    p;
        
        {
            boost::recursive_try_mutex::scoped_lock  l(mutex);
            p = ptr;
        }
        
        return p;
    }
    /** Attempt to set the value of the pointer with another pointer,
but
     *  only if the pointer is the same as a previously sampled value of
     *  the pointer.
     *
     *  @param  cmp     Value of pointer previously retrieved with
get().
     *  @param  x       New value of pointer.
     *  @return true if the pointer could be set to x (i.e. its value
was
     *               still cmp with the mutex locked.)
     */
    template<class Y, class X>
    bool    compare_and_set(const boost::shared_ptr<Y>& cmp,
                            boost::shared_ptr<X>&       x)
    {
        bool    r = false;
        boost::recursive_try_mutex::scoped_try_lock  l(mutex, false);
        
        if (l.try_lock())
        {
            r = ptr == cmp;
            if (r) ptr = x;
        }
        return r;
    }
private:
    base_ptr                            ptr;
    mutable boost::recursive_try_mutex  mutex;
};  // atomic_shared
        
#endif