Teuchos_RCPNode.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_NODE_HPP
#define TEUCHOS_RCP_NODE_HPP


#include "Teuchos_ConfigDefs.hpp"
#include "Teuchos_any.hpp"
#include "Teuchos_map.hpp"
#include "Teuchos_ENull.hpp"
#include "Teuchos_Assert.hpp"
#include "Teuchos_Exceptions.hpp"
#include "Teuchos_TypeNameTraits.hpp"
#include "Teuchos_toString.hpp"
#include "Teuchos_getBaseObjVoidPtr.hpp"


namespace Teuchos {


enum EPrePostDestruction { PRE_DESTROY, POST_DESTROY };

enum ERCPStrength { RCP_STRENGTH_INVALID=-1, RCP_STRONG=0, RCP_WEAK=1 };

enum ERCPNodeLookup { RCP_ENABLE_NODE_LOOKUP, RCP_DISABLE_NODE_LOOKUP };

inline void debugAssertStrength(ERCPStrength strength)
{
#ifdef TEUCHOS_DEBUG
  switch (strength) {
    case RCP_STRONG:
      // fall through
    case RCP_WEAK:
      return; // Fine
    case RCP_STRENGTH_INVALID:
    default:
      TEST_FOR_EXCEPT(true);
  }
#endif
}

template<>
class TEUCHOS_LIB_DLL_EXPORT ToStringTraits<ERCPStrength> {
public:
  static std::string toString( const ERCPStrength &t )
    {
      switch (t) {
        case RCP_STRENGTH_INVALID:
          return "RCP_STRENGTH_INVALID";
        case RCP_STRONG:
          return "RCP_STRONG";
        case RCP_WEAK:
          return "RCP_STRONG";
        default:
          // Should never get here but fall through ...
          break;
      }
      // Should never get here!
#ifdef TEUCHOS_DEBUG
      TEST_FOR_EXCEPT(true);
#endif
      return "";
      // 2009/06/30: rabartl: The above logic avoid a warning from the Intel
      // 10.1 compiler (remark #111) about the statement being unreachable.
    }
};


class TEUCHOS_LIB_DLL_EXPORT RCPNode {
public:
  RCPNode(bool has_ownership_in)
    : has_ownership_(has_ownership_in), extra_data_map_(NULL)
#ifdef TEUCHOS_DEBUG
    ,insertion_number_(-1)
#endif // TEUCHOS_DEBUG
    {
      count_[RCP_STRONG] = 0;
      count_[RCP_WEAK] = 0;
    }
  virtual ~RCPNode()
    {
      if(extra_data_map_)
        delete extra_data_map_;
    }
  int strong_count() const
    {
      return count_[RCP_STRONG]; 
    }
  int weak_count() const
    {
      return count_[RCP_WEAK];
    }
  int count( const ERCPStrength strength )
    {
      debugAssertStrength(strength);
      return count_[strength];
    }
  int incr_count( const ERCPStrength strength )
    {
      debugAssertStrength(strength);
      return ++count_[strength];
    }
  int deincr_count( const ERCPStrength strength )
    {
      debugAssertStrength(strength);
      return --count_[strength];
    }
  void has_ownership(bool has_ownership_in)
    {
      has_ownership_ = has_ownership_in;
    }
  bool has_ownership() const
    {
      return has_ownership_;
    }
  void set_extra_data(
    const any &extra_data, const std::string& name,
    EPrePostDestruction destroy_when, bool force_unique );
  any& get_extra_data( const std::string& type_name,
    const std::string& name );
  const any& get_extra_data( const std::string& type_name,
    const std::string& name
    ) const
    {
      return const_cast<RCPNode*>(this)->get_extra_data(type_name, name);
    }
  any* get_optional_extra_data(const std::string& type_name,
    const std::string& name );
  const any* get_optional_extra_data(
    const std::string& type_name, const std::string& name
    ) const
    {
      return const_cast<RCPNode*>(this)->get_optional_extra_data(type_name, name);
    }
  virtual bool is_valid_ptr() const = 0;
  virtual void delete_obj() = 0;
  virtual void throw_invalid_obj_exception(
    const std::string& rcp_type_name,
    const void* rcp_ptr,
    const RCPNode* rcp_node_ptr,
    const void* rcp_obj_ptr
    ) const = 0;
  virtual const std::string get_base_obj_type_name() const = 0;
#ifdef TEUCHOS_DEBUG

