---

CdbCPtr.hh

Go to the documentation of this file.

#ifndef CDB_CPTR_HH
#define CDB_CPTR_HH

// File and Version Information:
//      $Id: CdbCPtr.hh,v 1.7 2004/08/06 05:54:14 bartoldu Exp $

#include "CdbBase/CdbCommon.hh"
#include "CdbBase/CdbCPtrBase.hh"
#include "CdbBase/CdbDoNotClosePolicy.hh"

#include <iostream>

/// Smart counted pointer class supporting the automatic close policy.
/**
  * The is a non-intrusive implementation that allocates an additional
  * int and pointer for every counted object.
  *
  * The close policy is provided through an additional policy class.
  * The only method we expect from the policy class is:
  *
  * @code
  *
  *     static void CLOSE_POLICY::close( P* ptr );
  * @endcode
  *
  * It's up to the developer of this class how it will interract
  * with the pointee object in order to "close" its instances.
  *
  * By default, the "CdbDoNotClosePolicy" policy class will be used.
  */

template < class P, class CLOSE_POLICY = CdbDoNotClosePolicy<P> >
class CdbCPtr : private CdbCPtrBase<P> {

public:

  /// This is the type of objects pointed through this smart pointer
  /**
    * The concrete type will be available at the instantiation of the current
    * template class.
    */
    typedef P element_type;

  /// This is the type of the close policy
  /**
    * The concrete type will be available at the instantiation of the current
    * template class.
    */
    typedef CLOSE_POLICY close_policy;

  /// The constructor
  /**
    * This is the normal and default constructor. It will take the ownership
    * of specified pointer and initialize the internal counter to 1 if a non-null
    * pointer is passed.
    */
    CdbCPtr( P* ptr = 0 );

  /// The copy constructor
  /**
    * This constructor initializes the current instance to share
    * the counter object with the specified pointer. This will also increment
    * by 1 the number of smart pointers pointing onto the poentee, if this
    * is not a 0 pointer.
    */
    CdbCPtr( const CdbCPtr<P,CLOSE_POLICY>& thePtr );

  /// The destructor
  /**
    * Decrement the number of clients for the pointee. If we're the last
    * smart pointer then:
    *
    * - close the object. This operation is done through the supplied (as
    *   a template parameter) policy class.
    *
    * - destroy the pointee. Here we're assuming that its destructor
    *   is available for us.
    */
    ~CdbCPtr( );

  /// Asignment operator
  /**
    * Drop the currently hold pointee.
    * And borrow the counter object from the right-hand smart pointer object
    * and increment by 1the number of clients for the pointee object
    * (if this is not the 0).
    */
    CdbCPtr& operator=( const CdbCPtr<P,CLOSE_POLICY>& thePtr );

  /// Asignment operator
  /**
    * Drop the currently hold pointee.
    * And take ownership ower the specified pointee object. Set the total
    * number of its clients to 1.
    */
    CdbCPtr& operator=( P* ptr );

  /// Dereference operator
  /**
    * Return a reference to the pointed object.
    *
    * Here is a trivial example on how to use this operator:
    *
    * @code
    *   // This is a simple class whose objects will be
    *   // pointed through the smart pointer.
    *     class A ... {
    *     public:
    *         void foo( );
    *     };
    *
    *   // Initialize smart pointer to point onto a new object.
    *   // Remember, that the smart pointer will take ownership
    *   // over this object.
    *     CdbCPtr<A,SomePolicy> aPtr( new A( ));
    *
    *   // Do something usefull
    *     (*Aptr).foo( );   // 
    * @endcode
    */
    P& operator*( ) const;

  /// The arrow operator
  /**
    * This operator is meant to provide access to the members of the pointed
    * object in the same way if it were the regular pointer.
    *
    * Here is a trivial example on how to use this operator:
    *
    * @code
    *   // This is a simple class whose objects will be
    *   // pointed through the smart pointer.
    *     class A ... {
    *     public:
    *         void foo( );
    *     };
    *
    *   // Initialize smart pointer to point onto a new object.
    *   // Remember, that the smart pointer will take ownership
    *   // over this object.
    *     CdbCPtr<A,SomePolicy> aPtr( new A( ));
    *
    *   // Do something usefull
    *     APtr->foo( );   // 
    * @endcode
    */
    P* operator->( ) const;

  /// The comparision operator
  /**
    * This operator will compare two smart pointers if they both point
    * onto the same object. It will also return true if both smart pointers
    * are pointinig to 0.
    *
    * An example:
    *
    * @code
    *   // Initialize two smart pointers in different ways: the first one
    *   // will point to 0, and the second one - to a real object of class A.
    *     CdbCPtr<A,...> aNullPtr;
    *     CdbCPtr<A,...> aSomePtr( new A( ));
    *
    *   // Compare the pointers
    *     if( aSomePtr == aNullPtr ) {
    *         ...
    *     }
    * @endcode
    *
    * @return the result of comparision
    */
    bool operator==( const CdbCPtr<P,CLOSE_POLICY>& thePtr ) const;

