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.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// 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);

  inline RCP(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=(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 explicit operator bool() 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;

#if defined(HAVE_TEUCHOSCORE_CXX11) && defined(HAVE_TEUCHOS_THREAD_SAFE)

  inline RCP<T> create_strong_thread_safe() const; // this format to be determined
#endif

  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);


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

};

struct RCPComp {
  template<class T1, class T2> inline
  bool operator() (const RCP<T1> p1, const RCP<T2> p2) const{
    return p1.get() < p2.get();
  }
};

struct RCPConstComp {
  template<class T1, class T2> inline
  bool operator() (const RCP<const T1> p1, const RCP<const T2> p2) const{
    return p1.get() < p2.get();
  }
};



// 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 ) {
    (void) ptr; // silence "unused parameter" compiler warning
  }
};


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
TEUCHOS_DEPRECATED 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);


template<class T, class Embedded> inline
RCP<T>
rcpWithEmbeddedObjPreDestroy( T* p, const Embedded &embedded, bool owns_mem = true );


template<class T, class Embedded> inline
RCP<T>
rcpWithEmbeddedObjPostDestroy( T* p, const Embedded &embedded, bool owns_mem = true );


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