  virtual const void* get_base_obj_map_key_void_ptr() const = 0;
#endif
protected:
  void pre_delete_extra_data()
    {
      if(extra_data_map_)
        impl_pre_delete_extra_data();
    }
private:
  struct extra_data_entry_t {
    extra_data_entry_t() : destroy_when(POST_DESTROY) {}
    extra_data_entry_t( const any &_extra_data, EPrePostDestruction _destroy_when )
      : extra_data(_extra_data), destroy_when(_destroy_when)
      {}
    any extra_data;
    EPrePostDestruction destroy_when;
  }; 
  typedef Teuchos::map<std::string,extra_data_entry_t> extra_data_map_t;
  int count_[2];
  bool has_ownership_;
  extra_data_map_t *extra_data_map_;
  // Above is made a pointer to reduce overhead for the general case when this
  // is not used.  However, this adds just a little bit to the overhead when
  // it is used.
  // Provides the "basic" guarantee!
  void impl_pre_delete_extra_data();
  // Not defined and not to be called
  RCPNode();
  RCPNode(const RCPNode&);
  RCPNode& operator=(const RCPNode&);
#ifdef TEUCHOS_DEBUG
  int insertion_number_;
public:
  void set_insertion_number(int insertion_number_in)
    {
      insertion_number_ = insertion_number_in;
    }
  int insertion_number() const
    {
      return insertion_number_;
    }
#endif // TEUCHOS_DEBUG
};


TEUCHOS_LIB_DLL_EXPORT void throw_null_ptr_error( const std::string &type_name );


class RCPNodeTracer {
public:


  struct RCPNodeStatistics {
    RCPNodeStatistics()
      : maxNumRCPNodes(0), totalNumRCPNodeAllocations(0),
        totalNumRCPNodeDeletions(0)
      {}
    long int maxNumRCPNodes;
    long int totalNumRCPNodeAllocations;
    long int totalNumRCPNodeDeletions;
  };



  static TEUCHOS_LIB_DLL_EXPORT bool isTracingActiveRCPNodes();

#if defined(TEUCHOS_DEBUG) && !defined(HAVE_TEUCHOS_DEBUG_RCP_NODE_TRACING)

  static TEUCHOS_LIB_DLL_EXPORT void setTracingActiveRCPNodes(bool tracingActiveNodes);
#endif

  static TEUCHOS_LIB_DLL_EXPORT int numActiveRCPNodes();

  static TEUCHOS_LIB_DLL_EXPORT RCPNodeStatistics getRCPNodeStatistics() ;

  static TEUCHOS_LIB_DLL_EXPORT void printRCPNodeStatistics(
    const RCPNodeStatistics& rcpNodeStatistics, std::ostream &out);

  static TEUCHOS_LIB_DLL_EXPORT void setPrintRCPNodeStatisticsOnExit(
    bool printRCPNodeStatisticsOnExit);

  static TEUCHOS_LIB_DLL_EXPORT bool getPrintRCPNodeStatisticsOnExit();

  static TEUCHOS_LIB_DLL_EXPORT void printActiveRCPNodes(std::ostream &out);



  static TEUCHOS_LIB_DLL_EXPORT void addNewRCPNode(RCPNode* rcp_node,
    const std::string &info );

  static TEUCHOS_LIB_DLL_EXPORT void removeRCPNode( RCPNode* rcp_node );

  template<class T>
  static const void* getRCPNodeBaseObjMapKeyVoidPtr(T *p)
    {
#ifdef HAS_TEUCHOS_GET_BASE_OBJ_VOID_PTR
      return getBaseObjVoidPtr(p);
#else
      // This will not return the base address for polymorphic types if
      // multiple inheritance and/or virtual bases are used but returning the
      // static_cast should be okay in how it is used.  It is just that the
      // RCPNode tracing support will not always be able to figure out if two
      // pointers of different type are pointing to the same object or not.
      return static_cast<const void*>(p);
#endif
    }