  /// The not-equal operator
  /**
    * @see CdbCPtr::operator==( CdbCPtr& thePtr )
    */
    bool operator!=( const CdbCPtr<P,CLOSE_POLICY>& thePtr ) const;

  /// The comparision operator
  /**
    * This operator will compare a smart pointer with a regular pointer
    * to see if the smart one points to the same object as the regular one.
    * It will also return true if both pointers are pointinig to 0.
    *
    * Note, that the primarily use of this operator is to check if the smart
    * pointer is pointing to 0. The other cases should not be possible
    * because smart pointer must be the only way to point objects.
    *
    * It's also important to note, that because of the restricted syntax of
    * the comparision operator in the class's scope, it's only possible to specify
    * the regular pointer on the righ-hand side of the comparision as it's shown
    * in a code example below. The reverse order can be added later for concrete
    * instantiations of the smart pointer.
    *
    * An example:
    *
    * @code
    *   // Initialize a smart pointer to a real object of class A.
    *     CdbCPtr<A,...> aSomePtr( new A( ));
    *     A*             ptr = ...;
    *
    *   // Compare this pointer with specified pointer.
    *     if( aSomePtr == ptr ) {
    *         ...
    *     }
    * @endcode
    *
    * @return the result of comparision
    */
    bool operator==( const P* ptr ) const;

  /// The not-equal operator
  /**
    * @see CdbCPtr::operator==( const P* ptr )
    */
    bool operator!=( const P* ptr ) const;

  /// Explicit check if the pointer does point onto 0
  /**
    * This operation is equivalent to the "operator==((const P*)0 )".
    *
    * An example:
    *
    * @code
    *   // Initialize a smart pointer to a real object of class A.
    *     CdbCPtr<A,...> aSomePtr( new A( ));
    *
    *   // Compare this pointer with specified pointer.
    *     if( !aSomePtr.isNull( )) {
    *         // Okay, the pointer is pointing onto something usefull.
    *     }
    * @endcode
    *
    * @return the result of comparision
    */
    bool isNull( ) const;

  /// Return a non-const pointer to the pointed object
  /**
    * Note, that this does not transfer the ownership over the pointed object.
    */
    P* get( ) const;

  /// Check if this smart pointer is the only clients of the held pointer
  /**
    * @return true if this is the only client
    */
    bool unique( ) const;

private:

  /// The nested class representing an internal counter.
  /**
    * Objects of these class are shared among multiple smart pointers
    * of the same type. The role of the counter class is to keep the pointer
    * to teh pointed object and to count the current numbver of clients - smart
    * pointers.
    */
    class Counter {
    public:

      /// The constructor
      /**
        * This is the normal and default constructor of the class
        * initializeing its context.
        */
        Counter( P* ptr = 0, unsigned count = 1 );

    public:

        P*       _ptr;
        unsigned _count;
    };

    Counter* _myCounter;

  /// Acquire the specified counter object
  /**
    * This method is meant to start sharing the specified counter
    * object and to increment the number of clients by 1.
    */
    void acquire( Counter* theCounter );

  /// Drop using the current counter object
  /**
    * This method is a way for a smart pointer object to get rid of
    * its current contex. This will lead to the reduction by 1 of the number
    * of current clients of the pointee object and possible closure
    * and subsequent destruction of this object if we were the last client.
    */
    void release( );
};

/// The missing equality operator for the smart pointer
/**
  * This operator allows to compare a smart pointer with a regular one
  * while having the regular one on the left hand side of the comparision
  * expression.
  *
  * This makes possible the following use case:
  *
  * @code
  *     CdbXyzPtr thePtr = ...;
  *     if( 0 == thePtr ) ...
  * @endcode
  */

template < class P, class CLOSE_POLICY >
bool
operator==( const P*                       ptr,
            const CdbCPtr<P,CLOSE_POLICY>& thePtr )
{
    return thePtr == ptr;
}

/// The missing non-equal operator for the smart pointer
/**
  * See the previously defined global equaty operator
  */
template < class P, class CLOSE_POLICY >
bool
operator!=( const P*                       ptr,
            const CdbCPtr<P,CLOSE_POLICY>& thePtr )
{
    return thePtr != ptr;
}

#ifdef     BABAR_COMP_INST
#include "CdbBase/CdbCPtr.cc"
#endif  // BABAR_COMP_INST

#endif // CDB_CPTR_HH

---