All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 TfHash
 
class TfWeakBase
 
TfRefPtr TfCreateRefPtr (T *)
 Transfer a raw pointer to a reference-counted pointer. More...
 
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 45 of file hash.h.

Member Typedef Documentation

typedef T DataType

Convenience type accessor to underlying type T for template code.

Definition at line 593 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 605 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 615 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 625 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 368 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 685 of file refPtr.h.

TfRefPtr ( TfNullPtrType  )
inline

Implicit conversion from TfNullPtr to TfRefPtr.

Definition at line 695 of file refPtr.h.

TfRefPtr ( std::nullptr_t  )
inline

Implicit conversion from nullptr to TfRefPtr.

Definition at line 701 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 771 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 805 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 828 of file refPtr.h.

Member Function Documentation

operator UnspecifiedBoolType ( ) const
inline

True if the pointer points to an object.

Definition at line 992 of file refPtr.h.

bool operator! ( ) const
inline

True if the pointer points to NULL.

Definition at line 997 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 966 of file refPtr.h.

T& operator* ( ) const
inline

Dereferences the stored pointer.

Definition at line 983 of file refPtr.h.

T* operator-> ( ) const
inline

Accessor to T's public members.

Definition at line 974 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 923 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 724 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 752 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 853 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 883 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 909 of file refPtr.h.

void Reset ( )
inline

Set this pointer to point to no object.

Equivalent to assignment with TfNullPtr.

Definition at line 1015 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 1005 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: