The Queue class accepts messages with an psuh(m) command where m is the message to be queued. More...

#include <src/main/decaf/util/StlQueue.h>

Inheritance diagram for decaf::util::StlQueue< T >:

Data Structures
class	QueueIterator
Public Member Functions
	StlQueue ()
virtual	~StlQueue ()
Iterator< T > *	iterator ()
	Gets an Iterator over this Queue.
void	clear ()
	Empties this queue.
T &	front ()
	Returns a Reference to the element at the head of the queue.
const T &	front () const
	Returns a Reference to the element at the head of the queue.
T &	back ()
	Returns a Reference to the element at the tail of the queue.
const T &	back () const
	Returns a Reference to the element at the tail of the queue.
void	push (const T &t)
	Places a new Object at the Tail of the queue.
void	enqueueFront (const T &t)
	Places a new Object at the front of the queue.
T	pop ()
	Removes and returns the element that is at the Head of the queue.
size_t	size () const
	Gets the Number of elements currently in the Queue.
bool	empty () const
	Checks if this Queue is currently empty.
virtual std::vector< T >	toArray () const
void	reverse (StlQueue< T > &target) const
	Reverses the order of the contents of this queue and stores them in the target queue.
virtual void	lock ()
	Locks the object.
virtual bool	tryLock ()
	Attempts to Lock the object, if the lock is already held by another thread than this method returns false.
virtual void	unlock ()
	Unlocks the object.
virtual void	wait ()
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	wait (long long millisecs)
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	wait (long long millisecs, int nanos)
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	notify ()
	Signals a waiter on this object that it can now wake up and continue.
virtual void	notifyAll ()
	Signals the waiters on this object that it can now wake up and continue.
T &	getSafeValue ()
	Fetch a reference to the safe value this object will return when there is nothing to fetch from the queue.

Detailed Description

template<typename T>
class decaf::util::StlQueue< T >

The Queue class accepts messages with an psuh(m) command where m is the message to be queued.

It destructively returns the message with pop(). pop() returns messages in the order they were enqueued.

Queue is implemented with an instance of the STL queue object. The interface is essentially the same as that of the STL queue except that the pop method actually reaturns a reference to the element popped. This frees the app from having to call the front method before calling pop.

Queue<string> sq; // make a queue to hold string messages sq.push(s); // enqueues a message m string s = sq.pop(); // dequeues a message

= DESIGN CONSIDERATIONS

The Queue class inherits from the Synchronizable interface and provides methods for locking and unlocking this queue as well as waiting on this queue. In a multi-threaded app this can allow for multiple threads to be reading from and writing to the same Queue.

Clients should consider that in a multiple threaded app it is possible that items could be placed on the queue faster than you are taking them off, so protection should be placed in your polling loop to ensure that you don't get stuck there.

Constructor & Destructor Documentation

template<typename T>

decaf::util::StlQueue< T >::StlQueue ( ) [inline]

template<typename T>

virtual decaf::util::StlQueue< T >::~StlQueue ( ) [inline, virtual]

Member Function Documentation

template<typename T>

T& decaf::util::StlQueue< T >::back ( ) [inline]

Returns a Reference to the element at the tail of the queue.

Returns:: reference to a queue type object or (safe)

References decaf::util::StlQueue< T >::getSafeValue().

template<typename T>

const T& decaf::util::StlQueue< T >::back ( ) const [inline]

Returns a Reference to the element at the tail of the queue.

Returns:: reference to a queue type object or (safe)

References decaf::util::StlQueue< T >::getSafeValue().

template<typename T>

void decaf::util::StlQueue< T >::clear ( ) [inline]

Empties this queue.

template<typename T>

bool decaf::util::StlQueue< T >::empty ( ) const [inline]

Checks if this Queue is currently empty.

Returns:: boolean indicating queue emptiness

template<typename T>

void decaf::util::StlQueue< T >::enqueueFront ( const T & t ) [inline]

Places a new Object at the front of the queue.

Parameters:

t	- Queue Object Type reference.

template<typename T>

const T& decaf::util::StlQueue< T >::front ( ) const [inline]

Returns a Reference to the element at the head of the queue.

Returns:: reference to a queue type object or (safe)

References decaf::util::StlQueue< T >::getSafeValue().

template<typename T>

T& decaf::util::StlQueue< T >::front ( ) [inline]

Returns a Reference to the element at the head of the queue.

Returns:: reference to a queue type object or (safe)

References decaf::util::StlQueue< T >::getSafeValue().

template<typename T>

