com.bigdata.relation.accesspath
Class BlockingBuffer.BlockingIterator

java.lang.Object
  com.bigdata.relation.accesspath.BlockingBuffer.BlockingIterator

All Implemented Interfaces:

IAsynchronousIterator<E>, ICloseableIterator<E>, Iterator<E>

Enclosing class:

BlockingBuffer<E>

protected class BlockingBuffer.BlockingIterator
extends Object
implements IAsynchronousIterator<E>

An inner class that reads from the buffer. This is not thread-safe - it makes no attempt to be atomic in its operations in hasNext() or next().

Version:

$Id: BlockingBuffer.java 6130 2012-03-15 10:31:25Z thompsonbry $

Author:

Bryan Thompson

Method Summary

void	close() Notes that the iterator is closed and hence may no longer be read.
boolean	hasNext() Return true iff there is at least one element that can be visited (blocking).
boolean	hasNext(long timeout, TimeUnit unit) Return true iff there is at least one element that can be visited.
boolean	isExhausted() Return true iff this iterator will not visit any more elements (non-blocking).
E	next() Return the next element.
E	next(long timeout, TimeUnit unit) Waits up to the timeout to return the next element.
void	remove() The operation is not supported.
String	toString() Safe non-blocking representation of the iterator state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

toString

public String toString()

Safe non-blocking representation of the iterator state.

Overrides:

toString in class Object

close

public void close()

Notes that the iterator is closed and hence may no longer be read. It is safe to invoke this method even if the iterator is closed. However, if the producer is still running then it will be canceled (interrupted) in order to prevent the IBlockingBuffer from filling up and deadlocking. For this reason, IAsynchronousIterator.close() has consequences NOT entailed by ICloseableIterator.

Note: Depending on the semantics of the producer, it MAY choose to treat an interrupt() as normal (but eager) termination. For example, rule execution treats an interrupt() as normal (but eager) termination with the consequence that queries may be safely interrupted once some limit has been satisfied. However, the preferred way to treat LIMIT is using IRule with an IQueryOptions that specifies a LIMIT.

Specified by:

close in interface IAsynchronousIterator<E>

Specified by:

close in interface ICloseableIterator<E>

See Also:

BlockingBuffer.iterator()

isExhausted

public boolean isExhausted()

Description copied from interface: IAsynchronousIterator

Return true iff this iterator will not visit any more elements (non-blocking).

Specified by:

isExhausted in interface IAsynchronousIterator<E>

Returns:

true iff the iterator is known to be exhausted without blocking. A false return does NOT imply that the iterator will visit more elements, only that it MIGHT visit more elements.

hasNext

public boolean hasNext()

Return true iff there is at least one element that can be visited (blocking). If the buffer is empty then this will block until: (a) an element appears in the buffer; or (b) the buffer is BlockingBuffer.close()ed.

Specified by:

hasNext in interface Iterator<E>

hasNext

public boolean hasNext(long timeout,
                       TimeUnit unit)
                throws InterruptedException

Description copied from interface: IAsynchronousIterator

Return true iff there is at least one element that can be visited. If the buffer is empty then this will block until: (a) an element appears in the buffer; (b) the buffer is BlockingBuffer.close()ed; or (c) the timeout expires.

Note that a false return DOES NOT signify that the iterator is exhausted. However, if you specify an infinite timeout using Long.MAX_VALUE TimeUnit.SECONDS then you MAY safely interpret a false return as an indication that the iterator is exhausted.

Specified by:

hasNext in interface IAsynchronousIterator<E>

Parameters:

timeout - The length of time that the method may block awaiting an element to appear.

unit - The units in which the timeout is expressed.

Returns:

true iff there is an element available.

Throws:

InterruptedException - if the current thread is interrupted while waiting another element.

next

public E next(long timeout,
              TimeUnit unit)
       throws InterruptedException

Description copied from interface: IAsynchronousIterator

Waits up to the timeout to return the next element. When the generic type of the elements in the buffer is an array type and there is more than one element available within the specified time, then multiple elements in the buffer MAY be combined into a single element and that element returned to the caller.

Specified by:

next in interface IAsynchronousIterator<E>

Parameters:

timeout - The timeout (overrides the chunkTimeout specified to the BlockingBuffer ctor).

unit - The unit in which the timeout is expressed.

Returns:

The element -or- null iff the timeout was exceeded before IAsynchronousIterator.hasNext(long, TimeUnit) returned true.

In order to have a definitive indication that the iterator is exhausted you need to invoke Iterator.hasNext() without a timeout (blocking) or IAsynchronousIterator.isExhausted() (non-blocking).

Throws:

InterruptedException - if the current thread is interrupted while waiting for another element.

next

public E next()

Return the next element. If the element is an array type, then the optional chunk combiner may be applied to aggregate chunks. When the chunk combiner is applied, this method will block until either a chunk of sufficient size has been accumulated -or- the chunk combiner timeout has been exceeded. In either case, it will then return the chunk which was accumulated.

Specified by:

next in interface Iterator<E>

remove

public void remove()

The operation is not supported.

Specified by:

remove in interface Iterator<E>