CrystalSpace

Public API Reference

csRef< T > Class Template Reference

A smart pointer. More...

#include <csutil/ref.h>

Inheritance diagram for csRef< T >:

List of all members.

Public Member Functions

void AttachNew (csPtr< T > newObj)
 Assign an object reference created with the new operator to this smart pointer.
 csRef (csRef const &other)
 Smart pointer copy constructor.
template<class T2 >
 csRef (csRef< T2 > const &other)
 Smart pointer copy constructor from assignment-compatible csRef<T2>.
template<class T2 >
 csRef (T2 *newobj)
 Construct a smart pointer from a raw object reference with a compatible type.
 csRef (T *newobj)
 Construct a smart pointer from a raw object reference.
 csRef (const csPtr< T > &newobj)
 Construct a smart pointer from a csPtr.
 csRef ()
 Construct an invalid smart pointer (that is, one pointing at nothing).
T * Get () const
 Cast smart pointer to a pointer to the underlying object.
uint GetHash () const
 Return a hash value for this smart pointer.
void Invalidate ()
 Invalidate the smart pointer by setting it to null.
bool IsValid () const
 Smart pointer validity check.
 operator T * () const
 Cast smart pointer to a pointer to the underlying object.
T & operator* () const
 Dereference underlying object.
T * operator-> () const
 Dereference underlying object.
csRefoperator= (csRef const &other)
 Assign another csRef<> of the same type to this one.
template<class T2 >
csRefoperator= (csRef< T2 > const &other)
 Assign another assignment-compatible csRef<T2> to this one.
csRefoperator= (T *newobj)
 Assign a raw object reference to this smart pointer.
csRefoperator= (const csPtr< T > &newobj)
 Assign a csPtr to a smart pointer.
 ~csRef ()
 Smart pointer destructor.

Friends

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

Detailed Description

template<class T>
class csRef< T >

A smart pointer.

Maintains and correctly manages a reference to a reference-counted object. This template requires only that the object type T implement the methods IncRef() and DecRef(). No other requirements are placed upon T.

Thread safety:
A csRef<> will always have a consistent state, even when assigned another csRef<>s or pointers from multiple threads concurrently.

Caveat: However, when assigning a value to a csRef<> from multiple threads, no statement on what value “wins” can be given. You will have to use other synchronization measures if you require a guarantee on the value a csRef<> used in such way ends up with.

The following code gives an example for correct, concurrent initialization of a shared csRef<>:

 csRef<Foo> my_ref (shared_ref);
 if (!my_ref)
 {
   // This statements is safe as it only deals with &ldquo;local&rdquo;
   // data:
   my_ref.AttachNew (new Foo);
   // The next statement can be executed concurrently
   shared_ref = my_ref;
   // shared_ref may, or may _not_, have the value of my_ref.
 }
 // ...work with my_ref

...but be aware that you can only rely on my_ref being a valid reference; it doesn't have to be the same as shared_ref. If you need such guarantees you have to use “stronger” synchronization (e.g. protect the check+assignment with a mutex).

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".

Definition at line 171 of file ref.h.


Constructor & Destructor Documentation

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

Construct an invalid smart pointer (that is, one pointing at nothing).

Dereferencing or attempting to use the invalid pointer will result in a run-time error, however it is safe to invoke IsValid().

Definition at line 182 of file ref.h.

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

Construct a smart pointer from a csPtr.

Doesn't call IncRef() on the object since it is assumed that the object in csPtr is already IncRef()'ed.

Definition at line 189 of file ref.h.

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

Construct a smart pointer from a raw object reference.

Calls IncRef() on the object.

Definition at line 205 of file ref.h.

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

Construct a smart pointer from a raw object reference with a compatible type.

Calls IncRef() on the object.

Definition at line 215 of file ref.h.

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

Smart pointer copy constructor from assignment-compatible csRef<T2>.

Definition at line 224 of file ref.h.

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

Smart pointer copy constructor.

Definition at line 232 of file ref.h.

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

Smart pointer destructor.

Invokes DecRef() upon the underlying object.

Definition at line 240 of file ref.h.


Member Function Documentation

template<class T>
void csRef< T >::AttachNew ( csPtr< T >  newObj  )  [inline]

Assign an object reference created with the new operator to this smart pointer.

Remarks:
This function allows you to assign an object pointer created with the new operator to the csRef object. Proper usage would be:
 csRef<iEvent> event;
 event.AttachNew (new csEvent);
While not recommended, you can also use this function to assign a csPtr object or csRef object to the csRef. In both of these cases, using AttachNew is equivalent to performing a simple assignment using the = operator.
Note:
Calling this function is equivalent to casting an object to a csPtr<T> and then assigning the csPtr<T> to the csRef, as follows:
 // Same effect as above code.
 csRef<iEvent> event = csPtr<iEvent> (new csEvent);

Definition at line 332 of file ref.h.

template<class T>
T* csRef< T >::Get (  )  const [inline]

Cast smart pointer to a pointer to the underlying object.

Definition at line 407 of file ref.h.

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

Return a hash value for this smart pointer.

Definition at line 426 of file ref.h.

template<class T>
void csRef< T >::Invalidate (  )  [inline]

Invalidate the smart pointer by setting it to null.

Definition at line 422 of file ref.h.

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

Smart pointer validity check.

Returns true if smart pointer is pointing at an actual object, otherwise returns false.

Definition at line 418 of file ref.h.

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

Cast smart pointer to a pointer to the underlying object.

Definition at line 403 of file ref.h.

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

Dereference underlying object.

Definition at line 411 of file ref.h.

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

Dereference underlying object.

Definition at line 399 of file ref.h.

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

Assign another csRef<> of the same type to this one.

Definition at line 351 of file ref.h.

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

Assign another assignment-compatible csRef<T2> to this one.

Definition at line 343 of file ref.h.

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

Assign a raw object reference to this smart pointer.

Remarks:
This function calls the object's IncRef() method. Because of this you should not assign a reference created with the new operator to a csRef object directly. The following code will produce a memory leak:
 csRef<iEvent> event = new csEvent;
If you are assigning a new object to a csRef, use AttachNew(T* newObj) instead.

Definition at line 291 of file ref.h.

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

Assign a csPtr to a smart pointer.

Doesn't call IncRef() on the object since it is assumed that the object in csPtr is already IncRef()'ed.

Remarks:
After this assignment, the csPtr<T> object is invalidated and cannot be used. You should not (and in fact cannot) decref the csPtr<T> after this assignment has been made.

Definition at line 254 of file ref.h.


Friends And Related Function Documentation

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

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

Definition at line 383 of file ref.h.

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

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

Definition at line 373 of file ref.h.

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

Test if the two references point to different object.

Definition at line 363 of file ref.h.

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

Test the relationship of the addresses of two objects.

Remarks:
Mainly useful when csRef<> is used as the subject of csComparator<>, which employs operator< for comparisons.

Definition at line 392 of file ref.h.

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

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

Definition at line 378 of file ref.h.

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

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

Definition at line 368 of file ref.h.

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

Test if the two references point to same object.

Definition at line 358 of file ref.h.


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

Generated for Crystal Space 2.1 by doxygen 1.6.1