nub::ref_counted Class Reference

#include <nub/refcounted.h>

Inheritance diagram for nub::ref_counted:

[legend]Collaboration diagram for nub::ref_counted:

[legend]List of all members.

---

Detailed Description

nub::ref_counted is a reference counting base class that allows both strong and weak reference counting. nub::ref_counted objects use a nub::ref_counts object to manage their reference counts, so clients that need to know if a nub::ref_counted object is still around can check the is_owner_alive() from its nub::ref_counts object. Finally, subclasses of nub::ref_counted can declare themselves volatile (by calling mark_as_volatile()) if their lifetime cannot be fully controlled by reference-counting; clients of such volatile objects must use weak reference counts only. No manipulation of the reference count is allowed for volatile objects; only the weak reference count may be used.

Definition at line 129 of file refcounted.h.

Public Member Functions
void *	operator new (size_t bytes)
void	operator delete (void *space, size_t bytes)
	ref_counted ()
	Default constructor.
virtual	~ref_counted () GVX_DTOR_NOTHROW
void	mark_as_volatile () throw ()
	Mark this object as a volatile (unshareable) object.
void	incr_ref_count () const throw ()
	Increment the object's reference count.
void	decr_ref_count () const throw ()
	Decrement the object's reference count.
void	decr_ref_count_no_delete () const throw ()
	Decrement the object's reference count, but don't delete it.
bool	is_shared () const throw ()
	Returns true if no external client has sole ownership of the object.
bool	is_unshared () const throw ()
	Returns true if there is a sole external owner of the object.
bool	is_not_shareable () const throw ()
ref_counts *	get_counts () const throw ()
	Returns the object's reference count manager.
int	dbg_ref_count () const throw ()
	FOR TEST/DEBUG ONLY! Returns the object's (strong) reference count.
int	dbg_weak_ref_count () const throw ()
	FOR TEST/DEBUG ONLY! Returns the object's weak reference count.

---

Constructor & Destructor Documentation

nub::ref_counted::ref_counted (   )

Default constructor. Definition at line 169 of file refcounted.cc. References nub::ref_counts::acquire_weak(), dbg_eval_nl, dbg_print, and GVX_TRACE.

nub::ref_counted::~ref_counted (   )  [virtual]

Virtual destructor is protected, so that we can prevent clients from instantiating ref_counted's on the stack and from destroying them explicitly. Instead, ref_counted objects will only be destroyed by a 'delete this' call inside decr_ref_count() if the reference count falls to zero or below. Clients are forced to create ref_counted objects dynamically using new, which is what we need in order for 'delete this' to be valid later on. Definition at line 178 of file refcounted.cc. References rutz::mutex_atomic_int::atomic_get(), dbg_dump, dbg_eval_nl, dbg_print, GVX_PANIC, GVX_TRACE, nub::ref_counts::m_owner_alive, nub::ref_counts::m_strong, and nub::ref_counts::release_weak().

---

Member Function Documentation

int nub::ref_counted::dbg_ref_count (   )  const throw ()

FOR TEST/DEBUG ONLY! Returns the object's (strong) reference count. Definition at line 254 of file refcounted.cc. References rutz::mutex_atomic_int::atomic_get(), and nub::ref_counts::m_strong.

int nub::ref_counted::dbg_weak_ref_count (   )  const throw ()

FOR TEST/DEBUG ONLY! Returns the object's weak reference count. Definition at line 259 of file refcounted.cc. References rutz::mutex_atomic_int::atomic_get(), and nub::ref_counts::m_weak.

void nub::ref_counted::decr_ref_count (   )  const throw ()

Decrement the object's reference count. If this causes the reference count to fall to zero or below, the pointee and the pointer will be destroyed by a call to 'delete this'. This operation (on the strong reference count) is not permitted if the object is unshareable. Unshareable objects can only have their weak reference counts manipulated. Definition at line 212 of file refcounted.cc. References dbg_eval_nl, and nub::ref_counts::release_strong().

void nub::ref_counted::decr_ref_count_no_delete (   )  const throw ()

Decrement the object's reference count, but don't delete it. Unlike decr_ref_count(), the object will NOT be delete'd if the reference count falls to zero. This operation (on the strong reference count) is not permitted if the object is unshareable. Unshareable objects can only have their weak reference counts manipulated. Definition at line 221 of file refcounted.cc. References nub::ref_counts::release_strong_no_delete().

nub::ref_counts * nub::ref_counted::get_counts (   )  const throw ()

Returns the object's reference count manager. Definition at line 248 of file refcounted.cc. References GVX_TRACE.

void nub::ref_counted::incr_ref_count (   )  const throw ()

Increment the object's reference count. This operation (on the strong reference count) is not permitted if the object is unshareable. Unshareable objects can only have their weak reference counts manipulated. Definition at line 207 of file refcounted.cc. References nub::ref_counts::acquire_strong().

bool nub::ref_counted::is_not_shareable (   )  const throw ()

Returns true if the object is not shareable for any reason. This could be because its lifespan is volatile (such as objects representing on-screen windows that can be dismissed by the user). The default is for objects to be shareable; objects can declare themselves as unshareable by calling mark_as_volatile(). Definition at line 242 of file refcounted.cc. References GVX_TRACE, and nub::ref_counts::m_volatile. Referenced by is_shared().

bool nub::ref_counted::is_shared (   )  const throw ()

Returns true if no external client has sole ownership of the object. This may occur if either (1) the reference count is greater than one, or (2) the object is_not_shareable(), meaning that the object itself is the only "owner". Definition at line 226 of file refcounted.cc. References rutz::mutex_atomic_int::atomic_get(), GVX_TRACE, is_not_shareable(), and nub::ref_counts::m_strong. Referenced by is_unshared().

bool nub::ref_counted::is_unshared (   )  const throw ()

Returns true if there is a sole external owner of the object. This occurs if the reference count is one or less and the object is shareable. Definition at line 236 of file refcounted.cc. References GVX_TRACE, and is_shared().

void nub::ref_counted::mark_as_volatile (   )  throw ()

Mark this object as a volatile (unshareable) object. Definition at line 195 of file refcounted.cc. References rutz::mutex_atomic_int::atomic_get(), GVX_PANIC, GVX_TRACE, nub::ref_counts::m_strong, and nub::ref_counts::m_volatile.

void nub::ref_counted::operator delete (  void *  space, size_t  bytes )

Class-specific operator delete; private since deletion should only happen in ref_counted::decr_ref_count. Definition at line 163 of file refcounted.cc. References GVX_TRACE.

void * nub::ref_counted::operator new (  size_t  bytes  )

Class-specific operator new; protected to ensure that clients use factory functions. Definition at line 157 of file refcounted.cc. References GVX_TRACE.

---

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

• src/nub/refcounted.h
• src/nub/refcounted.cc

---