HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TfWeakPtr< T > Class Template Reference

#include <refBase.h>

+ Inheritance diagram for TfWeakPtr< T >:

Classes

struct  Rebind
 

Public Member Functions

 TfWeakPtr ()
 
 TfWeakPtr (TfNullPtrType)
 Construction, implicit conversion from TfNullPtr. More...
 
 TfWeakPtr (std::nullptr_t)
 Construction, implicit conversion from nullptr. More...
 
 TfWeakPtr (TfWeakPtr const &p)
 Copy construction. More...
 
template<class U >
 TfWeakPtr (TfRefPtr< U > const &p, typename std::enable_if< std::is_convertible< U *, T * >::value >::type *dummy=0)
 
template<class U >
 TfWeakPtr (U *p, typename std::enable_if< std::is_convertible< U *, T * >::value >::type *dummy=nullptr)
 Explicitly construct from a raw pointer p. More...
 
template<class U >
 TfWeakPtr (TfWeakPtr< U > const &p, typename std::enable_if< std::is_convertible< U *, T * >::value >::type *dummy=0)
 
bool IsExpired () const
 
- Public Member Functions inherited from TfWeakPtrFacade< TfWeakPtr, T >
bool operator== (PtrTemplate< Other > const &p) const
 
bool operator== (TfRefPtr< T > const &p) const
 
bool operator!= (PtrTemplate< Other > const &p) const
 
bool operator!= (TfRefPtr< T > const &p) const
 
bool operator< (PtrTemplate< Other > const &p) const
 
bool operator> (PtrTemplate< Other > const &p) const
 
bool operator<= (PtrTemplate< Other > const &p) const
 
bool operator>= (PtrTemplate< Other > const &p) const
 
 operator UnspecifiedBoolType () const
 
bool operator! () const
 
bool PointsTo (T const &obj) const
 
bool PointsToA () const
 
bool IsInvalid () const
 
void constGetUniqueIdentifier () const
 
TfWeakBase constGetWeakBase () const
 
void EnableExtraNotification () const
 
DataTypeoperator-> () const
 
DataTypeoperator* () const
 
void Reset ()
 

Friends

class TfWeakPtrFacadeAccess
 
template<class U >
class TfWeakPtr
 

Additional Inherited Members

- Public Types inherited from TfWeakPtrFacade< TfWeakPtr, T >
typedef Type DataType
 
typedef PtrTemplate< DataTypeDerived
 
typedef TfWeakPtrFacadeAccess Access
 
typedef Type element_type
 
using UnspecifiedBoolType = DataType *(TfWeakPtrFacade::*)(void) const
 

Detailed Description

template<class T>
class TfWeakPtr< T >

Pointer storage with deletion detection.

Overview

A TfWeakPtr is used to cache a pointer to an object; before retrieving/using this pointer, one queries the TfWeakPtr object to verify that the objected pointed to has not been deleted in the interim.

In the code above, if PossiblyDeleteLemur() deletes the object pointed to by lemur, then the test if(lPtr) returns false. Otherwise, it is safe to call a method on lPtr.

To declare a TfWeakPtr<T>, the type T must publicly derive from TfWeakBase.

Basic Use

A TfWeakPtr<T> can access T's public members by the -> operator and can be dereferenced by the "\c *" operator.

A TfWeakPtr converts to a true bool value (for example, in an if statement) only if the pointer points to an unexpired object. Otherwise, if the pointer was either initialized to NULL, or points to an expired object, the test returns false.

Occasionally, it is useful to distinguish between a TfWeakPtr being explicitly initialized to NULL versus a TfWeakPtr whose object has expired: the member function IsInvalid() returns true only if the pointer points to an expired object.

Opaqueness

See the parallel discussion about these concepts in the documentation for TfRefPtr; the same concepts apply.

Comparisons, Const and Non-Const, Inheritance and Casting

See the parallel discussion about these concepts in the documentation for TfRefPtr; the same concepts apply.

While it is possible to create TfWeakPtrs to const contents, we recommend against it. TfCreateNonConstWeakPtr will always create a non-const weak pointer even when passed a const argument (it casts away const).

