bes Updated for version 3.20.13
agg_util::RCObject Class Reference

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

#include <RCObject.h>

Collaboration diagram for agg_util::RCObject:
Collaboration graph

Public Member Functions

void addPreDeleteCB (UseCountHitZeroCB *pCB)
 
virtual int getRefCount () const
 
 RCObject (const RCObject &proto)
 
 RCObject (RCObjectPool *pool=0)
 
virtual int ref () const
 
virtual void removeFromPool () const
 
void removePreDeleteCB (UseCountHitZeroCB *pCB)
 
virtual std::string toString () const
 
virtual int unref () const
 

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::unique_ptr! Instead, use a RCPtr(new RCObject()) in place of unique_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::unique_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?

@TODO 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 164 of file RCObject.h.

Constructor & Destructor Documentation

◆ RCObject() [1/2]

agg_util::RCObject::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.

Definition at line 45 of file RCObject.cc.

◆ RCObject() [2/2]

agg_util::RCObject::RCObject ( const RCObject proto)

Copy ctor: Starts count at 0 and adds us to the proto's pool if it exists.

Definition at line 53 of file RCObject.cc.

◆ ~RCObject()

agg_util::RCObject::~RCObject ( )
virtual

Definition at line 62 of file RCObject.cc.

Member Function Documentation

◆ addPreDeleteCB()

void agg_util::RCObject::addPreDeleteCB ( UseCountHitZeroCB pCB)

Add uniquely. If it is added agan, the second time is ignored.

Definition at line 129 of file RCObject.cc.

◆ getRefCount()

int agg_util::RCObject::getRefCount ( ) const
virtual

Get the current reference count

Implements agg_util::RCObjectInterface.

Definition at line 101 of file RCObject.cc.

◆ ref()

int agg_util::RCObject::ref ( ) const
virtual

Increase the reference count by one. const since we do not consider the ref count part of the semantic constness of the rep

Implements agg_util::RCObjectInterface.

Definition at line 71 of file RCObject.cc.

◆ removeFromPool()

void agg_util::RCObject::removeFromPool ( ) const
virtual

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. Useful when we desire a particular object stay around outside of the pool's lifetime.

Implements agg_util::RCObjectInterface.

Definition at line 106 of file RCObject.cc.

◆ removePreDeleteCB()

void agg_util::RCObject::removePreDeleteCB ( UseCountHitZeroCB pCB)

Remove it exists. If not, this unchanged.

Definition at line 142 of file RCObject.cc.

◆ toString()

◆ unref()

int agg_util::RCObject::unref ( ) const
virtual

Decrease the reference count by one. If it goes from 1 to 0, delete this and this is no longer valid.

Returns
the new ref count. If it is 0, the caller knows the object was deleted.

It is illegal to unref() an object with a count of 0. We don't throw to allow use in dtors, so the caller is assumed not to do it!

const since the reference count is not part of the semantic constness of the rep

Implements agg_util::RCObjectInterface.

Definition at line 78 of file RCObject.cc.

Friends And Related Function Documentation

◆ RCObjectPool

friend class RCObjectPool
friend

Definition at line 166 of file RCObject.h.


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