ZThread::BoundedQueue< T, LockType, StorageType > Class Template Reference

#include <BoundedQueue.h>

Inheritance diagram for ZThread::BoundedQueue< T, LockType, StorageType >:

List of all members.

Public Member Functions
	BoundedQueue (size_t capacity)
virtual	~BoundedQueue ()
	Destroy this Queue.
size_t	capacity ()
virtual void	add (const T &item)
virtual bool	add (const T &item, unsigned long timeout)
virtual T	next ()
virtual T	next (unsigned long timeout)
virtual void	cancel ()
virtual bool	isCanceled ()
virtual size_t	size ()
virtual size_t	size (unsigned long timeout)
virtual bool	empty ()
virtual bool	empty (unsigned long timeout)
virtual void	acquire ()
virtual bool	tryAcquire (unsigned long timeout)
virtual void	release ()

---

Detailed Description

template<class T, class LockType, typename StorageType = std::deque<T>>
class ZThread::BoundedQueue< T, LockType, StorageType >

Author:

Eric Crahen <http://www.code-foo.com>

Date:

<2003-07-16T13:54:04-0400>

Version:

2.3.0

A BoundedQueue provides serialized access to a set of values. It differs from other Queues by adding a maximum capacity, giving it the following properties:

• Threads calling the empty() methods will be blocked until the BoundedQueue becomes empty.
• Threads calling the next() methods will be blocked until the BoundedQueue has a value to return.
• Threads calling the add() methods will be blocked until the number of values in the Queue drops below the maximum capacity.

See also:

Queue

---

Constructor & Destructor Documentation

template<class T, class LockType, typename StorageType = std::deque<T>>

ZThread::BoundedQueue< T, LockType, StorageType >::BoundedQueue

(

size_t

capacity

)

[inline]

Create a BoundedQueue with the given capacity.

Parameters:

capacity

maximum number of values to allow in the Queue at at any time

---

Member Function Documentation

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual void ZThread::BoundedQueue< T, LockType, StorageType >::acquire

(

)

[inline, virtual]

Acquire the Lockable object.

This method may or may not block the caller for an indefinite amount of time. Those details are defined by specializations of this class.

Exceptions:

Interrupted_Exception

thrown if the calling thread is interrupted before the operation completes.

Postcondition:

The Lockable is acquired only if no exception was thrown.

Implements ZThread::Lockable.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual bool ZThread::BoundedQueue< T, LockType, StorageType >::add	(	const T &	item,
		unsigned long	timeout
	)			[inline, virtual]

Add a value to this Queue.

If the number of values in the queue matches the value returned by capacity() then the calling thread will be blocked until at least one value is removed from the Queue.

Parameters:

	item	value to be added to the Queue
	timeout	maximum amount of time (milliseconds) this method may block the calling thread.

Returns:

• true if a copy of item can be added before timeout milliseconds elapse.
• false otherwise.

Exceptions:

	Cancellation_Exception	thrown if this Queue has been canceled.
	Interrupted_Exception	thrown if the thread was interrupted while waiting to add a value

Precondition:

The Queue should not have been canceled prior to the invocation of this function.

Postcondition:

If no exception is thrown, a copy of item will have been added to the Queue.

See also:

Queue::add(const T& item, unsigned long timeout)

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual void ZThread::BoundedQueue< T, LockType, StorageType >::add

(

const T &

item

)

[inline, virtual]

Add a value to this Queue.

If the number of values in the queue matches the value returned by capacity() then the calling thread will be blocked until at least one value is removed from the Queue.

Parameters:

item

value to be added to the Queue

Exceptions:

	Cancellation_Exception	thrown if this Queue has been canceled.
	Interrupted_Exception	thrown if the thread was interrupted while waiting to add a value

Precondition:

The Queue should not have been canceled prior to the invocation of this function.

Postcondition:

If no exception is thrown, a copy of item will have been added to the Queue.

See also:

Queue::add(const T& item)

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual void ZThread::BoundedQueue< T, LockType, StorageType >::cancel

(

)

[inline, virtual]

Cancel this queue.

Postcondition:

Any threads blocked by an add() function will throw a Cancellation_Exception.

Any threads blocked by a next() function will throw a Cancellation_Exception.

