TfRefPtr< T > Class Template Reference

Reference-counted smart pointer utility class. More...

Public Types
typedef T	DataType
	Convenience type accessor to underlying type T for template code. More...

Public Member Functions
	TfRefPtr ()
	Initialize pointer to nullptr. More...
	TfRefPtr (TfRefPtr< T > &&p)
	Moves the pointer managed by p to *this. More...
	TfRefPtr (const TfRefPtr< T > &p)
	Initializes *this to point at p's object. More...
template<template< class > class X, class U >
	TfRefPtr (const TfWeakPtrFacade< X, U > &p, typename boost::enable_if< boost::is_convertible< U *, T * > >::type *dummy=0)
	Initializes *this to point at gp's object. More...
template<class U >
	TfRefPtr (U *ptr, typename std::enable_if< std::is_convertible< U *, T * >::value >::type *=nullptr)
	Initializes to point at *ptr. More...
	TfRefPtr (TfNullPtrType)
	Implicit conversion from TfNullPtr to TfRefPtr. More...
	TfRefPtr (std::nullptr_t)
	Implicit conversion from nullptr to TfRefPtr. More...
TfRefPtr< T > &	operator= (const TfRefPtr< T > &p)
	Assigns pointer to point at p's object, and increments reference count. More...
TfRefPtr< T > &	operator= (TfRefPtr< T > &&p)
	Moves the pointer managed by p to *this and leaves p pointing at the NULL object. More...
	~TfRefPtr ()
	Decrements reference count of object being pointed to. More...
	TfRefPtr (const TfRefPtr< U > &p)
	Initializes to point at p's object, and increments reference count. More...
	TfRefPtr (TfRefPtr< U > &&p)
	Moves the pointer managed by p to *this and leaves p pointing at the NULL object. More...
TfRefPtr< T > &	operator= (const TfRefPtr< U > &p)
	Assigns pointer to point at p's object, and increments reference count. More...
TfRefPtr< T > &	operator= (TfRefPtr< U > &&p)
	Moves the pointer managed by p to *this and leaves p pointing at the NULL object. More...
bool	operator== (const TfRefPtr< U > &p) const
	Returns true if *this and p point to the same object (or if they both point to NULL). More...
bool	operator< (const TfRefPtr< U > &p) const
	Returns true if the address of the object pointed to by *this compares less than the address of the object pointed to by p. More...
bool	operator> (const TfRefPtr< U > &p) const
bool	operator<= (const TfRefPtr< U > &p) const
bool	operator>= (const TfRefPtr< U > &p) const
bool	operator!= (const TfRefPtr< U > &p) const
	Returns true if *this and p do not point to the same object. More...
T *	operator-> () const
	Accessor to T's public members. More...
T &	operator* () const
	Dereferences the stored pointer. More...
	operator UnspecifiedBoolType () const
	True if the pointer points to an object. More...
bool	operator! () const
	True if the pointer points to NULL. More...
void	swap (TfRefPtr &other)
	Swap this pointer with other. More...
void	Reset ()
	Set this pointer to point to no object. More...

Friends
class	TfWeakBase
TfRefPtr	TfCreateRefPtr (T *)
	Transfer a raw pointer to a reference-counted pointer. More...
template<class HashState , class U >
void	TfHashAppend (HashState &, const TfRefPtr< U > &)
template<class U >
size_t	hash_value (const TfRefPtr< U > &)
T *	get_pointer (TfRefPtr const &p)
template<class D >
TfRef< D >	TfDynamic_cast (const TfRefPtr< T > &)
	Allows dynamic casting of a TfRefPtr. More...
template<class D >
TfRefPtr< D >	TfStatic_cast (const TfRefPtr< T > &)
	Allows static casting of a TfRefPtr. More...
template<class D >
TfRefPtr< D >	TfConst_cast (const TfRefPtr< const D > &)
	Allows const casting of a TfRefPtr. More...
template<class U >
const std::type_info &	TfTypeid (const TfRefPtr< U > &ptr)
	Call typeid on the object pointed to by a TfRefPtr. More...

Detailed Description

template<class T>
class TfRefPtr< T >

Reference-counted smart pointer utility class.

The TfRefPtr class implements a reference counting on objects that inherit from TfRefBase.

For more information, see either the Quick Start example or read the detailed discussion.

Definition at line 37 of file refBase.h.

Member Typedef Documentation

typedef T DataType

Convenience type accessor to underlying type T for template code.

Definition at line 592 of file refPtr.h.

Constructor & Destructor Documentation

TfRefPtr ( )

