A BlockingQueue derivative that allows for a bound to be placed on the number of elements that can be enqueued at any one time. More...

#include <src/main/decaf/util/concurrent/LinkedBlockingQueue.h>

Inheritance diagram for decaf::util::concurrent::LinkedBlockingQueue< E >:

[legend]

Data Structures

class ConstLinkedIterator

class LinkedIterator

class QueueNode

class TotalLock

Public Member Functions

LinkedBlockingQueue ()

Create a new instance with a Capacity of Integer::MAX_VALUE.

LinkedBlockingQueue (int capacity)

Create a new instance with the given initial capacity value.

LinkedBlockingQueue (const Collection< E > &collection)

Create a new instance with a Capacity of Integer::MAX_VALUE and adds all the values contained in the specified collection to this Queue.

virtual ~LinkedBlockingQueue ()

LinkedBlockingQueue< E > & operator= (const LinkedBlockingQueue< E > &queue)

LinkedBlockingQueue< E > & operator= (const Collection< E > &collection)

virtual int size () const

Returns the number of elements in this collection.

virtual void clear ()

Removes all of the elements from this collection (optional operation).The collection will be empty after this method returns.This implementation iterates over this collection, removing each element using the Iterator.remove operation. Most implementations will probably choose to override this method for efficiency.Note that this implementation will throw an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection is non-empty.

Exceptions:

UnsupportedOperationException if the clear operation is not supported by this collection

This implementation repeatedly invokes poll until it returns false.

virtual int remainingCapacity () const

Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer::MAX_VALUE if there is no intrinsic limit.

virtual void put (const E &value)

Inserts the specified element into this queue, waiting if necessary for space to become available.

virtual bool offer (const E &value, long long timeout, const TimeUnit &unit)

Inserts the specified element into this queue, waiting up to the specified wait time if necessary for space to become available.

virtual bool offer (const E &value)

Inserts the specified element into the queue provided that the condition allows such an operation.

virtual E take ()

Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

virtual bool poll (E &result, long long timeout, const TimeUnit &unit)

Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.

virtual bool poll (E &result)

Gets and removes the element in the head of the queue.

virtual bool peek (E &result) const

Gets but not removes the element in the head of the queue.

virtual bool remove (const E &value)

Removes a single instance of the specified element from the collection.More formally, removes an element e such that (value == NULL ? e == NULL : value == e), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

Parameters:

value The reference to the element to remove from this Collection.

Returns:: true if the collection was changed, false otherwise.

Exceptions:

UnsupportedOperationExceptio	if this is an unmodifiable collection.
NullPointerException	if the Collection is a container of pointers and does not allow NULL values.

This implementation iterates over the collection looking for the specified element. If it finds the element, it removes the element from the collection using the iterator's remove method.Note that this implementation throws an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection contains the specified object.

virtual std::vector< E > toArray () const

Answers an STL vector containing copies of all elements contained in this Collection.

virtual std::string toString () const

virtual int drainTo (Collection< E > &c)

Removes all available elements from this queue and adds them to the given collection.

virtual int drainTo (Collection< E > &sink, int maxElements)

Removes at most the given number of available elements from this queue and adds them to the given collection.

virtual decaf::util::Iterator
< E > * iterator ()

virtual decaf::util::Iterator
< E > * iterator () const

Detailed Description

template<typename E>
class decaf::util::concurrent::LinkedBlockingQueue< E >

A BlockingQueue derivative that allows for a bound to be placed on the number of elements that can be enqueued at any one time.

Elements are inserted and removed in FIFO order. The internal structure of the queue is based on a linked nodes which provides for better performance over their array based versions but the performance is less predictable.

The capacity bound of this class default to Integer::MAX_VALUE.

Since:: 1.0

Constructor & Destructor Documentation

template<typename E>

decaf::util::concurrent::LinkedBlockingQueue< E >::LinkedBlockingQueue ( ) [inline]

Create a new instance with a Capacity of Integer::MAX_VALUE.

template<typename E>

decaf::util::concurrent::LinkedBlockingQueue< E >::LinkedBlockingQueue ( int capacity ) [inline]

Create a new instance with the given initial capacity value.

Parameters:

capacity The initial capacity value to assign to this Queue.

Exceptions:

IllegalArgumentException if the specified capacity is not greater than zero.

template<typename E>

decaf::util::concurrent::LinkedBlockingQueue< E >::LinkedBlockingQueue ( const Collection< E > & collection ) [inline]

Create a new instance with a Capacity of Integer::MAX_VALUE and adds all the values contained in the specified collection to this Queue.

Parameters:

collection The Collection whose elements are to be copied to this Queue.

Exceptions:

IllegalStateException if the number of elements in the collection exceeds this Queue's capacity.

References DECAF_CATCH_RETHROW, DECAF_CATCHALL_THROW, and decaf::lang::Iterable< E >::iterator().

template<typename E>

virtual decaf::util::concurrent::LinkedBlockingQueue< E >::~LinkedBlockingQueue ( ) [inline, virtual]

Member Function Documentation

template<typename E>

