Package org.threadly.concurrent

Class Poller

java.lang.Object

org.threadly.concurrent.Poller

public class Poller
extends java.lang.Object

Simple class for watching a condition and getting notified when a state has changed. One handy tool is the ability to transition java's Future into Threadly's much nicer ListenableFuture.

The frequency at which this polls should be determined based off how cheap polling is, and how many items will be polled on average.

If being allowed to garbage collect, this poller will continue to schedule itself as long as there are outstanding futures. Once all have completed (from timeout or naturally), then this will stop scheduling itself to poll for updates. Thus no explicit cleanup is needed. As long as the Supplier's are quick/fast (Future conversions are always quick/fast), it's most efficient to reuse the Poller instance. But if you need dynamic timeout's/max wait time you could construct a Poller and toss it away once you get the returned ListenableFuture from it.

Since:

5.0

Constructor Summary

Constructors

Constructor	Description
Poller(SubmitterScheduler scheduler, long pollFrequency)	Construct a new poller which will run on the provided scheduler, and run at the specified frequency.
Poller(SubmitterScheduler scheduler, long pollFrequency, long maxWaitTime)	Construct a new poller which will run on the provided scheduler, and run at the specified frequency.

Method Summary

Modifier and Type	Method	Description
<T> ListenableFuture<?>	consumeQueue(java.util.Queue<? extends T> queue, java.util.function.Consumer<? super T> consumer)	Consumes from a queue, checking for items and providing them to a Consumer as they become available.
<T> ListenableFuture<?>	consumeQueue(java.util.Queue<? extends T> queue, java.util.function.Consumer<? super T> consumer, ExceptionHandler exceptionHandler)	Consumes from a queue, checking for items and providing them to a Consumer as they become available.
<T> ListenableFuture<T>	watch(java.util.concurrent.Future<? extends T> f)	Convert a conventional Future into a ListenableFuture.
ListenableFuture<?>	watch(java.util.function.Supplier<java.lang.Boolean> p)	Watch suppliers returned condition.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Poller

public Poller(SubmitterScheduler scheduler,
              long pollFrequency)

Construct a new poller which will run on the provided scheduler, and run at the specified frequency.

Parameters:

scheduler - Scheduler to run polling task on

pollFrequency - Time in milliseconds to wait between polling events

Poller

public Poller(SubmitterScheduler scheduler,
              long pollFrequency,
              long maxWaitTime)

Construct a new poller which will run on the provided scheduler, and run at the specified frequency.

This constructor additionally allows you to specify the maximum time in millseconds we should wait for the condition to become true. At this point if we are still not seeing our expected polling state, then the return future will be canceled.

Parameters:

scheduler - Scheduler to run polling task on

pollFrequency - Time in milliseconds to wait between polling events

maxWaitTime - Maximum time in milliseconds till returned futures should be canceled

Method Detail

watch

public ListenableFuture<?> watch(java.util.function.Supplier<java.lang.Boolean> p)

Watch suppliers returned condition. Once Supplier is witnessed in the true state, the returned future is completed. Listeners and FutureCallback's executed on the returned future without a specified pool will run on the polling thread, and so should be kept to a minimum.

Parameters:

p - Supplier to provide state for when poll has completed as expected

Returns:

Future to complete once boolean state is witnessed as true

watch

public <T> ListenableFuture<T> watch(java.util.concurrent.Future<? extends T> f)

Convert a conventional Future into a ListenableFuture. As poller runs it will check if the provided future has completed. Once it does complete the returned future will also complete in the exact same way. Canceling the returned future will have NO impact on the provided future (and thus the use with a timeout is not a concern to interrupting the provided future). Because this is only checked at poll intervals the returned future's completion will be delayed by that polling delay.

Type Parameters:

T - Type of object returned from future

Parameters:

f - Future to monitor for completetion

Returns:

ListenableFuture that will provide the result from the source future

consumeQueue

public <T> ListenableFuture<?> consumeQueue(java.util.Queue<? extends T> queue,
                                            java.util.function.Consumer<? super T> consumer)

Consumes from a queue, checking for items and providing them to a Consumer as they become available. The poll interval is not the minimum consumption speed, but rather the resolution / delay that will occur after the queue is seen in an empty state. If items are available they will be provided to the Consumer as fast as possible. The Consumer will not be invoked in parallel, so if concurrent consumption is desired it must execute to a pool.

Because queue consumption is likely a long running process, this operation will ignore any timeout provided to the Poller(SubmitterScheduler, long, long) constructor.

The returned future will never complete on its own. It can only be used for stopping the consumption from the queue by invoking Future.cancel(boolean). If you never want to stop the queue consumption then the returned ListenableFuture can be ignored.

If any errors occur ExceptionUtils.handleException(Throwable) will be invoked.

Type Parameters:

T - The type of object to consume from the queue

Parameters:

queue - The queue to poll items from as they are available

consumer - The Consumer to provide items to as they are available

Returns:

A future which can stop consumption through cancel(boolean)

Since:

5.37

consumeQueue

public <T> ListenableFuture<?> consumeQueue(java.util.Queue<? extends T> queue,
                                            java.util.function.Consumer<? super T> consumer,
                                            ExceptionHandler exceptionHandler)

Consumes from a queue, checking for items and providing them to a Consumer as they become available. The poll interval is not the minimum consumption speed, but rather the resolution / delay that will occur after the queue is seen in an empty state. If items are available they will be provided to the Consumer as fast as possible. The Consumer will not be invoked in parallel, so if concurrent consumption is desired it must execute to a pool.

Because queue consumption is likely a long running process, this operation will ignore any timeout provided to the Poller(SubmitterScheduler, long, long) constructor.

The returned future may never complete. It will only complete if an error occurs (and parameter exceptionHandler was null), or if it is canceled. Invoking Future.cancel(boolean) on the returned future is how you would stop providing queue items to the Consumer. If an exceptionHandler is provided, and you never want to stop with a cancel(boolean), the returned future can be ignored.

Type Parameters:

T - The type of object to consume from the queue

Parameters:

queue - The queue to poll items from as they are available

consumer - The Consumer to provide items to as they are available

exceptionHandler - An optional handler for unexpected errors, or null to stop consumption on error

Returns:

A future which can stop consumption through cancel(boolean), and will report unhandled errors

Since:

5.37