sc::RefCount Class Reference

The base class for all reference counted objects. More...

#include <util/ref/ref.h>

Inheritance diagram for sc::RefCount:

Public Member Functions
size_t	identifier () const
	Return the unique identifier for this object that can be compared for different objects of different types. More...
int	lock_ptr () const
	Lock this object.
int	unlock_ptr () const
	Unlock this object.
void	use_locks (bool inVal)
	start and stop using locks on this object
refcount_t	nreference () const
	Return the reference count.
refcount_t	reference ()
	Increment the reference count and return the new count.
refcount_t	dereference ()
	Decrement the reference count and return the new count.
int	managed () const
void	unmanage ()
	Turn off the reference counting mechanism for this object. More...

Protected Member Functions
	RefCount (const RefCount &)
RefCount &	operator= (const RefCount &)

Detailed Description

The base class for all reference counted objects.

If multiple inheritance is used, RefCount must be virtually inherited from, otherwise references to invalid memory will likely result.

Reference counting information is usually maintained by smart pointer classes Ref, however this mechanism can be supplemented or replaced by directly using the public interface to RefCount.

The unmanage() member is only needed for special cases where memory management must be turned off. For example, if a reference counted object is created on the stack, memory management mechanisms based on reference counting must be prohibited from deleting it. The unmanage() member accomplishes this, but a better solution would be to allocate the object on the heap with new and let a smart pointer manage the memory for the object.

When using a debugger to look at reference counted objects the count is maintained in the reference_count member. However, this member is encoded so that memory overwrites can be sometimes detected. Thus, interpretation of reference_count is not always straightforward.

Member Function Documentation

identifier()

size_t sc::RefCount::identifier ( ) const

inline

Return the unique identifier for this object that can be compared for different objects of different types.

Usually this is just the value of the pointer to the RefCount base of the object. Some might think that this method is not needed, i.e. that the pointer to object is a sufficient means of establishing the identity. That's not so for the case of multiple inheritance. Consider this code:

struct A : virtual public RefCount { int a; };
struct B : virtual public RefCount { int b; };
struct C : public A, public B { int c; };
 
C c;
A* aptr = static_cast<A*>(&c);
B* aptr = static_cast<B*>(&c);
C* cptr = &c;
void* aptr_void = reinterpret_cast<void*>(aptr);
void* bptr_void = reinterpret_cast<void*>(bptr);
void* cptr_void = reinterpret_cast<void*>(cptr);
 
MPQC_ASSERT( c->indentifier() == aptr->identifier() ); // ok
MPQC_ASSERT( c->indentifier() == bptr->identifier() ); // ok
MPQC_ASSERT( cptr == aptr ); // ok
MPQC_ASSERT( cptr == bptr ); // ok! (implicit cast)
MPQC_ASSERT(cptr_void == aptr_void); // ok!
MPQC_ASSERT(cptr_void == bptr_void); // NOT ok!!!

Thus for objects that are derived from RefCount this will return pointer to the RefCount base; this allows to compare the identity of the objects pointed by pointers to base and pointer to the object itself.

unmanage()

void sc::RefCount::unmanage ( )

inline

Turn off the reference counting mechanism for this object.

The value returned by nreference() will always be 1 after this is called. The ability to unmanage() objects must be turned on at compile time by defining REF_MANAGE. There is a slight performance penalty.

---

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

• src/lib/util/ref/ref.h