CrystalSpace

Public API Reference

csWeakRef< T > Class Template Reference

A weak reference. More...

#include <csutil/weakref.h>

List of all members.

Public Member Functions

 csWeakRef (const csPtr< T > &newobj)
 Construct a weak reference from a csPtr.
 csWeakRef (csWeakRef const &other)
 Weak pointer copy constructor.
 csWeakRef (csRef< T > const &newobj)
 Construct a weak reference from a csRef<>.
 csWeakRef (T *newobj)
 Construct a weak reference from a normal pointer.
 csWeakRef ()
 Construct an empty weak reference.
uint GetHash () const
 Return a hash value for this smart pointer.
CS_WEAKREF_METHOD_UNSAFE bool IsValid () const
 Weak pointer validity check.
CS_WEAKREF_METHOD_UNSAFE operator T * () const
 Cast weak reference to a pointer to the underlying object.
CS_WEAKREF_METHOD_UNSAFE T & operator* () const
 Dereference underlying object.
CS_WEAKREF_METHOD_UNSAFE T * operator-> () const
 Dereference underlying object.
csWeakRefoperator= (csWeakRef const &other)
 Assign another object to this weak reference.
csWeakRefoperator= (csPtr< T > newobj)
 Assign a csPtr reference to this weak reference.
csWeakRefoperator= (csRef< T > const &newobj)
 Assign a csRef<> to this weak reference.
csWeakRefoperator= (T *newobj)
 Assign a raw object reference to this weak reference.
 ~csWeakRef ()
 Weak pointer destructor.



template<typename U >
void Get (U &ref) const
 Safely get the weakly referenced object.
template<typename U >
Get () const
 Safely get the weakly referenced object.

Friends

bool operator!= (T *obj, const csWeakRef &r1)
 Test if object pointed to by reference is different from obj.
bool operator!= (const csWeakRef &r1, T *obj)
 Test if object pointed to by reference is different from obj.
bool operator!= (const csWeakRef &r1, const csWeakRef &r2)
 Test if the two references point to different object.
bool operator== (T *obj, const csWeakRef &r1)
 Test if object pointed to by reference is same as obj.
bool operator== (const csWeakRef &r1, T *obj)
 Test if object pointed to by reference is same as obj.
bool operator== (const csWeakRef &r1, const csWeakRef &r2)
 Test if the two references point to same object.

Detailed Description

template<class T>
class csWeakRef< T >

A weak reference.

This is a reference to a reference counted object but in itself it doesn't increment the ref counter. As soon as the object is destroyed (i.e. the last REAL reference to it is removed) all weak references pointing to that object are cleared. This kind of reference is useful if you want to maintain some kind of cached objects that can safely be removed as soon as the last reference to it is gone.

Note: this class assumes that the T type implements at least the following functions:

Remarks:
An extended explanation on smart pointers - how they work and what type to use in what scenario - is contained in the User's manual, section "Correctly Using Smart Pointers".

Although csWeakRef<> implements the necessary operators to transparently use it like an actual pointer, this usage is not thread-safe: when using multiple threads, it can happen that a weak pointer appears valid in one thread, but is being destroyed (or has been destroyed) in another thread. For thread-safe usage, convert the weak pointer to a csRef<> first by using a Get() method: This ensures that a valid returned pointer stays valid and that an invalid pointer is returned if the object is being destroyed.

Definition at line 69 of file weakref.h.


Constructor & Destructor Documentation

template<class T>
csWeakRef< T >::csWeakRef (  )  [inline]

Construct an empty weak reference.

Definition at line 104 of file weakref.h.

template<class T>
csWeakRef< T >::csWeakRef ( T *  newobj  )  [inline]

Construct a weak reference from a normal pointer.

Definition at line 114 of file weakref.h.

template<class T>
csWeakRef< T >::csWeakRef ( csRef< T > const &  newobj  )  [inline]

Construct a weak reference from a csRef<>.

Definition at line 126 of file weakref.h.

template<class T>
csWeakRef< T >::csWeakRef ( csWeakRef< T > const &  other  )  [inline]

Weak pointer copy constructor.

Definition at line 138 of file weakref.h.

template<class T>
csWeakRef< T >::csWeakRef ( const csPtr< T > &  newobj  )  [inline]