  static TEUCHOS_LIB_DLL_EXPORT RCPNode* getExistingRCPNodeGivenLookupKey(
    const void* lookupKey);

  template<class T>
  static RCPNode* getExistingRCPNode(T *p)
    {
      return getExistingRCPNodeGivenLookupKey(getRCPNodeBaseObjMapKeyVoidPtr(p));
    }

  static TEUCHOS_LIB_DLL_EXPORT std::string getActiveRCPNodeHeaderString();

  static TEUCHOS_LIB_DLL_EXPORT std::string getCommonDebugNotesString();


};


#ifdef TEUCHOS_DEBUG
#  define TEUCHOS_RCP_INSERION_NUMBER_STR() \
      "  insertionNumber:      " << rcp_node_ptr->insertion_number() << "\n"
#else
#  define TEUCHOS_RCP_INSERION_NUMBER_STR()
#endif


template<class T, class Dealloc_T>
class RCPNodeTmpl : public RCPNode {
public:
  RCPNodeTmpl(T* p, Dealloc_T dealloc, bool has_ownership_in)
    : RCPNode(has_ownership_in), ptr_(p),
#ifdef TEUCHOS_DEBUG
      base_obj_map_key_void_ptr_(RCPNodeTracer::getRCPNodeBaseObjMapKeyVoidPtr(p)),
      deleted_ptr_(0),
#endif
      dealloc_(dealloc)
    {}
  RCPNodeTmpl(T* p, Dealloc_T dealloc, bool has_ownership_in, ENull)
    : RCPNode(has_ownership_in), ptr_(p),
#ifdef TEUCHOS_DEBUG
      base_obj_map_key_void_ptr_(0),
      deleted_ptr_(0),
#endif
      dealloc_(dealloc)
    {}
  Dealloc_T& get_nonconst_dealloc()
    { return dealloc_; }
  const Dealloc_T& get_dealloc() const
    { return dealloc_; }
  ~RCPNodeTmpl()
    {
#ifdef TEUCHOS_DEBUG
      TEST_FOR_EXCEPTION( ptr_!=0, std::logic_error,
        "Error, the underlying object must be explicitly deleted before deleting"
        " the node object!" );
#endif
    }
  virtual bool is_valid_ptr() const
    {
      return ptr_ != 0;
    }
  virtual void delete_obj()
    {
      if (ptr_!= 0) {
        this->pre_delete_extra_data(); // May throw!
        T* tmp_ptr = ptr_;
#ifdef TEUCHOS_DEBUG
        deleted_ptr_ = tmp_ptr;
#endif
        ptr_ = 0;
        if (has_ownership()) {
#ifdef TEUCHOS_DEBUG
          try {
#endif
            dealloc_.free(tmp_ptr);
#ifdef TEUCHOS_DEBUG
          }
          catch(...) {
            // Object was not deleted due to an exception!
            ptr_ = tmp_ptr;
            throw;
          }
#endif
        }
        // 2008/09/22: rabartl: Above, we have to be careful to set the member
        // this->ptr_=0 before calling delete on the object's address in order
        // to avoid a double call to delete in cases of circular references
        // involving weak and strong pointers (see the unit test
        // circularReference_c_then_a in RCP_UnitTests.cpp).  NOTE: It is
        // critcial that no member of *this get accesses after
        // dealloc_.free(...) gets called!  Also, in order to provide the
        // "strong" guarantee we have to include the above try/catch.  This
        // overhead is unfortunate but I don't know of any other way to
        // statisfy the "strong" guarantee and still avoid a double delete.
      }
    }
  virtual void throw_invalid_obj_exception(
    const std::string& rcp_type_name,
    const void* rcp_ptr,
    const RCPNode* rcp_node_ptr,
    const void* rcp_obj_ptr
    ) const
    {
      TEST_FOR_EXCEPT_MSG( ptr_!=0, "Internal coding error!" );
      const T* deleted_ptr =
#ifdef TEUCHOS_DEBUG
        deleted_ptr_
#else
        0
#endif
        ;
      TEUCHOS_ASSERT(rcp_node_ptr);
      TEST_FOR_EXCEPTION( true, DanglingReferenceError,
        "Error, an attempt has been made to dereference the underlying object\n"
        "from a weak smart pointer object where the underling object has already\n"
        "been deleted since the strong count has already gone to zero.\n"
        "\n"
        "Context information:\n"
        "\n"
        "  RCP type:             " << rcp_type_name << "\n"
        "  RCP address:          " << rcp_ptr << "\n"
        "  RCPNode type:         " << typeName(*this) << "\n"
        "  RCPNode address:      " << rcp_node_ptr << "\n"
        TEUCHOS_RCP_INSERION_NUMBER_STR()
        "  RCP ptr address:      " << rcp_obj_ptr << "\n"
        "  Concrete ptr address: " << deleted_ptr << "\n"
        "\n"
        << RCPNodeTracer::getCommonDebugNotesString()
        );
      // 2008/09/22: rabartl: Above, we do not provide the concreate object
      // type or the concrete object address.  In the case of the concrete
      // object address, in a non-debug build, we don't want to pay a price
      // for extra storage that we strictly don't need.  In the case of the
      // concrete object type name, we don't want to force non-debug built
      // code to have the require that types be fully defined in order to use
      // the memory management software.  This is related to bug 4016.

    }
  const std::string get_base_obj_type_name() const
    {
#ifdef TEUCHOS_DEBUG
      return TypeNameTraits<T>::name();
#else
      return "UnknownType";
#endif
    }
#ifdef TEUCHOS_DEBUG