inline

Initialize pointer to nullptr.

The default constructor leaves the pointer initialized to point to the NULL object. Attempts to use the -> operator will cause an abort until the pointer is given a value.

Definition at line 604 of file refPtr.h.

TfRefPtr ( TfRefPtr< T > &&  p )

inline

Moves the pointer managed by p to *this.

After construction, *this will point to the object p had been pointing at and p will be pointing at the NULL object. The reference count of the object being pointed at does not change.

Definition at line 614 of file refPtr.h.

TfRefPtr ( const TfRefPtr< T > &  p )

inline

Initializes *this to point at p's object.

Increments p's object's reference count.

Definition at line 624 of file refPtr.h.

TfRefPtr ( const TfWeakPtrFacade< X, U > &  p, typename boost::enable_if< boost::is_convertible< U *, T * > >::type *  dummy = 0  )

inline

Initializes *this to point at gp's object.

Increments gp's object's reference count.

Definition at line 365 of file weakPtrFacade.h.

TfRefPtr ( U *  ptr, typename std::enable_if< std::is_convertible< U *, T * >::value >::type *  = nullptr  )

inlineexplicit

Initializes to point at *ptr.

Increments *ptr's reference count. Note that newly constructed objects start with a reference count of one. Therefore, you should NOT use this constructor (either implicitly or explicitly) from within a New() function. Use TfCreateRefPtr() instead.

Definition at line 684 of file refPtr.h.

TfRefPtr ( TfNullPtrType  )

inline

Implicit conversion from TfNullPtr to TfRefPtr.

Definition at line 694 of file refPtr.h.

TfRefPtr ( std::nullptr_t  )

inline

Implicit conversion from nullptr to TfRefPtr.

Definition at line 700 of file refPtr.h.

~TfRefPtr ( )

inline

Decrements reference count of object being pointed to.

If the reference count of the object (if any) that was just pointed at reaches zero, the object will typically be destroyed at this point.

Definition at line 770 of file refPtr.h.

TfRefPtr ( const TfRefPtr< U > &  p )

inline

Initializes to point at p's object, and increments reference count.

This initialization is legal only if

*      U* uPtr;
*      T* tPtr = uPtr;
*  

is legal.

Definition at line 804 of file refPtr.h.

TfRefPtr ( TfRefPtr< U > &&  p )

inline

Moves the pointer managed by p to *this and leaves p pointing at the NULL object.

The reference count of the object being pointed to is not changed.

This initialization is legal only if

*      U* uPtr;
*      T* tPtr = uPtr;
*  

is legal.

Definition at line 827 of file refPtr.h.

Member Function Documentation

operator UnspecifiedBoolType ( ) const

inline

True if the pointer points to an object.

Definition at line 991 of file refPtr.h.

bool operator! ( ) const

inline

True if the pointer points to NULL.

Definition at line 996 of file refPtr.h.

bool operator!= ( const TfRefPtr< U > &  p ) const

inline

Returns true if *this and p do not point to the same object.

The comparison is legal only if a T* and a U* are comparable.

Definition at line 965 of file refPtr.h.

T& operator* ( ) const

inline

Dereferences the stored pointer.

Definition at line 982 of file refPtr.h.

T* operator-> ( ) const

inline

Accessor to T's public members.

Definition at line 973 of file refPtr.h.

bool operator< ( const TfRefPtr< U > &  p ) const

inline

Returns true if the address of the object pointed to by *this compares less than the address of the object pointed to by p.

The comparison is legal only if a T* and a U* are comparable.

Definition at line 922 of file refPtr.h.

TfRefPtr<T>& operator= ( const TfRefPtr< T > &  p )

inline

Assigns pointer to point at p's object, and increments reference count.

The object (if any) pointed at before the assignment has its reference count decremented, while the object newly pointed at has its reference count incremented. If the object previously pointed to now has nobody left to point at it, the object will typically be destroyed at this point.

An assignment

*      ptr = TfNullPtr;
*  

can be used to make ptr "forget" where it is pointing; note however that this has an important side effect, since it decrements the reference count of the object previously pointed to by ptr, possibly triggering destruction of that object.

Definition at line 723 of file refPtr.h.

TfRefPtr<T>& operator= ( TfRefPtr< T > &&  p )

inline

Moves the pointer managed by p to *this and leaves p pointing at the NULL object.

The object (if any) pointed at before the assignment has its reference count decremented, while the reference count of the object newly pointed at is not changed.

Definition at line 751 of file refPtr.h.

TfRefPtr<T>& operator= ( const TfRefPtr< U > &  p )

