com.bigdata.relation.accesspath
Interface IAsynchronousIterator<E>

All Superinterfaces:

ICloseableIterator<E>, Iterator<E>

All Known Implementing Classes:

BlockingBuffer.BlockingIterator, ClientAsynchronousIterator, ThickAsynchronousIterator

public interface IAsynchronousIterator<E>
extends ICloseableIterator<E>

Interface for iterators that are running asynchronously. Such iterators are the consumer side of a producer - consumer pattern. The producer writes on an IBlockingBuffer which is drained by the IAsynchronousIterator.

Version:

$Id: IAsynchronousIterator.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

See Also:

BlockingBuffer

Method Summary

void	close() Notes that the iterator is closed and hence may no longer be read.
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(long timeout, TimeUnit unit) Waits up to the timeout to return the next element.

Methods inherited from interface java.util.Iterator

hasNext, next, remove

Method Detail

isExhausted

boolean isExhausted()

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

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

boolean hasNext(long timeout,
                TimeUnit unit)
                throws InterruptedException

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.

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

E next(long timeout,
       TimeUnit unit)
       throws InterruptedException

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.

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 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 isExhausted() (non-blocking).

Throws:

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

close

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, 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 ICloseableIterator<E>