base::Dlist< T, LOCK > Class Template Reference

///
/// Interface:
/// ----------
/// Dlist()     Pass DESTROY/KEEP to control whether linked objects
///             will be deleted when the dlist itself is deleted.
/// IfEmpty()	True if dlist is empty.
/// IfMoreThanOne()	True if dlist has more than one item.
/// IfLinked()	True if object is in dlist.
/// Clear()     Remove all links (deletes objects depending on KEEP/DESTROY).
/// Prepend()	Prepend new link before the head of the dlist (new link becomes the first one).
/// Append()	Append new link after the tail of the dlist (new link becomes the last one).
/// Unlink()	Remove link.  Never deletes the unlinked object (regardless of DESTROY).
/// First()		Return pointer to the first link or NULL if none (iterator helpers instead is recommended).
/// Last()		Return pointer to the last  link or NULL if none (iterator helpers instead is recommended).
/// Prev()		Return pointer to previous link or NULL if none (iterator helpers instead is recommended).
/// Next()		Return pointer to following link or NULL if none (iterator helpers instead is recommended).
///
/// Features:
/// ---------
/// - Circular list with double links.
/// - Fast unlinking and appending (because of double-links and tail pointer).
/// - List destructor can auto-destroy linked objects (optional).
/// - Type-signature checking to catch memory corruption.
/// - Imperfect thread-safety.
/// - Unlink() doesn't delete objects.
/// - Can return Iterator object.
///
/// Usage:
/// ------
/// By default, when a Dlist is deleted, it deletes all linked objects.
/// Or pass KEEP to ctor to leave objects allocated after Dlist is destroyed.
/// Unlink() is unaffected by this arg (see below).
///
/// Linked objects must be allocated by the C++ new operator since
/// the Dlist destructor uses the C++ delete operator to free linked objects
///
/// Although Dlist is based on storing pointers to objects, a Dlist variable
/// is declared with only the user-type inside <> (don't be confused by this).
/// The Dlist itself should be declared as a pointer, eg:
///
///  Dlist<Class>*  mDlist;  // right
///  Dlist<Class>*  mDlist = new Dlist<MyClass>;  // right
///  Dlist<Class*>* mDlist;  // wrong (would store pointer-to-pointers to MyClass)
///  Dlist<Class>   mDlist;  // wrong (won't compile because of there's no default constructor)
///
/// C++ arrays aren't directly supported.
/// Use a STL container or the Array<> class.
///
/// Traversing a Dlist using DlistIterator:
///
/// A DlistIterator object will auto-lock the Dlist.
/// It's intended to be an automatic variable.
///
/// DlistIterator<Object> iter( mList );
/// while ( iter )  // DlistIterator::operator bool() returns true Next() has an item
/// {
///    Object* obj = dlistIter.Next();
/// }
///
/// Unlink() never deletes linked objects:
/// -------------------------------------
/// Unlink() never deletes linked objects, regardless of the DESTROY ctor arg.
/// Because there are cases where a linked object unlinks itself from a Dlist.
/// Obviously, Unlink() shouldn't delete its caller.
///
/// Imperfect thread-safety:
/// ------------------------
/// Although Dlist uses locks to safe-guard its internal consistency,
/// multiple threads can concurrently modify the Dlist.
/// Such users are responsible for locking the Dlist themselves.
///
/// Implementation:
/// ---------------
/// A sentinel is omnipresent, never unlinked.
/// A Dlist is empty when its last remaining link is the sentinel.
/// The head pointer always points to the sentinel (head pointer is never reassigned)
/// but the tail pointer will change.
/// The first actual link follows the sentinel and is pointed to by head->next.
///
/// For speed, a count of links isn't maintained (expected to be unused usually).
/// If a count is needed, the user of the Dlist can track inserted/removed items.
///
///


Public Types
enum	eDestroy { DESTROY, KEEP }
typedef LOCK	LockType
Public Member Functions
	Dlist (eDestroy destroy=DESTROY)
	~Dlist ()
void	Clear (void)
Dlink< T > *	Prepend (T *obj)
Dlink< T > *	Append (T *obj)
void	Unlink (Dlink< T > *dlink)
bool	IfEmpty (void) const
bool	IfMoreThanOne (void) const
Dlink< T > *	First (void) const
Dlink< T > *	Last (void) const
Dlink< T > *	Prev (const Dlink< T > *dlink) const
Dlink< T > *	Next (const Dlink< T > *dlink) const
bool	IfLinked (const T *obj)
void	Lock (void) const
void	Unlock (void) const
Private Attributes
eDestroy	mDestroy
	controls whether dlist destructor will delete linked objects
Dlink< T > *	mHead
	always points to the sentinel
Dlink< T > *	mTail
	points to last link or sentinel if empty

base::Dlist< T, LOCK > Class Template Reference

Public Types

Public Member Functions

Private Attributes

Detailed Description

template<typename T, typename LOCK = FastLock>
class base::Dlist< T, LOCK >

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

DESTROY
KEEP

base::Dlist< T, LOCK > Class Template Reference

Public Types

Public Member Functions

Private Attributes

Detailed Description

template<typename T, typename LOCK = FastLock> class base::Dlist< T, LOCK >

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename T, typename LOCK = FastLock>
class base::Dlist< T, LOCK >