T& decaf::util::StlQueue< T >::getSafeValue ( ) [inline]

Fetch a reference to the safe value this object will return when there is nothing to fetch from the queue.

Returns:: Reference to this Queues safe object

Referenced by decaf::util::StlQueue< T >::back(), decaf::util::StlQueue< T >::front(), and decaf::util::StlQueue< T >::pop().

template<typename T>

Iterator<T>* decaf::util::StlQueue< T >::iterator ( ) [inline]

Gets an Iterator over this Queue.

Returns:: new iterator pointer that is owned by the caller.

template<typename T>

virtual void decaf::util::StlQueue< T >::lock ( ) [inline, virtual]

Locks the object.

Exceptions:

RuntimeException if an error occurs while locking the object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::lock().

template<typename T>

virtual void decaf::util::StlQueue< T >::notify ( ) [inline, virtual]

Signals a waiter on this object that it can now wake up and continue.

Must have this object locked before calling.

Exceptions:

IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.
RuntimeException	if an error occurs while notifying one of the waiting threads.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::notify().

template<typename T>

virtual void decaf::util::StlQueue< T >::notifyAll ( ) [inline, virtual]

Signals the waiters on this object that it can now wake up and continue.

Must have this object locked before calling.

Exceptions:

IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.
RuntimeException	if an error occurs while notifying the waiting threads.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::notifyAll().

template<typename T>

T decaf::util::StlQueue< T >::pop ( ) [inline]

Removes and returns the element that is at the Head of the queue.

Returns:: reference to a queue type object or (safe)

References decaf::util::StlQueue< T >::getSafeValue().

template<typename T>

void decaf::util::StlQueue< T >::push ( const T & t ) [inline]

Places a new Object at the Tail of the queue.

Parameters:

t	- Queue Object Type reference.

template<typename T>

void decaf::util::StlQueue< T >::reverse ( StlQueue< T > & target ) const [inline]

Reverses the order of the contents of this queue and stores them in the target queue.

Parameters:

target - The target queue that will receive the contents of this queue in reverse order.

template<typename T>

size_t decaf::util::StlQueue< T >::size ( ) const [inline]

Gets the Number of elements currently in the Queue.

Returns:: Queue Size

template<typename T>

virtual std::vector<T> decaf::util::StlQueue< T >::toArray ( ) const [inline, virtual]

Returns:: the all values in this queue as a std::vector.

template<typename T>

virtual bool decaf::util::StlQueue< T >::tryLock ( ) [inline, virtual]

Attempts to Lock the object, if the lock is already held by another thread than this method returns false.

Returns:: true if the lock was acquired, false if it is already held by another thread.

Exceptions:

RuntimeException if an error occurs while locking the object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::tryLock().

template<typename T>

virtual void decaf::util::StlQueue< T >::unlock ( ) [inline, virtual]

Unlocks the object.

Exceptions:

RuntimeException if an error occurs while unlocking the object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::unlock().

template<typename T>

virtual void decaf::util::StlQueue< T >::wait ( ) [inline, virtual]

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling.

Exceptions:

RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::wait().

template<typename T>

virtual void decaf::util::StlQueue< T >::wait ( long long millisecs ) [inline, virtual]

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling. This wait will timeout after the specified time interval.

Parameters:

millisecs the time in milliseconds to wait, or WAIT_INIFINITE

Exceptions:

RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::wait().

template<typename T>

virtual void decaf::util::StlQueue< T >::wait	(	long long	millisecs,
		int	nanos
	)		`[inline, virtual]`

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling. This wait will timeout after the specified time interval. This method is similar to the one argument wait function except that it add a finer grained control over the amount of time that it waits by adding in the additional nanosecond argument.

NOTE: The ability to wait accurately at a nanosecond scale depends on the platform and OS that the Decaf API is running on, some systems do not provide an accurate enough clock to provide this level of granularity.

Parameters:

millisecs	the time in milliseconds to wait, or WAIT_INIFINITE
nanos	additional time in nanoseconds with a range of 0-999999

Exceptions:

IllegalArgumentException	if an error occurs or the nanos argument is not in the range of [0-999999]
RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

References decaf::util::concurrent::Mutex::wait().

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

src/main/decaf/util/StlQueue.h

decaf::util::StlQueue< T > Class Template Reference

Data Structures

Public Member Functions

Detailed Description

template<typename T> class decaf::util::StlQueue< T >

Constructor & Destructor Documentation

Member Function Documentation

template<typename T>
class decaf::util::StlQueue< T >