A base class for a simple reference counted object. More...

#include <RCObject.h>

Inheritance diagram for agg_util::RCObject:

Collaboration diagram for agg_util::RCObject:

Public Member Functions
void	addPreDeleteCB (UseCountHitZeroCB *pCB)
	Add uniquely. More...

virtual int	getRefCount () const
	Get the current reference count. More...

	RCObject (RCObjectPool *pool=0)
	If the pool is given, the object will be released back to the pool when its count hits 0, otherwise it will be deleted. More...

	RCObject (const RCObject &proto)
	Copy ctor: Starts count at 0 and adds us to the proto's pool if it exists. More...

virtual int	ref () const
	Increase the reference count by one. More...

virtual void	removeFromPool () const
	If the object is in an auto-delete pool, remove it from the pool and force it to only delete when it's ref count goes to 0. More...

void	removePreDeleteCB (UseCountHitZeroCB *pCB)
	Remove it exists. More...

virtual std::string	toString () const
	Just prints the count and address. More...

virtual int	unref () const throw ()
	Decrease the reference count by one. More...

virtual	~RCObject ()

Friends
class	RCObjectPool

Detailed Description

A base class for a simple reference counted object.

Use as a base class for objects that need to delete themselves when their reference count goes to 0.

When a strong reference to the object is required, the caller uses ref(). When the reference needs to be released, unref() is called. p->unref() should be considered potentially identical to delete p; since it can cause the object to be deleted. The pointer should NOT be used after an unref() unless it was known to be preceded by a ref(), or unless the count is checked prior to unref() and found to be > 1.

A new RCObject has a count of 0, and will only be destroyed automatically if the count goes from 1 back to 0, so the caller is in charge of it unless the first ref() call. Be careful storing these in std::auto_ptr! Instead, use a RCPtr(new RCObject()) in place of auto_ptr for hanging onto an RCOBject* in a local variable before possible early exit.

See also: RCPtr which can be used as a temporary reference similar to std::auto_ptr<T>, but which uses the reference counting system to safely handle a RCObject as a temporary in a location where an exception might cause it to be leaked. This is especially useful when the object is removed from a refcounted container but safely needs to be used locally before destruction.

Note: This class influenced by Scott Meyers and Open Inventor ref counting stuff.; I'd much rather use boost::shared_ptr and boost::weak_ptr for this stuff since they can be used in STL containers and are thread-safe, but adding a boost dependency for just shared_ptr seems like overkill now. NOTE: shared_ptr is now in C++ TR1, implemented by gcc 4.x. Can we assume it?

Consider adding a pointer to an abstract MemoryPool or what have you so that a Factory can implement the interface and these objects can be stored in a list as well as returned from factory. That way the factory can forcibly clear all dangling references from the pool in its dtor in the face of exception unwind or programmer ref counting error.

Definition at line 162 of file RCObject.h.