CS::SndSys::Queue

CS::SndSys::Queue< T > Class Template Reference

A threadsafe, pointer-passing queue (First-In First-Out) implementation for the sound system. More...

#include <csplugincommon/sndsys/queue.h>

List of all members.

Public Member Functions

void Clear ()

Clear all entries in the queue.

T * DequeueEntry (bool bWait=false)

Dequeue an entry from the queue.

bool Find (T *data)

Compares pointers, and not the objects they point to.

bool GetClosed ()

This can be used to determine if the queue is closed.

bool GetDupecheck ()

Retrieve the status of duplicate pointer checking.

QueueIterator< T > * GetIterator ()

Retrieve an iterator over this queue.

size_t Length ()

Retrieve the number of entries in the queue.

Queue ()

Queue construction requires no parameters.

QueueErrorType QueueEntry (T *pData)

Add the specified pointer to the end of the queue.

void SetClosed (bool Closed)

Close the queue so that no further entries may be added.

void SetDupecheck (bool Check)

Turn on/off duplicate entry pointer checking.

~Queue ()

Protected Member Functions

void Lock ()

Gain exclusive-access lock on queue operations.

void Unlock ()

Release exclusive-access lock on queue operations.

Protected Attributes

volatile bool m_bClosed

Flag indicating whether new entries may be added to this queue.

volatile bool m_bDupeCheck

Flag indicating whether the same pointer may exist multiple times in this queue.

size_t m_EntryCount

Number of entries currently in the queue.

csRef< csMutex > m_pAccessMutex

The mutex which restricts access to all queue operations.

csRef< csCondition > m_pEntryReadyCondition

The condition used for waiting on and signaling availability of entries.

QEntry< T > * m_pHead

Pointer to the oldest entry in the queue.

QEntry< T > * m_pTail

Pointer to the newest entry in the queue.

Friends

class QueueIterator< T >

Detailed Description

template<typename T>
class CS::SndSys::Queue< T >

A threadsafe, pointer-passing queue (First-In First-Out) implementation for the sound system.

Warning:: csRef<> is not threadsafe, and csPtr<> doesn't let us do anything with the object referenced inside so this class, which is specifically designed to communicate between threads, has no choice but to use raw pointers. If this is used to communicate between threads, the 'feeder' thread should incref the object before passing it into the queue. The 'consumer' thread should NOT touch the refcount unless it's certain that no other thread will be touching the refcount. This makes cleanup ... interesting. One possible method for cleanup is for the 'consumer' thread which implicitly holds a single reference (passed from the 'feeder') to wait for the refcount to reach 1 before releasing it's refcount, since a refcount of 1 means that it should have the only reference and thus should be guaranteed to be the only thread working with the refcount. Another possibility is for the 'consumer' thread to queue this object back to the 'feeder' thread (through another queue), which will perform the decref itself.
If an object passed through this queue is meant to be accessed from multiple threads at once, the object must contain threadsafe methods itself.

Definition at line 95 of file queue.h.

Constructor & Destructor Documentation

template<typename T>

CS::SndSys::Queue< T >::Queue ( ) [inline]

Queue construction requires no parameters.

Definition at line 100 of file queue.h.

Member Function Documentation

template<typename T>

void CS::SndSys::Queue< T >::Clear ( ) [inline]

Clear all entries in the queue.

Warning:: This call will NOT delete the underlying object, or release any reference counts. To clear the queue in a more controlled manner, consider calling Close(true), then fetching each queue entry and handling them as appropriate for your use.

Definition at line 120 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::~Queue().

template<typename T>

T* CS::SndSys::Queue< T >::DequeueEntry ( bool bWait = false ) [inline]

Dequeue an entry from the queue.

This call can optionally wait for an entry to arrive if the bWait parameter is specified as true.

Note:: Even if bWait is specified as true, this function may return 0 Such a situation is possible if: 1) The Queue is cleared by destruction or a call to Clear() 2) The condition wait is interrupted - possibly by signal arrival

Definition at line 183 of file queue.h.

template<typename T>

bool CS::SndSys::Queue< T >::Find ( T * data ) [inline]

Compares pointers, and not the objects they point to.

Definition at line 219 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::QueueEntry().

template<typename T>

bool CS::SndSys::Queue< T >::GetClosed ( ) [inline]

This can be used to determine if the queue is closed.

Closed queues do not allow further entries to be added.

Definition at line 246 of file queue.h.

template<typename T>

bool CS::SndSys::Queue< T >::GetDupecheck ( ) [inline]

Retrieve the status of duplicate pointer checking.

Definition at line 269 of file queue.h.

template<typename T>

QueueIterator<T>* CS::SndSys::Queue< T >::GetIterator ( ) [inline]

Retrieve an iterator over this queue.

Warning:: The provided iterator holds an exclusive-access lock on the entire queue for its lifetime.

Definition at line 282 of file queue.h.

template<typename T>