virtual void decaf::util::concurrent::LinkedBlockingQueue< E >::clear ( ) [inline, virtual]

Removes all of the elements from this collection (optional operation).The collection will be empty after this method returns.This implementation iterates over this collection, removing each element using the Iterator.remove operation. Most implementations will probably choose to override this method for efficiency.Note that this implementation will throw an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection is non-empty.

Exceptions:

UnsupportedOperationException if the clear operation is not supported by this collection

This implementation repeatedly invokes poll until it returns false.

Reimplemented from decaf::util::AbstractQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::getAndSet(), decaf::util::AbstractCollection< E >::lock(), decaf::util::concurrent::Mutex::notify(), and decaf::util::concurrent::atomic::AtomicInteger::set().

Referenced by decaf::util::concurrent::LinkedBlockingQueue< E >::operator=().

template<typename E>

virtual int decaf::util::concurrent::LinkedBlockingQueue< E >::drainTo ( Collection< E > & c ) [inline, virtual]

Removes all available elements from this queue and adds them to the given collection.

This operation may be more efficient than repeatedly polling this queue. A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

c	the collection to transfer elements into

Returns:: the number of elements transferred

Exceptions:

UnsupportedOperationException	if addition of elements is not supported by the specified collection
IllegalArgumentException	if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::lang::Integer::MAX_VALUE.

template<typename E>

virtual int decaf::util::concurrent::LinkedBlockingQueue< E >::drainTo	(	Collection< E > &	c,
		int	maxElements
	)		`[inline, virtual]`

Removes at most the given number of available elements from this queue and adds them to the given collection.

A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

c	the collection to transfer elements into
maxElements	the maximum number of elements to transfer

Returns:: the number of elements transferred

Exceptions:

UnsupportedOperationException	if addition of elements is not supported by the specified collection
IllegalArgumentException	if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::Collection< E >::add(), decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndAdd(), and decaf::lang::Math::min().

template<typename E>

virtual decaf::util::Iterator<E>* decaf::util::concurrent::LinkedBlockingQueue< E >::iterator ( ) const [inline, virtual]

Implements decaf::lang::Iterable< E >.

template<typename E>

virtual decaf::util::Iterator<E>* decaf::util::concurrent::LinkedBlockingQueue< E >::iterator ( ) [inline, virtual]

Returns:: an iterator over a set of elements of type T.

Implements decaf::lang::Iterable< E >.

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::offer ( const E & value ) [inline, virtual]

Inserts the specified element into the queue provided that the condition allows such an operation.

The method is generally preferable to the collection.add(E), since the latter might throw an exception if the operation fails.

Parameters:

value the specified element to insert into the queue.

Returns:: true if the operation succeeds and false if it fails.

Exceptions:

NullPointerException	if the Queue implementation does not allow Null values to be inserted into the Queue.
IllegalArgumentException	if some property of the specified element prevents it from being added to this queue

Implements decaf::util::Queue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndIncrement(), and decaf::util::concurrent::Mutex::notify().

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::offer	(	const E &	e,
		long long	timeout,
		const TimeUnit &	unit
	)		`[inline, virtual]`

Inserts the specified element into this queue, waiting up to the specified wait time if necessary for space to become available.

Parameters:

e	the element to add
timeout	how long to wait before giving up, in units of `unit`
unit	a `TimeUnit` determining how to interpret the `timeout` parameter

Returns:: true if successful, or false if the specified waiting time elapses before space is available

Exceptions:

InterruptedException	if interrupted while waiting
NullPointerException	if the specified element is null
IllegalArgumentException	if some property of the specified element prevents it from being added to this queue

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndIncrement(), decaf::util::concurrent::Mutex::notify(), decaf::util::concurrent::TimeUnit::toMillis(), and decaf::util::concurrent::Mutex::wait().

template<typename E>

LinkedBlockingQueue<E>& decaf::util::concurrent::LinkedBlockingQueue< E >::operator= ( const Collection< E > & collection ) [inline]

References decaf::util::AbstractQueue< E >::addAll(), and decaf::util::concurrent::LinkedBlockingQueue< E >::clear().

template<typename E>

LinkedBlockingQueue<E>& decaf::util::concurrent::LinkedBlockingQueue< E >::operator= ( const LinkedBlockingQueue< E > & queue ) [inline]

References decaf::util::AbstractQueue< E >::addAll(), and decaf::util::concurrent::LinkedBlockingQueue< E >::clear().

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::peek ( E & result ) const [inline, virtual]

Gets but not removes the element in the head of the queue.

The result if successful is assigned to the result parameter.

Parameters:

result Reference to an instance of the contained type to assigned the removed value to.

Returns:: true if the element at the head of the queue was removed and assigned to the result parameter.

Implements decaf::util::Queue< E >.

References decaf::lang::Pointer< T, REFCOUNTER >::get(), and decaf::util::concurrent::atomic::AtomicInteger::get().

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::poll	(	E &	result,
		long long	timeout,
		const TimeUnit &	unit
	)		`[inline, virtual]`

Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.

Parameters:

