io.servicetalk.concurrent

Interface BlockingIterator<T>

Type Parameters:

T - the type of elements returned by this Iterator.

All Superinterfaces:

java.lang.AutoCloseable, CloseableIterator<T>, java.util.Iterator<T>

public interface BlockingIterator<T>
extends CloseableIterator<T>

An Iterator that is also an AutoCloseable and whose blocking operations support timeout durations.

This interface is meant to be the synchronous API equivalent of PublisherSource.Subscriber coupled with a PublisherSource.Subscription. If the data is not completely consumed from this Iterable then close() MUST be called. If the data is completely consumed (e.g. Iterator.hasNext() and/or hasNext(long, TimeUnit) return false) then this object is implicitly closed.

Method Summary

Modifier and Type	Method and Description
void	close() This method is used to communicate that you are no longer interested in consuming data.
boolean	hasNext(long timeout, java.util.concurrent.TimeUnit unit) The equivalent of Iterator.hasNext() but only waits for timeout duration amount of time.
T	next()
T	next(long timeout, java.util.concurrent.TimeUnit unit) The equivalent of next() but only waits for timeout duration of time.

Methods inherited from interface java.util.Iterator

forEachRemaining, hasNext, remove

Method Detail

hasNext

boolean hasNext(long timeout,
                java.util.concurrent.TimeUnit unit)
         throws java.util.concurrent.TimeoutException

The equivalent of Iterator.hasNext() but only waits for timeout duration amount of time.

Note that close() is not required to interrupt this call.

Parameters:

timeout - The duration of time to wait. If this value is non-positive that means the timeout expiration is immediate or in the past. In this case, if this implementation cannot determine if there is more data immediately (e.g. without external dependencies) then a TimeoutException should be thrown, otherwise the method can return the known status.

unit - The units for the duration of time.

Returns:

See the return value for Iterator.hasNext(). If this value is false then this object is implicitly closed.

Throws:

java.util.concurrent.TimeoutException - if the wait timed out. This object is implicitly closed if this occurs.

next

@Nullable
T next(long timeout,
                 java.util.concurrent.TimeUnit unit)
          throws java.util.concurrent.TimeoutException

The equivalent of next() but only waits for timeout duration of time.

Note that close() is not required to interrupt this call.

Parameters:

timeout - The duration of time to wait. If this value is non-positive that means the timeout expiration is immediate or in the past. In this case, if this implementation cannot determine if there is more data immediately (e.g. without external dependencies) then a TimeoutException should be thrown, otherwise the method can return the known status.

unit - The units for the duration of time.

Returns:

See the return value for next().

Throws:

java.util.NoSuchElementException - if the iteration has no more elements.

java.util.concurrent.TimeoutException - if the wait timed out. This object is implicitly closed if this occurs.

next

@Nullable
T next()

Specified by:

next in interface java.util.Iterator<T>

close

void close()
    throws java.lang.Exception

This method is used to communicate that you are no longer interested in consuming data. This provides a "best effort" notification to the producer of data that you are no longer interested in data from this Iterator. It is still possible that data may be obtained after calling this method, for example if there is data currently queued in memory.

If all the data has not been consumed (e.g. Iterator.hasNext() and/or hasNext(long, TimeUnit) have not yet returned false) this may have transport implications (e.g. if the source of data comes from a socket or file descriptor). If all data has been consumed, or this BlockingIterator has previously been closed this should be a noop.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception