Teuchos_RCPDecl.hpp

Go to the documentation of this file.

// @HEADER
// ***********************************************************************
//
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
//
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
//
// This library is free software; you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as
// published by the Free Software Foundation; either version 2.1 of the
// License, or (at your option) any later version.
//
// This 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 for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
// USA
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ***********************************************************************
// @HEADER

#ifndef TEUCHOS_RCP_DECL_HPP
#define TEUCHOS_RCP_DECL_HPP


#include "Teuchos_RCPNode.hpp"
#include "Teuchos_ENull.hpp"
#include "Teuchos_NullIteratorTraits.hpp"


#ifdef REFCOUNTPTR_INLINE_FUNCS
#  define REFCOUNTPTR_INLINE inline
#else
#  define REFCOUNTPTR_INLINE
#endif


#ifdef TEUCHOS_DEBUG
#  define TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
#endif


namespace Teuchos {


template<class T> class Ptr;


enum ERCPWeakNoDealloc { RCP_WEAK_NO_DEALLOC };
enum ERCPUndefinedWeakNoDealloc { RCP_UNDEFINED_WEAK_NO_DEALLOC };
enum ERCPUndefinedWithDealloc { RCP_UNDEFINED_WITH_DEALLOC };


template<class T>
class RCP {
public:

  typedef T  element_type;


  inline RCP(ENull null_arg = null);

  inline explicit RCP( T* p, bool has_ownership = true );

  template<class Dealloc_T>
  inline RCP(T* p, Dealloc_T dealloc, bool has_ownership);

  inline RCP(const RCP<T>& r_ptr);

  template<class T2>
  inline RCP(const RCP<T2>& r_ptr);

  inline ~RCP();

  inline RCP<T>& operator=(const RCP<T>& r_ptr);

  inline RCP<T>& operator=(ENull);

  inline void swap(RCP<T> &r_ptr);



  inline bool is_null() const;

  inline T* operator->() const;

  inline T& operator*() const;

  inline T* get() const;

  inline T* getRawPtr() const;

  inline Ptr<T> ptr() const;

  inline Ptr<T> operator()() const;

  inline RCP<const T> getConst() const;



  inline ERCPStrength strength() const;

  inline bool is_valid_ptr() const;

  inline int strong_count() const;

  inline int weak_count() const;

  inline int total_count() const;

  inline void set_has_ownership();

  inline bool has_ownership() const;

  inline Ptr<T> release();

  inline RCP<T> create_weak() const;

  inline RCP<T> create_strong() const;

  template<class T2>
  inline bool shares_resource(const RCP<T2>& r_ptr) const;



  inline const RCP<T>& assert_not_null() const;

  inline const RCP<T>& assert_valid_ptr() const;

  inline const RCP<T>& debug_assert_not_null() const
    {
#ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
      assert_not_null();
#endif
      return *this;
    }

  inline const RCP<T>& debug_assert_valid_ptr() const
    {
#ifdef TEUCHOS_DEBUG
      assert_valid_ptr();
#endif
      return *this;
    }



  inline void reset();

  template<class T2>
  inline void reset(T2* p, bool has_ownership = true);

  inline int count() const;


private:

  // //////////////////////////////////////////////////////////////
  // Private data members

  T *ptr_; // NULL if this pointer is null
  RCPNodeHandle node_; // NULL if this pointer is null

public: // Bad bad bad

  // These constructors are put here because we don't want to confuse users
  // who would otherwise see them.

  inline explicit RCP(T* p, ERCPWeakNoDealloc);

  inline explicit RCP(T* p, ERCPUndefinedWeakNoDealloc);

  template<class Dealloc_T>
  inline RCP(T* p, Dealloc_T dealloc, ERCPUndefinedWithDealloc,
    bool has_ownership = true);

#ifndef DOXYGEN_COMPILE

