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.
Public Member Functions inherited from decaf::util::concurrent::Synchronizable
virtual	~Synchronizable ()

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 ( )

inlinevirtual

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>

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>

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 >::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 ( )

inlinevirtual

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 ( )

inlinevirtual

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 ( )

inlinevirtual

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

inlinevirtual

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

template<typename T>

virtual bool decaf::util::StlQueue< T >::tryLock ( )

inlinevirtual

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 ( )

inlinevirtual

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 ( )

inlinevirtual

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 )

inlinevirtual

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
	)

inlinevirtual

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

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 >