size_t CS::SndSys::Queue< T >::Length ( ) [inline]

Retrieve the number of entries in the queue.

Definition at line 216 of file queue.h.

template<typename T>

void CS::SndSys::Queue< T >::Lock ( ) [inline, protected]

Gain exclusive-access lock on queue operations.

Definition at line 290 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Clear(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::DequeueEntry(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Find(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::GetClosed(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::GetDupecheck(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::QueueEntry(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::SetClosed(), and CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::SetDupecheck().

template<typename T>

QueueErrorType CS::SndSys::Queue< T >::QueueEntry ( T * pData ) [inline]

Add the specified pointer to the end of the queue.

Definition at line 138 of file queue.h.

template<typename T>

void CS::SndSys::Queue< T >::SetClosed ( bool Closed ) [inline]

Close the queue so that no further entries may be added.

Definition at line 237 of file queue.h.

template<typename T>

void CS::SndSys::Queue< T >::SetDupecheck ( bool Check ) [inline]

Turn on/off duplicate entry pointer checking.

This is off by default.

Warning:: Turning duplicate entry checking on causes each insert operation to perform a linear search of the queue.

Definition at line 261 of file queue.h.

template<typename T>

void CS::SndSys::Queue< T >::Unlock ( ) [inline, protected]

Release exclusive-access lock on queue operations.

Definition at line 296 of file queue.h.

Member Data Documentation

template<typename T>

volatile bool CS::SndSys::Queue< T >::m_bClosed [protected]

Flag indicating whether new entries may be added to this queue.

Definition at line 309 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::GetClosed(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::GetDupecheck(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::QueueEntry(), and CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::SetClosed().

template<typename T>

volatile bool CS::SndSys::Queue< T >::m_bDupeCheck [protected]

Flag indicating whether the same pointer may exist multiple times in this queue.

Definition at line 312 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::QueueEntry(), and CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::SetDupecheck().

template<typename T>

size_t CS::SndSys::Queue< T >::m_EntryCount [protected]

Number of entries currently in the queue.

Definition at line 307 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Length().

template<typename T>

csRef<csMutex> CS::SndSys::Queue< T >::m_pAccessMutex [protected]

The mutex which restricts access to all queue operations.

Definition at line 315 of file queue.h.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::DequeueEntry(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Lock(), CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Queue(), and CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Unlock().

template<typename T>

csRef<csCondition> CS::SndSys::Queue< T >::m_pEntryReadyCondition [protected]

The condition used for waiting on and signaling availability of entries.

Definition at line 317 of file queue.h.

template<typename T>

QEntry<T>* CS::SndSys::Queue< T >::m_pHead [protected]

Pointer to the oldest entry in the queue.

Definition at line 303 of file queue.h.

template<typename T>

QEntry<T>* CS::SndSys::Queue< T >::m_pTail [protected]

Pointer to the newest entry in the queue.

Definition at line 305 of file queue.h.

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

csplugincommon/sndsys/queue.h

Generated for Crystal Space by doxygen 1.4.7


Public Member Functions
void	Clear ()
	Clear all entries in the queue.
T *	DequeueEntry (bool bWait=false)
	Dequeue an entry from the queue.
bool	Find (T *data)
	Compares pointers, and not the objects they point to.
bool	GetClosed ()
	This can be used to determine if the queue is closed.
bool	GetDupecheck ()
	Retrieve the status of duplicate pointer checking.
QueueIterator< T > *	GetIterator ()
	Retrieve an iterator over this queue.
size_t	Length ()
	Retrieve the number of entries in the queue.
	Queue ()
	Queue construction requires no parameters.
QueueErrorType	QueueEntry (T *pData)
	Add the specified pointer to the end of the queue.
void	SetClosed (bool Closed)
	Close the queue so that no further entries may be added.
void	SetDupecheck (bool Check)
	Turn on/off duplicate entry pointer checking.
	~Queue ()
Protected Member Functions
void	Lock ()
	Gain exclusive-access lock on queue operations.
void	Unlock ()
	Release exclusive-access lock on queue operations.
Protected Attributes
volatile bool	m_bClosed
	Flag indicating whether new entries may be added to this queue.
volatile bool	m_bDupeCheck
	Flag indicating whether the same pointer may exist multiple times in this queue.
size_t	m_EntryCount
	Number of entries currently in the queue.
csRef< csMutex >	m_pAccessMutex
	The mutex which restricts access to all queue operations.
csRef< csCondition >	m_pEntryReadyCondition
	The condition used for waiting on and signaling availability of entries.
QEntry< T > *	m_pHead
	Pointer to the oldest entry in the queue.
QEntry< T > *	m_pTail
	Pointer to the newest entry in the queue.
Friends
class	QueueIterator< T >

Public API Reference

CS::SndSys::Queue< T > Class Template Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

template<typename T> class CS::SndSys::Queue< T >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename T>
class CS::SndSys::Queue< T >