Cortex
10.0.0-a4
|
#include <RefCounted.h>
Public Types | |
typedef size_t | RefCount |
Public Member Functions | |
IE_CORE_DECLAREMEMBERPTR (RefCounted) | |
void | addRef () const |
Add a reference to the current object. | |
void | removeRef () const |
Remove a reference from the current object. | |
RefCount | refCount () const |
Returns the current reference count. | |
A simple reference counted base class, intended for use with boost::intrusive_ptr.
An intrusive_ptr should be used anywhere in Cortex where it is necessary to maintain ownership of an instance derived from RefCounted, or to share ownership between several interested parties. The construction of an intrusive_ptr increments the reference count and the destruction of an intrusive_ptr decrements the reference count - when the count drops to 0 the RefCounted object will self destruct. All RefCounted derived types define both a Type::Ptr and TypePtr typedef for an intrusive_ptr pointing to that type.
There is some overhead involved in the reference counting associated with RefCounted, and for this reason, and in an attempt to strengthen the semantics of pointer usage in Cortex, we try to use the following conventions when defining programming interfaces :
When receiving a pointer as a function argument :
Pass a raw (Type *) pointer if the called function has no need to increment the reference count. For instance Renderable::render( Renderer *renderer ) takes a raw pointer as the Renderable should not need to hold a reference to the Renderer following the call.
Pass an intrusive_ptr (TypePtr) if the reference count will be changed following the function call. For instance Group::addChild( VisibleRenderablePtr child ) takes an intrusive_ptr as the group will maintain a reference to the child following the call.
When returning a pointer from a method :
Return a raw (Type *) pointer if the called object will continue to maintain a reference to the returned object following the method call. For instance CompoundObject::member() returns a raw pointer, because the CompoundObject will continue to hold a reference to the returned object following the call. The caller can assign the raw pointer to an intrusive_ptr if it wishes to own its own reference to the result, but if it merely wants to use the result temporarily it can rely on the owner to maintain a reference until the owner dies.
Return an intrusive_ptr (TypePtr) if the method or function is returning an object for which no other references are currently held. For instance Object::create() returns an ObjectPtr so that a reference to the new object exists, and to encourage the caller to maintain ownership of the new object.
When calling operator new :
Always assign the result of operator new for a RefCounted class to an intrusive_ptr immediately, to assume ownership of the new object.