inline

Assigns pointer to point at p's object, and increments reference count.

This assignment is legal only if

*      U* uPtr;
*      T* tPtr;
*      tPtr = uPtr;
*  

is legal.

Definition at line 852 of file refPtr.h.

TfRefPtr<T>& operator= ( TfRefPtr< U > &&  p )

inline

Moves the pointer managed by p to *this and leaves p pointing at the NULL object.

The reference count of the object being pointed to is not changed.

This assignment is legal only if

*      U* uPtr;
*      T* tPtr;
*      tPtr = uPtr;
*  

is legal.

Definition at line 882 of file refPtr.h.

bool operator== ( const TfRefPtr< U > &  p ) const

inline

Returns true if *this and p point to the same object (or if they both point to NULL).

The comparison is legal only if a T* and a U* are comparable.

Definition at line 908 of file refPtr.h.

void Reset ( )

inline

Set this pointer to point to no object.

Equivalent to assignment with TfNullPtr.

Definition at line 1014 of file refPtr.h.

void swap ( TfRefPtr< T > &  other )

inline

Swap this pointer with other.

After this operation, this pointer will point to what other formerly pointed to, and other will point to what this pointer formerly pointed to.

Definition at line 1004 of file refPtr.h.

Friends And Related Function Documentation

TfRefPtr<D> TfConst_cast ( const TfRefPtr< const D > &  )

friend

Allows const casting of a TfRefPtr.

The following is always legal:

*      TfRefPtr<const T> cPtr = ...;
*      TfRefPtr<T>       tPtr;
* 
*      tPtr = TfConst_cast< TfRefPtr<T> >(cPtr);
*  

As with the C++ const_cast operator, use of this function is discouraged.

TfRefPtr TfCreateRefPtr ( T *  )

friend

Transfer a raw pointer to a reference-counted pointer.

The TfCreateRefPtr() function should only be used from within a static New() function (or similarly, a Clone() function) of a reference-counted class. Reference-counted objects have their reference count initially set to one to account for the fact that a newly created object must always persist at least until its New() function returns. Therefore, the transfer of the pointer returned by new into a reference pointer must not increase the reference count. The transfer of the raw pointer returned by new into the object returned by New() is a "transfer of ownership" and does not represent an additional reference to the object.

In summary, this code is wrong, and will return an object that can never be destroyed:

*      SimpleRefPtr Simple::New() {
*          return SimpleRefPtr(new Simple);      // legal, but leaks memory: beware!!
*      }
*  

The correct form is

*      SimpleRefPtr Simple::New() {
*          return TfCreateRefPtr(new Simple);
*      }
*  

Note also that a function which is essentially like New(), for example Clone(), would also want to use TfCreateRefPtr().

TfRef<D> TfDynamic_cast ( const TfRefPtr< T > &  )

friend

Allows dynamic casting of a TfRefPtr.

If it is legal to dynamically cast a T* to a D* , then the following is also legal:

*      TfRefPtr<T> tPtr = ... ;
*      TfRefPtr<D> dPtr;
* 
*      if (!(dPtr = TfDynamic_cast< TfRefPtr<D> >(tPtr)))
*          ...;       // cast failed
*  

The runtime performance of this function is exactly the same as a dynamic_cast (i.e. one virtual function call). If the pointer being cast is NULL or does not point to an object of the requisite type, the result is a TfRefPtr pointing to NULL.

TfRefPtr<D> TfStatic_cast ( const TfRefPtr< T > &  )

friend

Allows static casting of a TfRefPtr.

If it is legal to statically cast a T* to a D* , then the following is also legal:

*      TfRefPtr<T> tPtr = ... ;
*      TfRefPtr<D> dPtr;
* 
*      dPtr = TfStatic_cast< TfRefPtr<D> >(tPtr);
*  

The runtime performance of this function is exactly the same as a regular TfRefPtr initialization, since the cost of the underlying static_cast is zero. Of course, a TfDynamic_cast is preferred, assuming the underlying types are polymorphic (i.e. have virtual functions).

const std::type_info& TfTypeid ( const TfRefPtr< U > &  ptr )

friend

Call typeid on the object pointed to by a TfRefPtr.

If ptr is a TfRefPtr, typeid(ptr) will return type information about the TfRefPtr. To access type information about the object pointed to by a TfRefPtr, one can use TfTypeid.

---

The documentation for this class was generated from the following files:

• pxr/base/tf/refBase.h
• pxr/base/tf/refPtr.h
• pxr/base/tf/weakPtrFacade.h