CeylanCountedPointer.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the Ceylan library.
 *
 * The Ceylan library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The Ceylan library 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 Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and the GNU General Public License along with the Ceylan library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#ifndef CEYLAN_COUNTED_POINTER_H_
#define CEYLAN_COUNTED_POINTER_H_


#include "CeylanTypes.h"              // for Uint32
#include "CeylanTextDisplayable.h"    // for TextDisplayable
#include "CeylanOperators.h"          // for Ceylan::toString



#include <string>



/*
 * Optimization of copy, made only when necessary, currently disabled for the
 * sake of simplicity.
 *
 * Moreover, the code seems to make the assumption that a copy constructor 
 * for the templated type exists, which is not always true.
 *
 */
#define CEYLAN_COUNTED_POINTER_USE_COPY_ON_WRITE 0 
//#define CEYLAN_COUNTED_POINTER_USE_COPY_ON_WRITE 1


// Set to 1 if wanting refcount-related debug displays:
#define CEYLAN_COUNTED_POINTER_DEBUG 0
//#define CEYLAN_COUNTED_POINTER_DEBUG 1


#if CEYLAN_COUNTED_POINTER_DEBUG

    #include <iostream>

    #define CEYLAN_DISPLAY_REFCOUNT(message) std::cout << "[CountedPointer] " << message << std::endl ;

#else // CEYLAN_COUNTED_POINTER_DEBUG

    #define CEYLAN_DISPLAY_REFCOUNT(message)

#endif // CEYLAN_COUNTED_POINTER_DEBUG




namespace Ceylan
{



    typedef Ceylan::Uint32 ReferenceCount ;



    template< typename T >
    class CountedPointer : public Ceylan::TextDisplayable
    {
    
    
        // First: interface.
            
            
        public:


            typedef T ElementType ;    



            CountedPointer( ElementType * resourcePointer = 0 )
            {
         
                /*
                 * Speeds default creation for arrays (stack gets a reference).
                 *
                 * Therefore, for each class templated with CountedPointer,
                 * as soon as a first counter pointer is created, the 
                 * following static referent will be itself created (and 
                 * deallocated at program ending).
                 *
                 */
                static Referent staticRef( /* null pointer */ 0, 
                    /* ref count */ 1 ) ; 

                setReferent( ( resourcePointer == 0 ) ? 
                    &staticRef : new Referent( resourcePointer ) ) ;
                    
            }



            CountedPointer( const CountedPointer<T> & source ) :
                Ceylan::TextDisplayable()
            {
            
                setReferent( source._referent ) ;
                
            }



            CountedPointer<T> & operator=( const CountedPointer<T> & source )
            {
            
                if ( _referent != source._referent )
                {
                    // Sets own referent to the source one:
                    reset( source._referent ) ;
                }
                    
                /*
                 * else do nothing, for auto-assignment (foo_ref1 = foo_ref1 ;)
                 *
                 */
                
                // For assignment chaining:
                return * this ;
                
            }



            ~CountedPointer() throw()
            {
            
                release() ;
                
            }

            
            
            ElementType & operator*() const
            {
            
                return * get() ;
                
            }

            
            
            ElementType * operator->() const
            {
            
                return get() ;
                
            }



            ElementType * get() const
            {
            
                return _referent->_resourcePointer ;
                
            }



            bool isUnique() const
            {
            
                return ( _referent->_refCount == 1 ) ;
                
            }


            
            ReferenceCount getReferenceCount() const
            {
            
                return _referent->_refCount ;
                            
            }



            virtual const std::string toString( VerbosityLevels level = high )
                const
            {
            
                if ( _referent != 0 )
                {
                    
                    std::string res = "Counted pointer keeping track of " 
                        + Ceylan::toString( _referent->_refCount ) 
                        + " reference(s) to its wrapped resource ("
                        + Ceylan::toString( _referent->_resourcePointer ) 
                        + ")" ;
                    
                    if ( level == Ceylan::low )
                        return res ;
                    
                    if ( _referent->_resourcePointer == 0 )
                        return res + ", which is a null pointer (abnormal)" ;
                    else
                        return res + ", which is: " + 
                            _referent->_resourcePointer->toString( level ) ;
                                
                }       
                else
                {
                    return "Counted pointer with no resource referenced" ;
                }   
                
            }   


#if CEYLAN_COUNTED_POINTER_USE_COPY_ON_WRITE