  const void* get_base_obj_map_key_void_ptr() const
    {
      return base_obj_map_key_void_ptr_;
    }
#endif
private:
  T *ptr_;
#ifdef TEUCHOS_DEBUG
  const void *base_obj_map_key_void_ptr_;
  T *deleted_ptr_;
#endif
  Dealloc_T dealloc_;
  // not defined and not to be called
  RCPNodeTmpl();
  RCPNodeTmpl(const RCPNodeTmpl&);
  RCPNodeTmpl& operator=(const RCPNodeTmpl&);

}; // end class RCPNodeTmpl<T>


class TEUCHOS_LIB_DLL_EXPORT ActiveRCPNodesSetup {
public:
  ActiveRCPNodesSetup();
  ~ActiveRCPNodesSetup();
  void foo();
private:
  static int count_;
};


} // namespace Teuchos


namespace {
// This static variable is delcared before all other static variables that
// depend on RCP or other classes. Therefore, this static varaible will be
// deleted *after* all of these other static variables that depend on RCP or
// created classes go away!  This ensures that the node tracing machinery is
// setup and torn down correctly (this is the same trick used by the standard
// stream objects in many compiler implementations).
Teuchos::ActiveRCPNodesSetup local_activeRCPNodesSetup;
} // namespace


namespace Teuchos {


class TEUCHOS_LIB_DLL_EXPORT RCPNodeHandle {
public:
  RCPNodeHandle(ENull null_arg = null)
    : node_(0), strength_(RCP_STRENGTH_INVALID)
    {(void)null_arg;}
  RCPNodeHandle( RCPNode* node, ERCPStrength strength_in = RCP_STRONG,
    bool newNode = true
    )
    : node_(node), strength_(strength_in)
    {
#ifdef TEUCHOS_DEBUG
      TEUCHOS_ASSERT(node);
#endif
      bind();
#ifdef TEUCHOS_DEBUG
      // Add the node if this is the first RCPNodeHandle to get it.  We have
      // to add it because unbind() will call the remove_RCPNode(...) function
      // and it needs to match when node tracing is on from the beginning.
      if (RCPNodeTracer::isTracingActiveRCPNodes() && newNode)
      {
        std::ostringstream os;
        os << "{T=Unknown, ConcreteT=Unknown, p=Unknown,"
           << " has_ownership="<<node_->has_ownership()<<"}";
        RCPNodeTracer::addNewRCPNode(node_, os.str());
      }
#endif
    }
#ifdef TEUCHOS_DEBUG