Construct a weak reference from a csPtr.

This will put the object in the weak reference and then it will release the reference.

Definition at line 158 of file weakref.h.

template<class T>
csWeakRef< T >::~csWeakRef (  )  [inline]

Weak pointer destructor.

Definition at line 171 of file weakref.h.


Member Function Documentation

template<class T>
template<typename U >
void csWeakRef< T >::Get ( U &  ref  )  const [inline]

Safely get the weakly referenced object.

Template Parameters:
U Type as which the object pointer should be returned. Must be constructible or assignable from T*. It's recommended to make it a csRef<T> in order to keep the object alive as long as it's needed.

Definition at line 311 of file weakref.h.

template<class T>
template<typename U >
U csWeakRef< T >::Get (  )  const [inline]

Safely get the weakly referenced object.

Template Parameters:
U Type as which the object pointer should be returned. Must be constructible or assignable from T*. It's recommended to make it a csRef<T> in order to keep the object alive as long as it's needed.

Definition at line 305 of file weakref.h.

template<class T>
uint csWeakRef< T >::GetHash (  )  const [inline]

Return a hash value for this smart pointer.

Definition at line 328 of file weakref.h.

template<class T>
CS_WEAKREF_METHOD_UNSAFE bool csWeakRef< T >::IsValid (  )  const [inline]

Weak pointer validity check.

Returns true if weak reference is pointing at an actual object, otherwise returns false.

Definition at line 324 of file weakref.h.

template<class T>
CS_WEAKREF_METHOD_UNSAFE csWeakRef< T >::operator T * (  )  const [inline]

Cast weak reference to a pointer to the underlying object.

Definition at line 289 of file weakref.h.

template<class T>
CS_WEAKREF_METHOD_UNSAFE T& csWeakRef< T >::operator* (  )  const [inline]

Dereference underlying object.

Definition at line 294 of file weakref.h.

template<class T>
CS_WEAKREF_METHOD_UNSAFE T* csWeakRef< T >::operator-> (  )  const [inline]

Dereference underlying object.

Definition at line 284 of file weakref.h.

template<class T>
csWeakRef& csWeakRef< T >::operator= ( csWeakRef< T > const &  other  )  [inline]

Assign another object to this weak reference.

Definition at line 230 of file weakref.h.

template<class T>
csWeakRef& csWeakRef< T >::operator= ( csPtr< T >  newobj  )  [inline]

Assign a csPtr reference to this weak reference.

This will cause a DecRef() on the pointer.

Definition at line 221 of file weakref.h.

template<class T>
csWeakRef& csWeakRef< T >::operator= ( csRef< T > const &  newobj  )  [inline]

Assign a csRef<> to this weak reference.

Definition at line 212 of file weakref.h.

template<class T>
csWeakRef& csWeakRef< T >::operator= ( T *  newobj  )  [inline]

Assign a raw object reference to this weak reference.

Definition at line 188 of file weakref.h.


Friends And Related Function Documentation

template<class T>
bool operator!= ( T *  obj,
const csWeakRef< T > &  r1 
) [friend]

Test if object pointed to by reference is different from obj.

Definition at line 269 of file weakref.h.

template<class T>
bool operator!= ( const csWeakRef< T > &  r1,
T *  obj 
) [friend]

Test if object pointed to by reference is different from obj.

Definition at line 257 of file weakref.h.

template<class T>
bool operator!= ( const csWeakRef< T > &  r1,
const csWeakRef< T > &  r2 
) [friend]

Test if the two references point to different object.

Definition at line 244 of file weakref.h.

template<class T>
bool operator== ( T *  obj,
const csWeakRef< T > &  r1 
) [friend]

Test if object pointed to by reference is same as obj.

Definition at line 263 of file weakref.h.

template<class T>
bool operator== ( const csWeakRef< T > &  r1,
T *  obj 
) [friend]

Test if object pointed to by reference is same as obj.

Definition at line 251 of file weakref.h.

template<class T>
bool operator== ( const csWeakRef< T > &  r1,
const csWeakRef< T > &  r2 
) [friend]

Test if the two references point to same object.

Definition at line 237 of file weakref.h.


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

Generated for Crystal Space 2.1 by doxygen 1.6.1