            void isolate()
            {
            
                if ( isUnique() )
                {
                
                    // Nothing to do.
                    return ;
                    
                }   


                /* 
                 * @note: if this fails, the state of the object must continue
                 * to be sound. 
                 * The only problem areas are the new operations (and possibly
                 * the delete called by release). 
                 * Basically, we treat the code like a transaction. 
                 *
                 */


                /*
                 * Throws out of isolate, if error creating element occurs.
                 *
                 * Supposes a copy constructor for the templated type exists!
                 *
                 */
                ElementType * newElement = new ElementType( * get() ) ;


                try
                {
             
                    /* 
                     * @note: This is safe if the new operation fails. 
                     * If success, it does a simple release and reference call. 
                     */

                    reset( new Referent( newElement ) ) ;
                 
                }
                catch( ... )
                {
                
                    delete newElement ;
                    
                    // Propagate the exception:
                    throw ;   
                         
                }
                
            }


#endif // CEYLAN_COUNTED_POINTER_USE_COPY_ON_WRITE







     private:


         struct Referent
         {
         
         
            // Method members.
         
         
             Referent( ElementType * resourcePointer = 0, 
                    ReferenceCount initialCount = 0 ):
                 _resourcePointer( resourcePointer ),
                 _refCount( initialCount )
             {
            
                CEYLAN_DISPLAY_REFCOUNT( 
                    "after referent construction for resource pointer "
                    << Ceylan::toString( _resourcePointer )
                    << ", refcount = " << _refCount ) ;
             
             }


             ~Referent() throw()
             {
             
                CEYLAN_DISPLAY_REFCOUNT( 
                    "referent destructor deallocating its resource "
                    << Ceylan::toString( _resourcePointer ) ) ;

                // The actual only place where the wrapped resource is deleted:
                delete _resourcePointer ;
                
             }
             


            // Data members.
            
            
            ElementType * _resourcePointer ;     
            
            
            ReferenceCount _refCount ;
            
            
         } * _referent ;                



         // Simple methods to reference and release representations.



         /*
          * @note The following methods should use critical sections if they
          * were to be used in a multithreaded context.
          *
          */

         
         void reset( Referent * refPointer )
         {
         
             // Enter critical section: auto_lock< lock_type > lock ;

             release() ;
             setReferent( refPointer ) ;
             
         }



        void setReferent( Referent * refPointer )
        {

            // Enter critical section: auto_lock< lock_type > lock ;
            
            ( _referent = refPointer )->_refCount++ ;
            
            CEYLAN_DISPLAY_REFCOUNT( "after setReferent, refcount = " 
                << _referent->_refCount << " for "
                << Ceylan::toString( _referent->_resourcePointer ) ) ;
                
        }



        void release()
        {

            // Enter critical section: auto_lock< lock_type > lock ;

            if ( --_referent->_refCount == 0 )
            {
            
                CEYLAN_DISPLAY_REFCOUNT( "after release, refcount is null, "
                    "deallocating resource "
                    << Ceylan::toString( _referent->_resourcePointer ) ) ;
                    
                // Will trigger the resource deletion too:
                delete _referent ;
                _referent = 0 ;
                
            }
            else
            {
            
                CEYLAN_DISPLAY_REFCOUNT( "after release, refcount = " 
                    << _referent->_refCount << " for " 
                    << Ceylan::toString( _referent->_resourcePointer ) ) ;
            }
            
        }
         
         
         
     } ;  // Definition of CountedPointer template.
 
 
 
} // namespace Ceylan



#endif // CEYLAN_COUNTED_POINTER_H_

---