smart_ptr.h

Go to the documentation of this file.

/*
 * smart_ptr.h
 *
 * Copyright 2002,2009 Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Yet ANOTHER smart ptr.  This is basically the std::auto_ptr<T>,
 * but it has special copy/assignment operators so it can be used
 * in STL collections.
 */

#ifndef WAVEPACKET_SMART_PTR_H__
#define WAVEPACKET_SMART_PTR_H__


// includes --------------------------------------------------------------------
#include "threadsafe_counter.h"


/// \ingroup threadsafe
/*@{*/

/// Auto-destructing pointer class.
///
/// This is a ref-counting class.  It keeps the ref struct as a separate
/// struct on the heap, and all smart pointers share it.
///
/// \b WARNING: you will really hose yourself if you have two or more smart_ptr's
/// wrapping the same underlying pointer if they use different ref structs.
/// The way to avoid this is to use smart_ptr<T>'s everywhere (never convert to
/// a raw T* and then pass to another smart_ptr<T>, for instance). 
///
/// This class is PARTLY threadsafe!  That is, there is a mutex protecting the ref
/// count.  This is a slight overhead for single-threaded applications, but is
/// probably worth it overall.  General smart_ptr<T> accesses such as
/// \verbatim  p->doSomething()  \endverbatim
/// don't pay any synchronization
/// overhead.  Only operations that impact the ref count (assignment,
/// destruction, etc.) will synchronize.
///
/// Put another way, accessing the pointer is NOT synchronized (and therefore
/// not generally threadsafe).  If your class
/// needs that, you'll need to make the class itself threadsafe.
template <class T>
class smart_ptr
{
public:
        // constructors --------------------------------------------------------
        smart_ptr(T * pT = NULL) throw() : m_prefcount(NULL), m_pT(NULL) {
                this->assign(pT);
        }

        template <class X>
        smart_ptr(IN const smart_ptr<X>& from) throw() :
            m_prefcount(NULL), m_pT(NULL) {
                this->assign(from);
        }

        smart_ptr(IN const smart_ptr<T>& from) throw() :
            m_prefcount(NULL), m_pT(NULL) {
                this->assign(from);
        }
        
        // destructor ----------------------------------------------------------
        ~smart_ptr(void) throw() { this->release(); }

        // operators -----------------------------------------------------------
        T * operator -> (void) throw() {
                ASSERT(m_pT, "NULL smart pointer");
                return m_pT;
        }

        const T * operator -> (void) const throw() {
                ASSERT(m_pT, "NULL smart pointer");
                return m_pT;
        }

        operator T * (void) throw() {
                return m_pT;
        }

        operator const T * (void) const throw() {
                return m_pT;
        }

        bool operator ! (void) const throw() {
                return !m_pT;
        }

        const smart_ptr<T>& operator = (IN T * pT) throw() {
                this->assign(pT);
                return *this;
        }

        template <class X>
        const smart_ptr<T>& operator = (IN const smart_ptr<X>& from) throw() {
                this->assign(from);
                return *this;
        }

        const smart_ptr<T>& operator = (IN const smart_ptr<T>& from) throw() {
                this->assign(from);
                return *this;
        }

        long get_ref_count(void) const throw() {
                return (m_prefcount) ? m_prefcount->getCount() : 0;
        }

        T * disown(void) throw() {
                // releases refs without destroying object.
                // only works if only 1 ref remains!
                ASSERT(m_prefcount && m_pT,
                    "calling disown() on empty smart_ptr<T>");
                ASSERT(!m_prefcount->decrement(),
                    "Can only disown() smart_ptr<T>'s with 1 ref");
                delete m_prefcount;
                m_prefcount = NULL;
                T * pT = m_pT;
                m_pT = NULL;
                return pT;
        }

private:
        // private typedefs ----------------------------------------------------

        // private helper methods ----------------------------------------------
        void assign(IN T * pT) throw() {
                this->release();
                if (pT) {
                        m_prefcount = new threadsafe_counter;
                        ASSERT(m_prefcount, "out of memory");
                        m_prefcount->increment();
                        m_pT = pT;
                }
        }

        template <class X>
        void assign(IN const smart_ptr<X>& from) throw() {
                this->release();

                // nasty cast to get rid of const-ness, and type!
                smart_ptr<T> * pfoo =
                    (smart_ptr<T> *) ((void *) &from);

                // force from to increment so it doesn't get nuked on another
                //    thread.
                // so long as ref counts aren't corrupted, this should avoid
                //    all such race conditions.
                long incCount = pfoo->increment();
                if (incCount < 2) {
                        // from is dead or dying!  no object to copy
                        pfoo->decrement();
                        return;
                }

                // FROM HERE ON OUT WE HAVE TO MAKE SURE WE CALL pfoo->decrement
                //   or else we hang on to the incremented count for ourselves

                // make sure we can safely cast from X to T
                const X * pX = (const X *) from;
                const T * pT = dynamic_cast<const T *>(pX);
                if (!pT) {
                        // can't cast, so this isn't a valid assignment
                        pfoo->decrement();
                        return;
                }

                // non-null?
                ASSERT(pT, "should have non-null pointer");

                // another nasty cast
                T * new_pT = (T *) pT;

                // store ref pointer, and copy object pointer
                m_prefcount = pfoo->m_prefcount;
                m_pT = new_pT;

                // we already took a new ref (pfoo->increment(), above) so we
                //   are all done
        }

        void release(void) throw() {
                if (m_prefcount) {
                        // decrement count
                        long count = m_prefcount->decrement();
                        if (count < 1) {
                                // we had the last ref!  destroy everything
                                m_prefcount->increment();   // avoid re-entry
                                delete m_pT;
                                delete m_prefcount;
                        }

                        // clear all state
                        m_prefcount = NULL;
                        m_pT = NULL;
                }
                ASSERT(!m_pT && !m_prefcount, "Invalid release");
        }

        long increment(void) throw() {
                        if (m_prefcount) {
                                return m_prefcount->increment();
                        }
                        return 0;
                }

        long decrement(void) throw() {
                        if (m_prefcount) {
                                return m_prefcount->decrement();
                        }
                        return 0;
                }

        // private data --------------------------------------------------------
        threadsafe_counter *    m_prefcount;    // pointer to ref count
        T      *m_pT;           // our own (possibly cast) pointer to T
};



#endif  // WAVEPACKET_SMART_PTR_H__