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

A blocking queue in which each insert operation must wait for a corresponding remove operation by another thread, and vice versa. More...

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

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

[legend]

Data Structures
class	EmptyIterator
Public Member Functions
	SynchronousQueue ()
virtual	~SynchronousQueue ()
virtual void	put (const E &value)
	Adds the specified element to this queue, waiting if necessary for another thread to receive it.
virtual bool	offer (const E &e, long long timeout, const TimeUnit &unit)
	Inserts the specified element into this queue, waiting if necessary up to the specified wait time for another thread to receive it.
virtual bool	offer (const E &value)
	Inserts the specified element into this queue, if another thread is waiting to receive it.
virtual E	take ()
	Retrieves and removes the head of this queue, waiting if necessary for another thread to insert it.
virtual bool	poll (E &result, long long timeout, const TimeUnit &unit)
	Retrieves and removes the head of this queue, waiting if necessary up to the specified wait time, for another thread to insert it.
virtual bool	poll (E &result)
	Retrieves and removes the head of this queue, if another thread is currently making an element available.
virtual bool	equals (const Collection< E > &value) const
	Answers true if this Collection and the one given are the same size and if each element contained in the Collection given is equal to an element contained in this collection.
virtual decaf::util::Iterator < E > *	iterator ()
virtual decaf::util::Iterator < E > *	iterator () const
virtual bool	isEmpty () const
	Returns true if this collection contains no elements.
virtual int	size () const
	Returns the number of elements in this collection.
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	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 bool	contains (const E &value DECAF_UNUSED) const
virtual bool	containsAll (const Collection< E > &collection) const
	This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. If all elements are so contained true is returned, otherwise false.
virtual bool	remove (const E &value DECAF_UNUSED)
virtual bool	removeAll (const Collection< E > &collection DECAF_UNUSED)
virtual bool	retainAll (const Collection< E > &collection DECAF_UNUSED)
virtual bool	peek (E &result DECAF_UNUSED) const
virtual std::vector< E >	toArray () const
	Answers an STL vector containing copies of all elements contained in this Collection.
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 > &c, int maxElements)
	Removes at most the given number of available elements from this queue and adds them to the given collection.

---

Detailed Description

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

A blocking queue in which each insert operation must wait for a corresponding remove operation by another thread, and vice versa.

A synchronous queue does not have any internal capacity, not even a capacity of one. You cannot peek at a synchronous queue because an element is only present when you try to remove it; you cannot insert an element (using any method) unless another thread is trying to remove it; you cannot iterate as there is nothing to iterate. The head of the queue is the element that the first queued inserting thread is trying to add to the queue; if there is no such queued thread then no element is available for removal and poll() will return null. For purposes of other Collection methods (for example contains), a SynchronousQueue acts as an empty collection. This queue does not permit null elements.

Synchronous queues are similar to rendezvous channels used in CSP and Ada. They are well suited for handoff designs, in which an object running in one thread must sync up with an object running in another thread in order to hand it some information, event, or task.

This class supports an optional fairness policy for ordering waiting producer and consumer threads. By default, this ordering is not guaranteed. However, a queue constructed with fairness set to true grants threads access in FIFO order.

This class and its iterator implement all of the optional methods of the Collection and Iterator interfaces.

Since:

1.0

---

Constructor & Destructor Documentation

template<typename E >

decaf::util::concurrent::SynchronousQueue< E >::SynchronousQueue

(

)

[inline]

template<typename E >

virtual decaf::util::concurrent::SynchronousQueue< E >::~SynchronousQueue

(

)

[inline, virtual]

---

Member Function Documentation

template<typename E >

virtual void decaf::util::concurrent::SynchronousQueue< 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.

This implementation repeatedly invokes poll until it returns false.

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

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::contains

(

const E &value

DECAF_UNUSED

)

const [inline, virtual]

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::containsAll

(

const Collection< E > &

collection

)

const [inline, virtual]

This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. If all elements are so contained true is returned, otherwise false.

