BReferenceable Class Reference

Implementation of reference-counted memory management. More...

Inherited by BNetworkAddressResolver, and BToolTip.

Public Member Functions
	BReferenceable ()
	Initialize the object with a reference count of 1.
virtual	~BReferenceable ()
	Destructor.
int32	AcquireReference ()
	Acquire a reference to the object.
int32	CountReferences () const
	Return the number of references to the object.
int32	ReleaseReference ()
	Release a reference to the object.

Protected Member Functions
virtual void	FirstReferenceAcquired ()
	Called when the first reference to the object is reacquired.
virtual void	LastReferenceReleased ()
	Called when the last reference to the object is released.

Detailed Description

Implementation of reference-counted memory management.

The C++ language provides two main ways of allocating objects: on the stack, and on the heap. Objects created on the heap must be managed by the application and deleted when they are not needed. Objects allocated on the stack have a lifetime limited to the execution of the block they are declared in.

This approach is simple, but in some cases it can become quite difficult to track ownership and lifetime of objects. The BReferenceable class allows to implement reference counting, which allows a partially automated memory management and some safety checks. It can also be used to implement pools of reusable objects.

As the name implies, reference counting consists of keeping track, inside an object, of how much references there are to it in the running application. When the object is not referenced anymore, it can't be reached or used from other parts of the application, so it is safe to delete or recycle the object.

To use reference counting for a particular class, you make it inherit BReferenceable. This provides all the support for reference counting. Objects are created as usual, on the stack or using the new operator.

The object can then be referenced from other places. Each time a reference to it is kept, the owner of the reference should call AcquireReference. When the reference is not needed, it should call ReleaseReference.

Since

Haiku R1

Constructor & Destructor Documentation

BReferenceable()

BReferenceable::BReferenceable

(

)

Initialize the object with a reference count of 1.

The creator of the object is assumed to owns the first reference to it.

~BReferenceable()

BReferenceable::~BReferenceable ( )

virtual

Destructor.

The destructor should not be called directly, as the object is destructed automatically when the last reference is released. This destructor is public because you may still need to destroy the objects in the case where LastReferenceReleased is overriden and you handle object destruction in some other way.

In debug mode, the destructor checks that no references to the object are still held. If the object was allocated on the stack, it allows exactly one reference to be kept, which makes it possible to allocate BReferenceable on the stack without needing to release the single reference to it.

Member Function Documentation

AcquireReference()

int32 BReferenceable::AcquireReference

(

)

Acquire a reference to the object.

Returns

the previous reference count

If the reference count was previously 0, this will call FirstReferenceAcquired.

CountReferences()

int32 BReferenceable::CountReferences ( ) const

inline

Return the number of references to the object.

Returns

the reference count.

References atomic_get().

FirstReferenceAcquired()

void BReferenceable::FirstReferenceAcquired ( )

protectedvirtual

Called when the first reference to the object is reacquired.

The default implementation does nothing. This method can be overriden to implement reinitialization of the object, when using BReferenceable to keep track of a pool of reusable objects.

In this use case, the objects are created (at initialization or lazily on an as-needed basis) and stored in a pool. When an object is needed, if there is an unused one waiting in the pool, it is reused instead of creating a new one. Once a reference to it is acquired, this method is called and the object can initialize itself to a clean state.

Warning

This is currently not called when the object is first created, but only on subsequent reuses.

LastReferenceReleased()

void BReferenceable::LastReferenceReleased ( )

protectedvirtual

Called when the last reference to the object is released.

This function is called when the object is not referenced anymore. The default implementation deletes the object using the delete operator.

This behavior can be overriden. For example, to implement an object pool, this method would not delete the object, but instead put it back in the free object pool, ready for reuse at a later point.

ReleaseReference()

int32 BReferenceable::ReleaseReference

(

)

Release a reference to the object.

Returns

the previous reference count

If the reference count was previously 1 (and is now 0), this will call LastReferenceReleased.