See also:

Queue::cancel()

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

size_t ZThread::BoundedQueue< T, LockType, StorageType >::capacity

(

)

[inline]

Get the maximum capacity of this Queue.

Returns:

size_t maximum capacity

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual bool ZThread::BoundedQueue< T, LockType, StorageType >::empty

(

unsigned long

timeout

)

[inline, virtual]

Test whether any values are available in this Queue.

The calling thread is blocked until there are no values present in the Queue.

Parameters:

timeout

maximum amount of time (milliseconds) this method may block the calling thread.

Returns:

• true if there are no values available.
• false if there are values available.

Exceptions:

Timeout_Exception

thrown if timeout milliseconds expire before a value becomes available

See also:

Queue::empty()

Reimplemented from ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual bool ZThread::BoundedQueue< T, LockType, StorageType >::empty

(

)

[inline, virtual]

Test whether any values are available in this Queue.

The calling thread is blocked until there are no values present in the Queue.

Returns:

• true if there are no values available.
• false if there are values available.

See also:

Queue::empty()

Reimplemented from ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual bool ZThread::BoundedQueue< T, LockType, StorageType >::isCanceled

(

)

[inline, virtual]

See also:

Queue::isCanceled()

Implements ZThread::Cancelable.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual T ZThread::BoundedQueue< T, LockType, StorageType >::next

(

unsigned long

timeout

)

[inline, virtual]

Retrieve and remove a value from this Queue.

If invoked when there are no values present to return then the calling thread will be blocked until a value arrives in the Queue.

Parameters:

timeout

maximum amount of time (milliseconds) this method may block the calling thread.

Returns:

T next available value

Exceptions:

	Cancellation_Exception	thrown if this Queue has been canceled.
	Timeout_Exception	thrown if the timeout expires before a value can be retrieved.

Precondition:

The Queue should not have been canceled prior to the invocation of this function.

Postcondition:

The value returned will have been removed from the Queue.

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual T ZThread::BoundedQueue< T, LockType, StorageType >::next

(

)

[inline, virtual]

Retrieve and remove a value from this Queue.

If invoked when there are no values present to return then the calling thread will be blocked until a value arrives in the Queue.

Returns:

T next available value

Exceptions:

	Cancellation_Exception	thrown if this Queue has been canceled.
	Interrupted_Exception	thrown if the thread was interrupted while waiting to retrieve a value

Precondition:

The Queue should not have been canceled prior to the invocation of this function.

Postcondition:

The value returned will have been removed from the Queue.

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual void ZThread::BoundedQueue< T, LockType, StorageType >::release

(

)

[inline, virtual]

Release the Lockable object.

This method may or may not block the caller for an indefinite amount of time. Those details are defined by specializations of this class.

Postcondition:

The Lockable is released only if no exception was thrown.

Implements ZThread::Lockable.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual size_t ZThread::BoundedQueue< T, LockType, StorageType >::size

(

unsigned long

timeout

)

[inline, virtual]

See also:

Queue::size(unsigned long timeout)

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual size_t ZThread::BoundedQueue< T, LockType, StorageType >::size

(

)

[inline, virtual]

See also:

Queue::size()

Implements ZThread::Queue< T >.

template<class T, class LockType, typename StorageType = std::deque<T>>

virtual bool ZThread::BoundedQueue< T, LockType, StorageType >::tryAcquire

(

unsigned long

timeout

)

[inline, virtual]

Attempt to acquire the Lockable object.

This method may or may not block the caller for a definite amount of time. Those details are defined by specializations of this class; however, this method includes a timeout value that can be used to limit the maximum amount of time that a specialization could block.

Parameters:

timeout

- maximum amount of time (milliseconds) this method could block

Returns:

• true if the operation completes and the Lockable is acquired before the timeout expires.
• false if the operation times out before the Lockable can be acquired.

Exceptions:

Interrupted_Exception

thrown if the calling thread is interrupted before the operation completes.

Postcondition:

The Lockable is acquired only if no exception was thrown.

Implements ZThread::Lockable.

---

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

• My Documents/Visual Studio 2005/Projects/swgemu/dep/include/zthread/BoundedQueue.h

---