  // WARNING: A general user should *never* call these functions!
  inline RCP(T* p, const RCPNodeHandle &node);
  inline T* access_private_ptr() const; // Does not throw
  inline RCPNodeHandle& nonconst_access_private_node(); // Does not thorw
  inline const RCPNodeHandle& access_private_node() const; // Does not thorw

#endif

};


// 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<RCP<T> >
// specialization since I want to be able to print the type name of an RCP
// that does not have the type T fully defined!


template<typename T>
class NullIteratorTraits<RCP<T> > {
public:
  static RCP<T> getNull() { return null; }
};


template<class T>
class DeallocNull
{
public:
  typedef T ptr_t;
  void free( T* ptr ) { }
};


template<class T>
class DeallocDelete
{
public:
  typedef T ptr_t;
  void free( T* ptr ) { if(ptr) delete ptr; }
};


template<class T>
class DeallocArrayDelete
{
public:
  typedef T ptr_t;
  void free( T* ptr ) { if(ptr) delete [] ptr; }
};


template<class T, class DeleteFunctor>
class DeallocFunctorDelete
{
public:
  DeallocFunctorDelete( DeleteFunctor deleteFunctor ) : deleteFunctor_(deleteFunctor) {}
  typedef T ptr_t;
  void free( T* ptr ) { if(ptr) deleteFunctor_(ptr); }
private:
  DeleteFunctor deleteFunctor_;
  DeallocFunctorDelete(); // Not defined and not to be called!
};


template<class T, class DeleteFunctor>
DeallocFunctorDelete<T,DeleteFunctor>
deallocFunctorDelete( DeleteFunctor deleteFunctor )
{
  return DeallocFunctorDelete<T,DeleteFunctor>(deleteFunctor);
}


template<class T, class DeleteHandleFunctor>
class DeallocFunctorHandleDelete
{
public:
  DeallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
    : deleteHandleFunctor_(deleteHandleFunctor) {}
  typedef T ptr_t;
  void free( T* ptr ) { if(ptr) { T **hdl = &ptr; deleteHandleFunctor_(hdl); } }
private:
  DeleteHandleFunctor deleteHandleFunctor_;
  DeallocFunctorHandleDelete(); // Not defined and not to be called!
};


template<class T, class DeleteHandleFunctor>
DeallocFunctorHandleDelete<T,DeleteHandleFunctor>
deallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
{
  return DeallocFunctorHandleDelete<T,DeleteHandleFunctor>(deleteHandleFunctor);
}


template<class T, class Embedded, class Dealloc>
class EmbeddedObjDealloc
{
public:
  typedef typename Dealloc::ptr_t ptr_t;
  EmbeddedObjDealloc(
    const Embedded &embedded, EPrePostDestruction prePostDestroy,
    Dealloc dealloc
    ) : embedded_(embedded), prePostDestroy_(prePostDestroy), dealloc_(dealloc)
    {}
  void setObj( const Embedded &embedded ) { embedded_ = embedded; }
  const Embedded& getObj() const { return embedded_; }
  Embedded& getNonconstObj() { return embedded_; }
  void free( T* ptr )
    {
      if (prePostDestroy_ == PRE_DESTROY)
        embedded_ = Embedded();
      dealloc_.free(ptr);
      if (prePostDestroy_ == POST_DESTROY)
        embedded_ = Embedded();
    }
private:
  Embedded embedded_;
  EPrePostDestruction prePostDestroy_;
  Dealloc dealloc_;
  EmbeddedObjDealloc(); // Not defined and not to be called!
};


template<class T, class Embedded >
EmbeddedObjDealloc<T,Embedded,DeallocDelete<T> >
embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
{
  return EmbeddedObjDealloc<T,Embedded,DeallocDelete<T> >(
    embedded, prePostDestroy,DeallocDelete<T>());
}


template<class T, class Embedded >
EmbeddedObjDealloc<T,Embedded,DeallocArrayDelete<T> >
embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
{
  return EmbeddedObjDealloc<T,Embedded,DeallocArrayDelete<T> >(
    embedded, prePostDestroy,DeallocArrayDelete<T>());
}


template<class T> inline
RCP<T> rcp(T* p, bool owns_mem = true);


template<class T, class Dealloc_T> inline
RCP<T> rcpWithDealloc(T* p, Dealloc_T dealloc, bool owns_mem=true);


template<class T, class Dealloc_T> inline
RCP<T> rcp( T* p, Dealloc_T dealloc, bool owns_mem )
{
  return rcpWithDealloc(p, dealloc, owns_mem);
}


template<class T, class Dealloc_T> inline
RCP<T> rcpWithDeallocUndef(T* p, Dealloc_T dealloc, bool owns_mem=true);


template<class T> inline
RCP<T> rcpFromRef(T& r);


template<class T> inline
RCP<T> rcpFromUndefRef(T& r);


/* \brief Create an RCP with and also put in an embedded object.
 *
 * In this case the embedded object is destroyed (by setting to Embedded())
 * before the object at <tt>*p</tt> is destroyed.
 *
 * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
 * <tt>getNonconstEmbeddedObject()</tt>.
 *
 * \relates RCP
 */
template<class T, class Embedded> inline
RCP<T>
rcpWithEmbeddedObjPreDestroy( T* p, const Embedded &embedded, bool owns_mem = true );


/* \brief Create an RCP with and also put in an embedded object.
 *
 * In this case the embedded object is destroyed (by setting to Embedded())
 * after the object at <tt>*p</tt> is destroyed.
 *
 * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
 * <tt>getNonconstEmbeddedObject()</tt>.
 *
 * \relates RCP
 */
template<class T, class Embedded> inline
RCP<T>
rcpWithEmbeddedObjPostDestroy( T* p, const Embedded &embedded, bool owns_mem = true );


/* \brief Create an RCP with and also put in an embedded object.
 *
 * This function should be called when it is not important when the embedded
 * object is destroyed (by setting to Embedded()) with respect to when
 * <tt>*p</tt> is destroyed.
 *
 * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
 * <tt>getNonconstEmbeddedObject()</tt>.
 *
 * \relates RCP
 */
template<class T, class Embedded> inline
RCP<T>
rcpWithEmbeddedObj( T* p, const Embedded &embedded, bool owns_mem = true );


// 2007/10/25: rabartl: ToDo: put in versions of
// rcpWithEmbedded[Pre,Post]DestoryWithDealloc(...) that also accept a general
// deallocator!


template<class T, class ParentT>
RCP<T> rcpWithInvertedObjOwnership(const RCP<T> &child, const RCP<ParentT> &parent);


template<class T>
RCP<T> rcpCloneNode(const RCP<T> &p);


template<class T> inline
bool is_null( const RCP<T> &p );


template<class T> inline
bool nonnull( const RCP<T> &p );


template<class T> inline
bool operator==( const RCP<T> &p, ENull );


template<class T> inline
bool operator!=( const RCP<T> &p, ENull );


template<class T1, class T2> inline
bool operator==( const RCP<T1> &p1, const RCP<T2> &p2 );


template<class T1, class T2> inline
bool operator!=( const RCP<T1> &p1, const RCP<T2> &p2 );


template<class T2, class T1> inline
RCP<T2> rcp_implicit_cast(const RCP<T1>& p1);


template<class T2, class T1> inline
RCP<T2> rcp_static_cast(const RCP<T1>& p1);


template<class T2, class T1> inline
RCP<T2> rcp_const_cast(const RCP<T1>& p1);


template<class T2, class T1> inline
RCP<T2> rcp_dynamic_cast(
  const RCP<T1>& p1, bool throw_on_fail = false
  );


template<class T1, class T2>
void set_extra_data( const T1 &extra_data, const std::string& name,
  const Ptr<RCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
  bool force_unique = true);

template<class T1, class T2>
const T1& get_extra_data( const RCP<T2>& p, const std::string& name );


template<class T1, class T2>
T1& get_nonconst_extra_data( RCP<T2>& p, const std::string& name );


template<class T1, class T2>
Ptr<const T1> get_optional_extra_data( const RCP<T2>& p, const std::string& name );


template<class T1, class T2>
Ptr<T1> get_optional_nonconst_extra_data( RCP<T2>& p, const std::string& name );


template<class Dealloc_T, class T>
const Dealloc_T& get_dealloc( const RCP<T>& p );


template<class Dealloc_T, class T>
Dealloc_T& get_nonconst_dealloc( const RCP<T>& p );


template<class Dealloc_T, class T>
Ptr<const Dealloc_T> get_optional_dealloc( const RCP<T>& p );


template<class Dealloc_T, class T>
Ptr<Dealloc_T> get_optional_nonconst_dealloc( const RCP<T>& p );


template<class TOrig, class Embedded, class T>
const Embedded& getEmbeddedObj( const RCP<T>& p );


template<class TOrig, class Embedded, class T>
Embedded& getNonconstEmbeddedObj( const RCP<T>& p );


template<class TOrig, class Embedded, class T>
Ptr<const Embedded> getOptionalEmbeddedObj( const RCP<T>& p );


template<class TOrig, class Embedded, class T>
Ptr<Embedded> getOptionalNonconstEmbeddedObj( const RCP<T>& p );


template<class ParentT, class T>
RCP<ParentT> getInvertedObjOwnershipParent(const RCP<T> &invertedChild);


template<class T>
std::ostream& operator<<( std::ostream& out, const RCP<T>& p );


} // end namespace Teuchos


#endif  // TEUCHOS_RCP_DECL_HPP