Cortex  10.0.0-a4
Public Types | Public Member Functions | List of all members
IECore::RefCounted Class Reference

#include <RefCounted.h>

+ Inheritance diagram for IECore::RefCounted:

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.
 

Detailed Description

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.

Note
Not all of Cortex has been updated to match these conventions. Please add todo items for any nonconforming APIs.
Todo:
Disallow construction on the heap by having a private destructor - do we need to do this for all derived classes as well?

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