include/KDIS/Extras/KRef_Ptr.hpp

   1 /*********************************************************************
   2 Copyright 2013 Karl Jones
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7
   8 1. Redistributions of source code must retain the above copyright notice, this
   9    list of conditions and the following disclaimer.
  10 2. Redistributions in binary form must reproduce the above copyright notice,
  11    this list of conditions and the following disclaimer in the documentation
  12    and/or other materials provided with the distribution.
  13
  14 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  15 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  16 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  17 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  18 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  19 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  21 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  23 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24
  25 For Further Information Please Contact me at
  26 Karljj1@yahoo.com
  27 http://p.sf.net/kdis/UserGuide
  28 *********************************************************************/
  29
  30 /********************************************************************
  31 class:      KRef_Ptr
  32 created:    2009/07/22
  33 author:     Karl Jones
  34
  35 purpose:    Implementation of a referenced smart pointer.
  36             Holds a counter of how many references are currently held of a pointer.
  37             When the final reference is released the memory is released.
  38
  39             -*How To Use:*-
  40
  41             KRef_Ptr<MyClass> pObj = new MyClass;
  42
  43             pObj can now be used like a normal pointer.
  44
  45             E.G
  46
  47             pObj->func();
  48             *pObj.func();
  49
  50             -*Note:*-
  51
  52             Be carefull of the following mistakes:
  53
  54             - MyClass * p = pObj.GetPtr(); // p is not safe. It could be deleted when the KRef_Ptr goes out of scope leaving you with a NULL pointer.
  55
  56             - KRef_Ptr<MyClass> pRef = pObj.GetPtr(); // This will create a second reference to the pointer which will cause problems.
  57
  58               instead use
  59
  60               KRef_Ptr<MyClass> pRef = pObj;
  61 *********************************************************************/
  62
  63 #pragma once
  64
  65 #include "./../KDefines.h"
  66
  67 namespace KDIS {
  68 namespace UTILS {
  69
  70 typedef KDIS::KUINT16 RefCounter; // Change the counter to KUINT32 if you expect to have over 65,535 references.
  71
  72 template<class Type>
  73 class KRef_Ptr
  74 {
  75 private:
  76
  77     typedef KRef_Ptr<Type> ThisType;
  78
  79     Type * m_pRef;
  80
  81     RefCounter * m_piCount;
  82
  83     //************************************
  84     // FullName:    KRef_Ptr<Type>::ref
  85     // Description: Increments reference counter
  86     //************************************
  87     void ref()
  88     {
  89         if( m_pRef )++( *m_piCount );
  90     };
  91
  92     //************************************
  93     // FullName:    KRef_Ptr<Type>::unRef
  94     // Description: Decrements reference counter, cleans
  95     //              up if no other references exist.
  96     //************************************
  97     void unRef()
  98     {
  99         if( m_pRef )
 100         {
 101             --( *m_piCount );
 102             if( *m_piCount == 0 )
 103             {
 104                 delete m_piCount;
 105                 delete m_pRef;
 106                 m_piCount = NULL;
 107                 m_pRef = NULL;
 108             }
 109         }
 110     };
 111
 112 public:
 113
 114     KRef_Ptr() :
 115         m_pRef( NULL ),
 116         m_piCount( NULL )
 117     {
 118     };
 119
 120     KRef_Ptr( Type * p )
 121     {
 122         m_pRef = p;
 123         m_piCount = new RefCounter;
 124         *m_piCount = 0;
 125         ref();
 126     };
 127
 128     KRef_Ptr( const KRef_Ptr<Type> & p ) :
 129         m_pRef( p.m_pRef ),
 130         m_piCount( p.m_piCount )
 131     {
 132         ref();
 133     };
 134
 135     virtual ~KRef_Ptr()
 136     {
 137         unRef();
 138     };
 139
 140     //************************************
 141     // FullName:    KRef_Ptr<Type>::Clear
 142     // Description: Removes the current reference held.
 143     //************************************
 144     void Clear()
 145     {
 146         unRef();
 147         m_pRef = NULL;
 148         m_piCount = NULL;
 149     };
 150
 151     //************************************
 152     // FullName:    KRef_Ptr<Type>::GetPtr
 153     // Description: Returns pointer to the current reference
 154     //              or NULL if no reference exists.
 155     //              Note: The returned pointer will not be safe. Avoid using this function.
 156     //************************************
 157     Type * GetPtr() const
 158     {
 159         return m_pRef;
 160     };
 161
 162     //************************************
 163     // FullName:    KRef_Ptr<Type>::GetCount
 164     // Description: Returns number of reference that currently exist
 165     //              for this pointer or 0 if no reference is held.
 166     //************************************
 167     RefCounter GetCount() const
 168     {
 169         if( m_piCount )return *m_piCount;
 170     };
 171
 172     //************************************
 173     // FullName:    KRef_Ptr<Type>::operator=
 174     // Description: Assignment of an other KRef_Ptr.
 175     // Parameter:   const KRef_Ptr<Type> & p
 176     //************************************
 177     KRef_Ptr<Type> & operator=( const KRef_Ptr<Type> & p )
 178     {
 179         if ( this != &p )
 180         {
 181             if ( m_pRef == p.m_pRef )return *this;
 182             unRef();
 183             m_pRef = p.m_pRef;
 184             m_piCount = p.m_piCount;
 185             ref();
 186         }
 187         return *this;
 188     };
 189
 190     //************************************
 191     // FullName:    KRef_Ptr<Other>::operator=
 192     // Description: Assignment of an other KRef_Ptr of a different type.
 193     // Parameter:   const KRef_Ptr<Other> & p
 194     //************************************
 195     template<class Other>
 196     KRef_Ptr<Type> & operator=( const KRef_Ptr<Other> & p )
 197     {
 198         unRef();
 199         m_pRef = p.m_pRef;
 200         m_piCount = p.m_piCount;
 201         ref();
 202         return *this;
 203     };
 204
 205     //************************************
 206     // FullName:    KRef_Ptr<Type>::operator=
 207     // Description: Assignment of a new reference.
 208     // Parameter:   Type * p
 209     //************************************
 210     KRef_Ptr<Type> & operator=( Type * p )
 211     {
 212         if( m_pRef == p )return *this;
 213         unRef();
 214         m_pRef = p;
 215         m_piCount = new RefCounter;
 216         *m_piCount = 0;
 217         ref();
 218         return *this;
 219     };
 220
 221     //************************************
 222     // FullName:    KRef_Ptr<Other>::operator=
 223     // Description: Assignment of a new reference of a different type.
 224     // Parameter:   Other * p
 225     //************************************
 226     template<class Other>
 227     KRef_Ptr<Type> & operator=( Other * p )
 228     {
 229         unRef();
 230         m_pRef = p;
 231         m_piCount = new RefCounter;
 232         *m_piCount = 0;
 233         ref();
 234         return *this;
 235     };
 236
 237     //************************************
 238     // FullName:    KRef_Ptr<Type>::operator==
 239     // Description: Comparison equals. Checks if both references are the same.
 240     // Parameter:   const KRef_Ptr<Type> & p
 241     //************************************
 242     KBOOL operator==( const KRef_Ptr<Type> & p )const
 243     {
 244         return m_pRef == p.m_pRef;
 245     };
 246
 247     //************************************
 248     // FullName:    KRef_Ptr<Other>::operator==
 249     // Description: Comparison equals. Checks if both references are the same of a
 250     //              different type.
 251     //              E.G An upast/downcast of the current type.
 252     // Parameter:   const KRef_Ptr<Other> & p
 253     //************************************
 254     template<class Other>
 255     KBOOL operator==( const KRef_Ptr<Other> & p )const
 256     {
 257         return m_pRef == p.m_pRef;
 258     };
 259
 260     //************************************
 261     // FullName:    KRef_Ptr<Type>::operator*
 262     // Description: When referencing the KRef_Ptr return our referenced object.
 263     //************************************
 264     Type & operator*() const
 265     {
 266         return *m_pRef;
 267     };
 268
 269     //************************************
 270     // FullName:    KRef_Ptr<Type>::operator Type *
 271     // Description: Implicit conversion support.
 272     //************************************
 273     operator Type *()
 274     {
 275         return m_pRef;
 276     }
 277
 278     //************************************
 279     // FullName:    KRef_Ptr<Type>::operator->
 280     // Description: Returns the referenced pointer.
 281     //************************************
 282     Type * operator->() const
 283     {
 284         return m_pRef;
 285     };
 286
 287     //************************************
 288     // FullName:    KRef_Ptr<Type>::operator!=
 289     // Description: Comparison does not equals. Compares the referenced pointer to an unsafe pointer.
 290     // Parameter:   const Type * p
 291     //************************************
 292     KBOOL operator!= ( const Type * p ) const
 293     {
 294         return m_pRef != p;
 295     };
 296
 297     //************************************
 298     // FullName:    KRef_Ptr<Other>::operator!=
 299     // Description: Comparison does not equals. Compares the referenced pointer to an unsafe pointer of a different type.
 300     //              E.G a derrived type.
 301     // Parameter:   const Other * p
 302     //************************************
 303     template<class Other>
 304     KBOOL operator!= ( const Other * p ) const
 305     {
 306         return m_pRef != p;
 307     };
 308
 309     //************************************
 310     // FullName:    KRef_Ptr<Type>::operator!=
 311     // Description: Comparison does not equals. Compares the referenced pointer to an other KRef_Ptr.
 312     // Parameter:   const KRef_Ptr<Type> & p
 313     //************************************
 314     KBOOL operator!= ( const KRef_Ptr<Type> & p ) const
 315     {
 316         return m_pRef != p.m_pRef;
 317     };
 318
 319     //************************************
 320     // FullName:    KRef_Ptr<Other>::operator!=
 321     // Description: Comparison does not equals. Compares the referenced pointer to an other KRef_Ptr of a different type.
 322     // Parameter:   const KRef_Ptr<Other> & p
 323     //************************************
 324     template<class Other>
 325     KBOOL operator!= ( const KRef_Ptr<Other> & p ) const
 326     {
 327         return m_pRef != p.m_pRef;
 328     };
 329
 330     //************************************
 331     // FullName:    KRef_Ptr<Type>::operator bool() const
 332     // Description: This conversion operator allows KRef_Ptr objects to be used in boolean contexts, like if(p && p->valid()) {}.
 333     //************************************
 334     typedef Type * ThisType::*UnspecifiedBoolType;
 335
 336     operator UnspecifiedBoolType() const // never throws
 337     {
 338         return m_pRef == 0? 0: &ThisType::m_pRef;
 339     }
 340
 341     // operator! is redundant, but some compilers need it
 342     KBOOL operator! () const // never throws
 343     {
 344         return m_pRef == 0;
 345     }
 346 };
 347
 348
 349 } // END namespace UTILS
 350 } // END namespace KDIS