Source: Ref.h


Annotated List
Files
Globals
Hierarchy
Index
/*------------------------------------------------------------------------------

   Copyright (c) 2000 Tyrell Corporation. All rights reserved.

   Tyrell DarkIce

   File     : Ref.h
   Version  : $Revision: 1.5 $
   Author   : $Author: darkeye $
   Location : $Source: /cvsroot/darkice/darkice/src/Ref.h,v $
   
   Copyright notice:

    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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

------------------------------------------------------------------------------*/
#ifndef REF_H
#define REF_H

#ifndef __cplusplus
#error This is a C++ include file
#endif


/* ============================================================ include files */

#include "Exception.h"


/* ================================================================ constants */


/* =================================================================== macros */


/* =============================================================== data types */

/**
 *  Java-like object reference class.
 *  Objects used with this reference class have to be descandents
 *  of class Referable.
 *
 *  sample usage:
 *
 *  
 *  #include "Ref.h"
 *  #include "Referable.h"
 *
 *  class  A : public virtual Referable;
 *
 *  ...
 *   
 *  A        * a = new A();
 *  Ref     ref1 = a;       // 1 reference to a
 *  Ref     ref2 = ref1;    // 2 references to a
 *
 *  ref1 = 0;      // 1 reference to a
 *  ref2 = 0;      // at this point object a is destroyed
 *  
* * Based on Tima Saarinen's work, * http://gamma.nic.fi/~timosa/comp/refcount.html * * @ref Referable * * @author $Author: darkeye $ * @version $Revision: 1.5 $ */ template class Ref { private: /** * The object referenced by this Ref. * Must be a descandant of Referable. */ T* object; protected: public: /** * Default constructor. */ inline Ref ( void ) throw () { object = NULL; } /** * Copy constructor. * * @param other the Ref to copy. * @exception Exception */ inline Ref ( const Ref & other ) throw ( Exception ) { object = NULL; set( other.object); } /** * Constructor based on an object to reference. * * @param obj the object to reference. * @exception Exception */ inline Ref ( T * obj ) throw ( Exception ) { object = obj; obj->increaseReferenceCount(); } /** * Destructor. * * @exception Exception */ inline virtual ~Ref ( void ) throw ( Exception ) { set( 0 ); } /** * Operator overload to make the reference seem like a pointer. * * @return the pointer to the object referenced. */ inline T* operator->() const throw ( Exception ) { if ( !object ) { throw Exception( __FILE__, __LINE__, "reference to NULL object"); } return object; } /** * Assignment operator. * * @param other the Ref to assign to this one. * @return a reference to this Ref. * @exception Exception */ inline Ref & operator= ( Ref other ) throw ( Exception ) { set( other.object); return *this; } /** * Assignment operator. * * @param obj pointer to the object to assign to this Ref. * @return a reference to this Ref. * @exception Exception */ inline Ref & operator= ( T* obj ) throw ( Exception ) { set( obj); return *this; } /** * Set the object referenced. * Deletes the old referenced object is this was it's last reference. * * @param newobj pointer to the object to reference by this Ref. * @exception Exception */ inline void set ( T * newobj ) throw ( Exception ) { // If equal do nothing if ( newobj == object ) { return; } // Increase reference count if ( newobj ) { newobj->increaseReferenceCount(); } // Decrease the reference count of the old referable if ( object ) { if ( object->decreaseReferenceCount() == 0 ) { delete object; } } // Assign object = newobj; } /** * Return object pointer. This method should be used with * care because it breaks the encapsulation. * Typically this method is needed for the method calls * which require literal object pointer. * * It may not be bad idea to pass the Ref * objects as method arguments. * * @return Object pointer or NULL. */ inline T* get ( void ) const throw () { return object; } /** * Equality operator. * * @param other the pointer to compare this with. * @return true is this Ref refers to the same object as other, * false otherwise. */ inline bool operator== ( const T * other ) const throw () { return object == other; } /** * Equality operator. * * @param other the Ref to compare this with. * @return true is the two Refs refer to the same object, * false otherwise. */ inline bool operator== ( const Ref & other ) const throw () { return object == other.object; } /** * Unequality operator. * * @param other the pointer to compare this with. * @return false is this Ref refers to a different object then other, * true otherwise. */ inline bool operator!= ( const T * other ) const throw () { return object != other; } /** * Unequality operator. * * @param other the Ref to compare this with. * @return false is the two Refs refer to the same object, * true otherwise. */ inline bool operator!= ( const Ref & other ) const throw () { return object != other.object; } }; /* ================================================= external data structures */ /* ====================================================== function prototypes */ #endif /* REF_H */ /*------------------------------------------------------------------------------ $Source: /cvsroot/darkice/darkice/src/Ref.h,v $ $Log: Ref.h,v $ Revision 1.5 2002/08/20 20:07:36 darkeye minor fixes Revision 1.4 2002/02/20 11:51:27 darkeye added equality operators to compare with pointers Revision 1.3 2000/11/11 14:55:31 darkeye minor bugfix Revision 1.2 2000/11/11 12:33:13 darkeye added kdoc-style documentation Revision 1.1.1.1 2000/11/05 10:05:54 darkeye initial version ------------------------------------------------------------------------------*/

Generated by: darkeye on destroy on Sun Feb 15 23:41:12 2004, using kdoc 2.0a54.