Wefts::Referenced Class Reference
[Advanced Syncronization constructs]

#include <wefts_referenced.h>

Inheritance diagram for Wefts::Referenced:

[legend]Collaboration diagram for Wefts::Referenced:

[legend]List of all members.

---

Detailed Description

Shared object between threads implementing reference count and self-cancellation.

Many times, complex multithread programs need to produce a dynamically allocated object that is then shared among many user threads. This object must then be available until the last thread needing it is done with it.

The most simple way to achieve this is to provide a threadsafe reference count that can be incremented or decremented. When the last user having a reference on the object releases it, the destructor is called.

This object is derived from a read/write mutex, so the users can access the mutex in read/only mode (which is most common when you are distributing an object to many user threads.

Note:

The read/write mutex is not reentrant.

Public Member Functions
void	incRef ()
	Increments the reference count of the varaible.
void	decRef ()
	Decrements reference count.
int	references ()
	Returns the reference count of an object.
void	incRefUnlocked ()
	Increments the reference of the object without using the write locking.
void	setRefUnlocked (int count)
	Set Reference count to given amount.
Protected Member Functions
	Referenced (int count=1, bool dispose=true)
	Creates the referenced object with an initial count of users.
virtual	~Referenced ()
	The destructor may be called only by this class.
Private Attributes
int	m_count
	Count of users referencing the object.
bool	m_disposeable
	True if last reference should delete itself.

---

Constructor & Destructor Documentation

Wefts::Referenced::Referenced (  int  count = 1, bool  dispose = true )  [inline, protected]

Creates the referenced object with an initial count of users. The count of current users can never be less than 1; it can be more if the creating process has a hint of the objects that are already waiting for this reference to be created. The disposeable parameter should be given and set to false if this object is not dinamically created, but is statically held somewhere int the creator's stack. In this case, the object won't be destroyed even when the reference count reaches 0, as it will be destroyed during owner's stack frame unwinding. Parameters: count  users ready to use this data at creation dispose  true to have it deleted when reference count reaches zero, false if this obhect is statically allocated.

virtual Wefts::Referenced::~Referenced (   )  [inline, protected, virtual]

The destructor may be called only by this class.

---

Member Function Documentation

void Wefts::Referenced::decRef (   )  [inline]

Decrements reference count. If count reaches zero, the object is destroyed. Be careful not to cause race conditions so that you try to increment the reference of an object that is now being destroyed.

void Wefts::Referenced::incRef (   )  [inline]

Increments the reference count of the varaible. Be careful not to cause race conditions so that you try to increment the reference of an object that is now being destroyed.

void Wefts::Referenced::incRefUnlocked (   )  [inline]

Increments the reference of the object without using the write locking. This is meant to be used ONLY in code blocks where this object is already write locked. See the references() method for an example.

int Wefts::Referenced::references (   )  [inline]

Returns the reference count of an object. To be sure that the count of this object is still valid after this call, the caller must surround this call with a lock. Normally a read lock will be enough, but if the caller is going to reference this object more, with an incRefUnlocked, then a call inside a writeLock() is needed: MyReferenced *ref = new MyReferenced(); // Reading the value correctly // ref->readLock(); if ( ref->references() < 10 ) std::cout << "There are currently " << ref->references << std::endl; ref->unlock(); // Writing correctly // ref->writeLock(); // ...we know there are several threads waiting for us... while( ref->references() < 10 ) ref->incRefUnlocked(); ref->unlock(); Note: There isn't a decRefUnlocked method as it could cause program crashes if the count reaches 0 before unlocking.

void Wefts::Referenced::setRefUnlocked (  int  count  )  [inline]

Set Reference count to given amount. This is meant to be used ONLY in code blocks where this object is already write locked. See the references() method for an example. Note: setting a reference count lower than 1 will cause an assertion fault. Parameters: count  the new reference count

---

Member Data Documentation

int Wefts::Referenced::m_count [private]

Count of users referencing the object.

bool Wefts::Referenced::m_disposeable [private]

True if last reference should delete itself.

---

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

• wefts_referenced.h

---