Package io.servicetalk.concurrent

Interface BlockingIterable<T>

Type Parameters:

T - the type of elements returned by the BlockingIterator.

All Superinterfaces:

CloseableIterable<T>, Iterable<T>

All Known Subinterfaces:

BlockingIterable.Processor<T>, HttpMessageBodyIterable<T>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface BlockingIterable<T>
extends CloseableIterable<T>

An Iterable which supports generation of BlockingIterators.

This interface is meant to be the synchronous API equivalent of PublisherSource. Each call to iterator() is equivalent to calling PublisherSource.subscribe(Subscriber) and typically has the same characteristics in terms of being able to call the method multiple times and data availability in memory.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	BlockingIterable.Processor<T>	A BlockingIterable that supports to dynamically emitting items using BlockingIterable.Processor.next(Object).

Method Summary

Modifier and Type	Method	Description
default void	forEach(Consumer<? super T> action)
default void	forEach(Consumer<? super T> action, long timeout, TimeUnit unit)	Mimics the behavior of forEach(Consumer) but applies a timeout duration for the overall completion of this method.
default void	forEach(Consumer<? super T> action, LongSupplier timeoutSupplier, TimeUnit unit)	Mimics the behavior of forEach(Consumer) but uses the timeoutSupplier to determine the timeout value for interactions with the BlockingIterator.
BlockingIterator<T>	iterator()
default BlockingSpliterator<T>	spliterator()	The same behavior as Iterable.spliterator(), but returns a BlockingSpliterator view.

Method Details

iterator

BlockingIterator<T> iterator()

Specified by:

iterator in interface CloseableIterable<T>

Specified by:

iterator in interface Iterable<T>

forEach

default void forEach(Consumer<? super T> action)

Specified by:

forEach in interface Iterable<T>

forEach

default void forEach(Consumer<? super T> action,
 LongSupplier timeoutSupplier,
 TimeUnit unit)
              throws TimeoutException

Mimics the behavior of forEach(Consumer) but uses the timeoutSupplier to determine the timeout value for interactions with the BlockingIterator.

By default, the timeoutSupplier will be used for each interaction with BlockingIterator.hasNext(long, TimeUnit) and BlockingIterator.next(long, TimeUnit). However, implementations of BlockingIterable may decide to only apply the timeout when they are not sure if an interaction with the BlockingIterator will block or not.

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:

action - The action to be performed for each element.

timeoutSupplier - A LongSupplier that provides the timeout duration for the next call to BlockingIterator.hasNext(long, TimeUnit) and BlockingIterator.next(long, TimeUnit). These methods should be consulted for the meaning of non-positive timeout durations.

unit - The units for the duration of time.

Throws:

TimeoutException - If an individual call to BlockingIterator.hasNext(long, TimeUnit) takes longer than the timeout duration.

forEach

default void forEach(Consumer<? super T> action,
 long timeout,
 TimeUnit unit)
              throws TimeoutException

Mimics the behavior of forEach(Consumer) but applies a timeout duration for the overall completion of this method. The timeout is adjusted for each interaction with the BlockingIterator which may block.

Note that the timeout duration is an approximation and this duration maybe exceeded if data is available without blocking.

By default, the timeout will be used for each interaction with BlockingIterator.hasNext(long, TimeUnit) and BlockingIterator.next(long, TimeUnit). However, implementations of BlockingIterable may decide to only apply the timeout when they are not sure if an interaction with the BlockingIterator will block or not.

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:

action - The action to be performed for each element.

timeout - An approximate total duration for the overall completion of this method. This value is used to approximate because the actual duration maybe longer if data is available without blocking.

unit - The units for the duration of time.

Throws:

TimeoutException - If the total iteration time as determined by BlockingIterator.hasNext(long, TimeUnit) takes longer than the timeout duration.

spliterator

default BlockingSpliterator<T> spliterator()

The same behavior as Iterable.spliterator(), but returns a BlockingSpliterator view.

Calling BlockingSpliterator.close() may result in closing of the underlying BlockingIterator.

Specified by:

spliterator in interface Iterable<T>

Returns:

a BlockingSpliterator over the elements described by this BlockingIterable.