  template<typename T>
  RCPNodeHandle(RCPNode* node, T *p, const std::string &T_name,
    const std::string &ConcreteT_name, const bool has_ownership_in,
    ERCPStrength strength_in = RCP_STRONG
    )
    : node_(node), strength_(strength_in)
    {
      TEUCHOS_ASSERT(strength_in == RCP_STRONG); // Can't handle weak yet!
      TEUCHOS_ASSERT(node_);
      bind();
      if (RCPNodeTracer::isTracingActiveRCPNodes()) {
        std::ostringstream os;
        os << "{T="<<T_name<<", ConcreteT="<< ConcreteT_name
           <<", p="<<static_cast<const void*>(p)
           <<", has_ownership="<<has_ownership_in<<"}";
        RCPNodeTracer::addNewRCPNode(node_, os.str());
      }
    }
#endif // TEUCHOS_DEBUG

  RCPNodeHandle(const RCPNodeHandle& node_ref)
    : node_(node_ref.node_), strength_(node_ref.strength_)
    {
      bind();
    }
  void swap( RCPNodeHandle& node_ref )
    {
      std::swap(node_ref.node_, node_);
      std::swap(node_ref.strength_, strength_);
    }
  RCPNodeHandle& operator=(const RCPNodeHandle& node_ref)
    {
      // Assignment to self check: Note, We don't need to do an assigment to
      // self check here because such a check is already done in the RCP and
      // ArrayRCP classes.
      // Take care of this's existing node and object
      unbind(); // May throw in some cases
      // Assign the new node
      node_ = node_ref.node_;
      strength_ = node_ref.strength_;
      bind();
      // Return
      return *this;
    }
  ~RCPNodeHandle()
    {
      unbind();
    }
  RCPNodeHandle create_weak() const
    {
      if (node_) {
        return RCPNodeHandle(node_, RCP_WEAK, false);
      }
      return RCPNodeHandle();
    }
  RCPNodeHandle create_strong() const
    {
      if (node_) {
        return RCPNodeHandle(node_, RCP_STRONG, false);
      }
      return RCPNodeHandle();
    }
  RCPNode* node_ptr() const
    {
      return node_;
    }
  bool is_node_null() const
    {
      return node_==0;
    }
  bool is_valid_ptr() const
    {
      if (node_)
        return node_->is_valid_ptr();
      return true; // Null is a valid ptr!
    }
  bool same_node(const RCPNodeHandle &node2) const
    {
      return node_ == node2.node_;
    }
  int strong_count() const
    {
      if (node_)
        return node_->strong_count(); 
      return 0;
    }
  int weak_count() const
    {
      if (node_)
        return node_->weak_count(); 
      return 0;
    }
  int total_count() const
    {
      if (node_)
        return node_->strong_count() + node_->weak_count(); 
      return 0;
    }
  int count() const
    {
      if (node_)
        return node_->strong_count(); 
      return 0;
    }
  ERCPStrength strength() const
    {
      return strength_;
    }
  void has_ownership(bool has_ownership_in)
    {
      if (node_)
        node_->has_ownership(has_ownership_in);
    }
  bool has_ownership() const
    {
      if (node_)
        return node_->has_ownership();
      return false;
    }
  void set_extra_data(
    const any &extra_data, const std::string& name,
    EPrePostDestruction destroy_when, bool force_unique
    )
    {
      debug_assert_not_null();
      node_->set_extra_data(extra_data, name, destroy_when, force_unique);
    }
  any& get_extra_data( const std::string& type_name,
    const std::string& name
    )
    {
      debug_assert_not_null();
      return node_->get_extra_data(type_name, name);
    } 
  const any& get_extra_data( const std::string& type_name,
    const std::string& name 
    ) const
    {
      return const_cast<RCPNodeHandle*>(this)->get_extra_data(type_name, name);
    }
  any* get_optional_extra_data(
    const std::string& type_name, const std::string& name
    )
    {
      debug_assert_not_null();
      return node_->get_optional_extra_data(type_name, name);
    } 
  const any* get_optional_extra_data(
    const std::string& type_name, const std::string& name
    ) const
    {
      return const_cast<RCPNodeHandle*>(this)->get_optional_extra_data(type_name, name);
    }
  void debug_assert_not_null() const
    {
#ifdef TEUCHOS_DEBUG
      if (!node_)
        throw_null_ptr_error(typeName(*this));
#endif
    }
  template<class RCPType>
  void assert_valid_ptr(const RCPType& rcp_obj) const
    {
      if (!node_)
        return; // Null is a valid pointer!
      if (!is_valid_ptr()) {
        node_->throw_invalid_obj_exception( typeName(rcp_obj),
          this, node_, rcp_obj.access_private_ptr() );
      }
    }
  template<class RCPType>
  void debug_assert_valid_ptr(const RCPType& rcp_obj) const
    {
#ifdef TEUCHOS_DEBUG
      assert_valid_ptr(rcp_obj);
#endif
    }
#ifdef TEUCHOS_DEBUG
  const void* get_base_obj_map_key_void_ptr() const
    {
      if (node_)
        return node_->get_base_obj_map_key_void_ptr();
      return 0;
    }
#endif
private:
  RCPNode *node_;
  ERCPStrength strength_;
  inline void bind()
    {
      if (node_)
        node_->incr_count(strength_);
    }
  inline void unbind() 
    {
      // Optimize this implementation for count > 1
      if (node_ && node_->deincr_count(strength_)==0) {
        // If we get here, the reference count has gone to 0 and something
        // interesting is going to happen.  In this case, we need to
        // reincrement the count back to 1 and call the more complex function
        // that will either delete the object or delete the node.
        node_->incr_count(strength_);
        unbindOne();
      }
      // If we get here, either node_==0 or the count is still greater than 0.
      // In this case, nothing interesting is going to happen so we are done!
    }
  void unbindOne(); // Provides the "strong" guarantee!

};


inline
std::ostream& operator<<(std::ostream& out, const RCPNodeHandle& node)
{
  return (out << node.node_ptr());
}


class TEUCHOS_LIB_DLL_EXPORT RCPNodeThrowDeleter {
public:
  RCPNodeThrowDeleter(RCPNode *node)
    : node_(node)
    {}
  ~RCPNodeThrowDeleter()
    {
      if (node_) {
        node_->has_ownership(false); // Avoid actually deleting ptr_
        node_->delete_obj(); // Sets the pointer ptr_=0 to allow RCPNode delete
        delete node_;
      }
    }
  RCPNode* get() const
    {
      return node_;
    }
  void release()
    {
      node_ = 0;
    }
private:
  RCPNode *node_;
  RCPNodeThrowDeleter(); // Not defined
  RCPNodeThrowDeleter(const RCPNodeThrowDeleter&); // Not defined
  RCPNodeThrowDeleter& operator=(const RCPNodeThrowDeleter&); // Not defined
};


//
// Unit testing support
//


#if defined(TEUCHOS_DEBUG) && !defined(HAVE_TEUCHOS_DEBUG_RCP_NODE_TRACING)

class SetTracingActiveNodesStack {
public: 
  SetTracingActiveNodesStack()
    {RCPNodeTracer::setTracingActiveRCPNodes(true);}
  ~SetTracingActiveNodesStack()
    {RCPNodeTracer::setTracingActiveRCPNodes(false);}
};

#  define SET_RCPNODE_TRACING() Teuchos::SetTracingActiveNodesStack setTracingActiveNodesStack;

#else

#  define SET_RCPNODE_TRACING() (void)0

#endif //  defined(TEUCHOS_DEBUG) && !defined(HAVE_TEUCHOS_DEBUG_RCP_NODE_TRACING)


} // end namespace Teuchos


#endif // TEUCHOS_RCP_NODE_HPP