result	the referenced value that will be assigned the value retrieved from the Queue. Undefined if this methods returned false.
timeout	how long to wait before giving up, in units of `unit`
unit	a `TimeUnit` determining how to interpret the `timeout` parameter.

Returns:: true if successful or false if the specified waiting time elapses before an element is available.

Exceptions:

InterruptedException if interrupted while waiting

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndDecrement(), decaf::util::concurrent::Mutex::notify(), decaf::util::concurrent::TimeUnit::toMillis(), and decaf::util::concurrent::Mutex::wait().

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::poll ( E & result ) [inline, virtual]

Gets and removes the element in the head of the queue.

If the operation succeeds the value of the element at the head of the Queue is assigned to the result parameter and the method returns true. If the operation fails the method returns false and the value of the result parameter is undefined.

Parameters:

result Reference to an instance of the contained type to assigned the removed value to.

Returns:: true if the element at the head of the queue was removed and assigned to the result parameter.

Implements decaf::util::Queue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndDecrement(), and decaf::util::concurrent::Mutex::notify().

template<typename E>

virtual void decaf::util::concurrent::LinkedBlockingQueue< E >::put ( const E & value ) [inline, virtual]

Inserts the specified element into this queue, waiting if necessary for space to become available.

Parameters:

value the element to add

Exceptions:

InterruptedException	if interrupted while waiting
NullPointerException	if the specified element is null
IllegalArgumentException	if some property of the specified element prevents it from being added to this queue

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndIncrement(), decaf::util::concurrent::Mutex::notify(), and decaf::util::concurrent::Mutex::wait().

template<typename E>

virtual int decaf::util::concurrent::LinkedBlockingQueue< E >::remainingCapacity ( ) const [inline, virtual]

Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer::MAX_VALUE if there is no intrinsic limit.

Note that you cannot always tell if an attempt to insert an element will succeed by inspecting remainingCapacity because it may be the case that another thread is about to insert or remove an element.

Returns:: the remaining capacity

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get().

template<typename E>

virtual bool decaf::util::concurrent::LinkedBlockingQueue< E >::remove ( const E & value ) [inline, virtual]

Removes a single instance of the specified element from the collection.More formally, removes an element e such that (value == NULL ? e == NULL : value == e), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

Parameters:

value The reference to the element to remove from this Collection.

Returns:: true if the collection was changed, false otherwise.

Exceptions:

UnsupportedOperationExceptio	if this is an unmodifiable collection.
NullPointerException	if the Collection is a container of pointers and does not allow NULL values.

This implementation iterates over the collection looking for the specified element. If it finds the element, it removes the element from the collection using the iterator's remove method.Note that this implementation throws an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection contains the specified object.

This implementation iterates over the collection looking for the specified element. If it finds the element, it removes the element from the collection using the iterator's remove method.

Note that this implementation throws an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection contains the specified object.

Reimplemented from decaf::util::AbstractCollection< E >.

References decaf::util::AbstractCollection< E >::lock().

template<typename E>

virtual int decaf::util::concurrent::LinkedBlockingQueue< E >::size ( ) const [inline, virtual]

Returns the number of elements in this collection.

If this collection contains more than Integer::MAX_VALUE elements, returns Integer::MAX_VALUE.

Returns:: the number of elements in this collection

Implements decaf::util::Collection< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get().

Referenced by decaf::util::concurrent::LinkedBlockingQueue< E >::toArray().

template<typename E>

virtual E decaf::util::concurrent::LinkedBlockingQueue< E >::take ( ) [inline, virtual]

Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Returns:: the head of this queue

Exceptions:

InterruptedException if interrupted while waiting

Implements decaf::util::concurrent::BlockingQueue< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::concurrent::atomic::AtomicInteger::getAndDecrement(), decaf::util::concurrent::Mutex::notify(), and decaf::util::concurrent::Mutex::wait().

template<typename E>

virtual std::vector<E> decaf::util::concurrent::LinkedBlockingQueue< E >::toArray ( ) const [inline, virtual]

Answers an STL vector containing copies of all elements contained in this Collection.

All the elements in the array will not be referenced by the collection. The elements in the returned array will be sorted to the same order as those returned by the iterator of this collection itself if the collection guarantees the order.

Returns:: an vector of copies of all the elements from this Collection

Reimplemented from decaf::util::AbstractCollection< E >.

References decaf::util::concurrent::atomic::AtomicInteger::get(), decaf::util::AbstractCollection< E >::lock(), and decaf::util::concurrent::LinkedBlockingQueue< E >::size().

template<typename E>

virtual std::string decaf::util::concurrent::LinkedBlockingQueue< E >::toString ( ) const [inline, virtual]

References decaf::util::concurrent::atomic::AtomicInteger::get().

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

src/main/decaf/util/concurrent/LinkedBlockingQueue.h

decaf::util::concurrent::LinkedBlockingQueue< E > Class Template Reference

Data Structures

Public Member Functions

Detailed Description

template<typename E> class decaf::util::concurrent::LinkedBlockingQueue< E >

Constructor & Destructor Documentation

Member Function Documentation

template<typename E>
class decaf::util::concurrent::LinkedBlockingQueue< E >