This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. If all elements are so contained true is returned, otherwise false.

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

References decaf::util::Collection< E >::isEmpty().

template<typename E >

virtual int decaf::util::concurrent::SynchronousQueue< 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::AbstractQueue< E >::element(), and decaf::util::concurrent::SynchronousQueue< E >::poll().

template<typename E >

virtual int decaf::util::concurrent::SynchronousQueue< 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::util::Collection< E >::add(), decaf::util::AbstractQueue< E >::element(), and decaf::util::concurrent::SynchronousQueue< E >::poll().

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::equals

(

const Collection< E > &

collection

)

const [inline, virtual]

Answers true if this Collection and the one given are the same size and if each element contained in the Collection given is equal to an element contained in this collection.

Parameters:

collection

- The Collection to be compared to this one.

Returns:

true if this Collection is equal to the one given.

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

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::isEmpty

(

)

const [inline, virtual]

Returns true if this collection contains no elements.

This implementation returns size() == 0.

Returns:

true if the size method return 0.

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

template<typename E >

virtual decaf::util::Iterator<E>* decaf::util::concurrent::SynchronousQueue< E >::iterator

(

)

const [inline, virtual]

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

template<typename E >

virtual decaf::util::Iterator<E>* decaf::util::concurrent::SynchronousQueue< 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::SynchronousQueue< E >::offer

(

const E &

value

)

[inline, virtual]

Inserts the specified element into this queue, if another thread is waiting to receive it.

Parameters:

value

the element to add to the Queue

Returns:

true if the element was added to this queue, else false

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 >.

template<typename E >

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

Inserts the specified element into this queue, waiting if necessary up to the specified wait time for another thread to receive it.

Returns:

true if successful, or false if the specified waiting time elapses before a consumer appears.

Exceptions:

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

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

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::peek

(

E &result

DECAF_UNUSED

)

const [inline, virtual]

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::poll

(

E &

result

)

[inline, virtual]

Retrieves and removes the head of this queue, if another thread is currently making an element available.

Parameters:

result

a reference to the value where the head of the Queue should be copied to.

Returns:

true if the head of the Queue was copied to the result param or false if no value could be returned.

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

template<typename E >

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

Retrieves and removes the head of this queue, waiting if necessary up to the specified wait time, for another thread to insert it.

Parameters:

	result	a reference to the value where the head of the Queue should be copied to.
	timeout	the time that the method should block if there is no element available to return.
	unit	the Time Units that the timeout value represents.

Returns:

true if the head of the Queue was copied to the result param or false if no value could be returned.

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

Referenced by decaf::util::concurrent::SynchronousQueue< E >::drainTo().

template<typename E >

virtual void decaf::util::concurrent::SynchronousQueue< E >::put

(

const E &

value

)

[inline, virtual]

Adds the specified element to this queue, waiting if necessary for another thread to receive it.

Parameters:

value

the element to add to the Queue.

Exceptions:

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

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

template<typename E >

virtual int decaf::util::concurrent::SynchronousQueue< 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 >.

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::remove

(

const E &value

DECAF_UNUSED

)

[inline, virtual]

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::removeAll

(

const Collection< E > &collection

DECAF_UNUSED

)

[inline, virtual]

template<typename E >

virtual bool decaf::util::concurrent::SynchronousQueue< E >::retainAll

(

const Collection< E > &collection

DECAF_UNUSED

)

[inline, virtual]

template<typename E >

virtual int decaf::util::concurrent::SynchronousQueue< 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 >.

template<typename E >

virtual E decaf::util::concurrent::SynchronousQueue< E >::take

(

)

[inline, virtual]

Retrieves and removes the head of this queue, waiting if necessary for another thread to insert it.

Returns:

the head of this queue

Exceptions:

InterruptedException

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

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

template<typename E >

virtual std::vector<E> decaf::util::concurrent::SynchronousQueue< 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 >.

---

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

• src/main/decaf/util/concurrent/SynchronousQueue.h