This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
TfRefPtr< T > Class Template Reference

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

#include <refPtr.h>

Public Types

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

Public Member Functions

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

Friends

class TfWeakBase
 
TfRefPtr TfCreateRefPtr (T *)
 Transfer a raw pointer to a reference-counted pointer.
 
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 >
TfRefPtr< D > TfDynamic_cast (const TfRefPtr< T > &)
 Allows dynamic casting of a TfRefPtr.
 
template<class D >
TfRefPtr< D > TfStatic_cast (const TfRefPtr< T > &)
 Allows static casting of a TfRefPtr.
 
template<class D >
TfRefPtr< D > TfConst_cast (const TfRefPtr< const D > &)
 Allows const casting of a TfRefPtr.
 
template<class U >
const std::type_info & TfTypeid (const TfRefPtr< U > &ptr)
 Call typeid on the object pointed to by a TfRefPtr.
 

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 590 of file refPtr.h.

Member Typedef Documentation

◆ DataType

typedef T DataType

Convenience type accessor to underlying type T for template code.

Definition at line 602 of file refPtr.h.

Constructor & Destructor Documentation

◆ TfRefPtr() [1/9]

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 614 of file refPtr.h.

◆ TfRefPtr() [2/9]

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 624 of file refPtr.h.

◆ TfRefPtr() [3/9]

TfRefPtr ( const TfRefPtr< T > &  p)
inline

Initializes *this to point at p's object.

Increments p's object's reference count.

Definition at line 633 of file refPtr.h.

◆ TfRefPtr() [4/9]

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

Initializes *this to point at gp's object.

Increments gp's object's reference count.

Definition at line 345 of file weakPtrFacade.h.

◆ TfRefPtr() [5/9]

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 693 of file refPtr.h.

◆ TfRefPtr() [6/9]

TfRefPtr ( TfNullPtrType  )
inline

Implicit conversion from TfNullPtr to TfRefPtr.

Definition at line 703 of file refPtr.h.

◆ TfRefPtr() [7/9]

TfRefPtr ( std::nullptr_t  )
inline

Implicit conversion from nullptr to TfRefPtr.

Definition at line 709 of file refPtr.h.

◆ ~TfRefPtr()

~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 776 of file refPtr.h.

◆ TfRefPtr() [8/9]

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 792 of file refPtr.h.

◆ TfRefPtr() [9/9]

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 811 of file refPtr.h.

Member Function Documentation

◆ operator UnspecifiedBoolType()

operator UnspecifiedBoolType ( ) const
inline

True if the pointer points to an object.

Definition at line 946 of file refPtr.h.

◆ operator!()

bool operator! ( ) const
inline

True if the pointer points to NULL.

Definition at line 951 of file refPtr.h.

◆ operator!=()

auto operator!= ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() != std::declval<U *>(), bool())
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 886 of file refPtr.h.

◆ operator*()

T & operator* ( ) const
inline

Dereferences the stored pointer.

Definition at line 937 of file refPtr.h.

◆ operator->()

T * operator-> ( ) const
inline

Accessor to T's public members.

Definition at line 928 of file refPtr.h.

◆ operator<()

auto operator< ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() < std::declval<U *>(), bool())
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 898 of file refPtr.h.

◆ operator<=()

auto operator<= ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() <= std::declval<U *>(), bool())
inline

Definition at line 914 of file refPtr.h.

◆ operator=() [1/4]

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 732 of file refPtr.h.

◆ operator=() [2/4]

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 831 of file refPtr.h.

◆ operator=() [3/4]

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 759 of file refPtr.h.

◆ operator=() [4/4]

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 856 of file refPtr.h.

◆ operator==()

auto operator== ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() == std::declval<U *>(), bool())
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 875 of file refPtr.h.

◆ operator>()

auto operator> ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() > std::declval<U *>(), bool())
inline

Definition at line 906 of file refPtr.h.

◆ operator>=()

auto operator>= ( const TfRefPtr< U > &  p) const -> decltype(std::declval<T *>() >= std::declval<U *>(), bool())
inline

Definition at line 922 of file refPtr.h.

◆ Reset()

void Reset ( )
inline

Set this pointer to point to no object.

Equivalent to assignment with TfNullPtr.

Definition at line 967 of file refPtr.h.

◆ swap()

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 959 of file refPtr.h.

Friends And Related Function Documentation

◆ get_pointer

T * get_pointer ( TfRefPtr< T > const &  p)
friend

Definition at line 979 of file refPtr.h.

◆ TfConst_cast

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

Allows const casting of a TfRefPtr.

The following is always legal:

TfRefPtr<const T> cPtr = ...;
tPtr = TfConst_cast< TfRefPtr<T> >(cPtr);
Reference-counted smart pointer utility class.
Definition: refPtr.h:590

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

◆ TfCreateRefPtr

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);
}
friend TfRefPtr TfCreateRefPtr(T *)
Transfer a raw pointer to a reference-counted pointer.

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

◆ TfDynamic_cast

TfRefPtr< 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 = ... ;
if (!(dPtr = TfDynamic_cast< TfRefPtr<D> >(tPtr)))
...; // cast failed
friend TfRefPtr< D > TfDynamic_cast(const TfRefPtr< T > &)
Allows dynamic casting of a TfRefPtr.

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.

◆ TfStatic_cast

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

◆ TfTypeid

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.

◆ TfWeakBase

friend class TfWeakBase
friend

Definition at line 1110 of file refPtr.h.


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