The recommendation against use of weak pointers to const content is due to the fact that weak pointers cannot be implicitly cast for both inheritance (derived to base) and const-ness (non-const to const) at the same time. Because of this, using weak pointers to const content is most often much more trouble than the benefit it gives. Therefore our policy is to not use them.

Pointer Generality

While TfWeakPtr<TfWeakBase> is specifically forbidden (you cannot construct this kind of object), you can assign any TfWeakPtr<T> to a TfWeakPtr<void> or TfWeakPtr<const void>. The only thing you can do with the latter is check to see if it points to an object that has expired. You cannot manipulate the object itself (i.e. access its member functions).

This is useful when you need to watch for object expiration without being bound by the type(s) of the objects you're watching. Similarly, you can create a TfWeakPtr<void> from a TfWeakBase * using TfCreateWeakPtr().

Performance

Deriving from TfWeakBase results in a single TfRefPtr variable being added to a class, which is the size of a regular pointer. The cost of deleting an object derived from TfWeakBase is an extra inline boolean comparison, and possible decrement of a reference count if the object's address was ever given out as a TfWeakPtr.

The cost to create a TfWeakPtr is as follows: initial creation of the pointer from a TfWeakBase object dynamically creates an object called a remnant, whose size is that of two pointers. Subsequent transfers of the same object's address to another TfWeakPtr merely bump a reference count to the remnant. When all TfWeakPtrs to the object (and the object itself) are destroyed, the remnant is deleted. An object can have a remnant created and destroyed at most once, regardless of how many times its address is given out in the form of a TfWeakPtr.

Summarizing, the cost of guarding an object is a small amount of extra space, and near-zero runtime cost if the guarding is never used. Even if the guarding is used, the overhead at deletion time is minimal.

The time to test if a TfWeakPtr is NULL, or to call a member function through a TfWeakPtr is small, involving only a single inline boolean comparison.

Definition at line 38 of file refBase.h.

Constructor & Destructor Documentation

template<class T>
TfWeakPtr< T >::TfWeakPtr ( )
inline

Definition at line 155 of file weakPtr.h.

template<class T>
TfWeakPtr< T >::TfWeakPtr ( TfNullPtrType  )
inline

Construction, implicit conversion from TfNullPtr.

Definition at line 158 of file weakPtr.h.

template<class T>
TfWeakPtr< T >::TfWeakPtr ( std::nullptr_t  )
inline

Construction, implicit conversion from nullptr.

Definition at line 161 of file weakPtr.h.

template<class T>
TfWeakPtr< T >::TfWeakPtr ( TfWeakPtr< T > const p)
inline

Copy construction.

Definition at line 164 of file weakPtr.h.

template<class T>
template<class U >
TfWeakPtr< T >::TfWeakPtr ( TfRefPtr< U > const p,
typename std::enable_if< std::is_convertible< U *, T * >::value >::type dummy = 0 
)
inline

Conversion from RefPtr where U* is convertible to T* (this pointer type).

Definition at line 171 of file weakPtr.h.

template<class T>
template<class U >
TfWeakPtr< T >::TfWeakPtr ( U *  p,
typename std::enable_if< std::is_convertible< U *, T * >::value >::type dummy = nullptr 
)
inlineexplicit

Explicitly construct from a raw pointer p.

Definition at line 184 of file weakPtr.h.

template<class T>
template<class U >
TfWeakPtr< T >::TfWeakPtr ( TfWeakPtr< U > const p,
typename std::enable_if< std::is_convertible< U *, T * >::value >::type dummy = 0 
)
inline

Definition at line 194 of file weakPtr.h.

Member Function Documentation

template<class T>
bool TfWeakPtr< T >::IsExpired ( ) const
inline

Definition at line 201 of file weakPtr.h.

Friends And Related Function Documentation

template<class T>
template<class U >
friend class TfWeakPtr
friend

Definition at line 149 of file weakPtr.h.

template<class T>
friend class TfWeakPtrFacadeAccess
friend

Definition at line 148 of file weakPtr.h.


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