Package io.servicetalk.concurrent

Interface BlockingIterator<T>

Type Parameters:
T - the type of elements returned by this Iterator.
All Superinterfaces:
AutoCloseable, CloseableIterator<T>, Iterator<T>
All Known Subinterfaces:
HttpMessageBodyIterator<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
    Description
    void
    close()
    This method is used to communicate that you are no longer interested in consuming data.
    boolean
    hasNext(long timeout, TimeUnit unit)
    The equivalent of Iterator.hasNext() but only waits for timeout duration amount of time.
    T
    next()
    T
    next(long timeout, 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 Details

    • hasNext

      boolean hasNext(long timeout, TimeUnit unit) throws 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.

      Also note, this method can sneaky-throw an InterruptedException when a blocking operation internally does so. The reason it's not declared is that the Iterator and AutoCloseable interfaces do not declare checked exceptions and BlockingIterator extends them to allow use in try-with-resources and enhanced for loop.

      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:
      TimeoutException - if the wait timed out. This object is implicitly closed if this occurs.

    • next

      @Nullable T next(long timeout, TimeUnit unit) throws TimeoutException
      The equivalent of next() but only waits for timeout duration of time.

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

      Also note, this method can sneaky-throw an InterruptedException when a blocking operation internally does so. The reason it's not declared is that the Iterator and AutoCloseable interfaces do not declare checked exceptions and BlockingIterator extends them to allow use in try-with-resources and enhanced for loop.

      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:
      NoSuchElementException - if the iteration has no more elements.
      TimeoutException - if the wait timed out. This object is implicitly closed if this occurs.

    • next

      @Nullable T next()

      Note, this method can sneaky-throw an InterruptedException when a blocking operation internally does so. The reason it's not declared is that the Iterator and AutoCloseable interfaces do not declare checked exceptions and BlockingIterator extends them to allow use in try-with-resources and enhanced for loop.

      Specified by:
      next in interface Iterator<T>

    • close

      void close() throws 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 AutoCloseable
      Throws:
      Exception