Package com.tangosol.util

Class AsynchronousAgent<T>

java.lang.Object

com.tangosol.util.AsynchronousAgent<T>

Type Parameters:

T - the type of the result

All Implemented Interfaces:

FlowControl, Future<T>

Direct Known Subclasses:

AbstractAsynchronousAggregator, AbstractAsynchronousProcessor

public abstract class AsynchronousAgent<T>
extends Object
implements FlowControl, Future<T>

Base class for asynchronous operations that provides a simple implementation of the Future interface. It is assumed that subclasses at some point will either call complete(Supplier) passing the result supplier when completed successfully or call completeExceptionally(java.lang.Throwable) passing the failure reason.

Author:

gg/mf 2012.12.21, gg/bb 2015.04.06

Field Summary

Fields

Modifier and Type	Field	Description
protected FlowControl	m_control	The underlying FlowControl; could be null if the "automatic flow control" is turned on.
protected int	m_iOrderId	A unit-of-order id associated with this agent.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AsynchronousAgent(int iOrderId)	Construct the agent.
protected	AsynchronousAgent(int iOrderId, Executor executor)	Construct the agent.

Method Summary

Modifier and Type	Method	Description
void	bind(FlowControl control)	Bind this agent with the specified underlying FlowControl object.
boolean	cancel(boolean mayInterruptIfRunning)
boolean	checkBacklog(Continuation<Void> continueNormal)	Check for an excessive backlog and if the underlying communication channel is indeed clogged, call the specified continuation when the backlog is back to normal or the service terminates.
protected boolean	complete(Supplier<T> supplier)	Should be called if the operation completed successfully.
protected boolean	completeExceptionally(Throwable eReason)	Should be called if the operation failed for any reason.
long	drainBacklog(long cMillis)	Check for an excessive backlog and allow blocking the calling thread for up to the specified amount of time.
void	flush()	Ensure that any buffered asynchronous operations are dispatched to the underlying tier.
T	get()
T	get(long cTimeout, TimeUnit unit)
CompletableFuture<T>	getCompletableFuture()	Get the CompletableFuture.
Throwable	getException()	Helper method that returns an exception (if completed exceptionally).
T	getResult()	Helper method that calls get() and re-throws checked exceptions as a RuntimeException.
int	getUnitOfOrderId()	Return a unit-of-order id associated with this agent.
boolean	isCancelled()
boolean	isCompletedExceptionally()	Helper method to check if the operation failed.
boolean	isDone()

Methods inherited from class java.lang.Object

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

Field Detail

m_control

protected FlowControl m_control

The underlying FlowControl; could be null if the "automatic flow control" is turned on.

m_iOrderId

protected final int m_iOrderId

A unit-of-order id associated with this agent.

Constructor Detail

AsynchronousAgent

protected AsynchronousAgent(int iOrderId)

Construct the agent.

Parameters:

iOrderId - a unit-of-order id associated with this agent. Ordering semantics of operations based on this id are defined by subclasses

AsynchronousAgent

protected AsynchronousAgent(int iOrderId,
                            Executor executor)

Construct the agent.

Parameters:

iOrderId - a unit-of-order id associated with this agent. Ordering semantics of operations based on this id are defined by subclasses

executor - an optional Executor to complete the future on, if not provided the Daemons.commonPool() is used

Method Detail

bind

public void bind(FlowControl control)

Bind this agent with the specified underlying FlowControl object. This method is to be used only internally by the service.

Parameters:

control - the underlying FlowControl

flush

public void flush()

Description copied from interface: FlowControl

Ensure that any buffered asynchronous operations are dispatched to the underlying tier.

Note: this is a non-blocking call.

Specified by:

flush in interface FlowControl

drainBacklog

public long drainBacklog(long cMillis)

Description copied from interface: FlowControl

Check for an excessive backlog and allow blocking the calling thread for up to the specified amount of time.

Specified by:

drainBacklog in interface FlowControl

Parameters:

cMillis - the maximum amount of time to wait (in milliseconds), or zero for infinite wait

Returns:

the remaining timeout or a negative value if timeout has occurred (the return of zero is only allowed for infinite timeout and indicates that the backlog is no longer excessive)

checkBacklog

public boolean checkBacklog(Continuation<Void> continueNormal)

Description copied from interface: FlowControl

Check for an excessive backlog and if the underlying communication channel is indeed clogged, call the specified continuation when the backlog is back to normal or the service terminates. It's important to remember that:

1. The continuation could be called on any thread; concurrently with the calling thread or on the calling thread itself.
2. The continuation is called if and only if this method returns true.
3. The continuation must not make any blocking calls.

Specified by:

checkBacklog in interface FlowControl

Parameters:

continueNormal - (optional) Continuation to be called when the backlog has been reduced back to normal

Returns:

true if the underlying communication channel is backlogged; false otherwise

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Specified by:

cancel in interface Future<T>

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface Future<T>

isDone

public boolean isDone()

Specified by:

isDone in interface Future<T>

get

public T get()
      throws InterruptedException,
             ExecutionException

Specified by:

get in interface Future<T>

Throws:

InterruptedException

ExecutionException

get

public T get(long cTimeout,
             TimeUnit unit)
      throws InterruptedException,
             ExecutionException,
             TimeoutException

Specified by:

get in interface Future<T>

Throws:

InterruptedException

ExecutionException

TimeoutException

getUnitOfOrderId

public int getUnitOfOrderId()

Return a unit-of-order id associated with this agent. By default, the unit-of-order id is assigned to the calling thread's hashCode.

Note 1: the ordering guarantee is respected between AsynchronousAggregators and AsynchronousProcessors with the same unit-of-order id;
Note 2: there is no ordering guarantee between asynchronous and synchronous operations.

Returns:

the order id

See Also:

AbstractAsynchronousAggregator.getUnitOfOrderId(), AbstractAsynchronousProcessor.getUnitOfOrderId()

complete

protected boolean complete(Supplier<T> supplier)

Should be called if the operation completed successfully.

Parameters:

supplier - the supplier of the result of the asynchronous execution

Returns:

true if agent could be marked to complete with the given Supplier.

completeExceptionally

protected boolean completeExceptionally(Throwable eReason)

Should be called if the operation failed for any reason.

Parameters:

eReason - the reason of failure

Returns:

true if agent could be marked to complete with the given exception.

getResult

public T getResult()

Helper method that calls get() and re-throws checked exceptions as a RuntimeException.

Returns:

the result value

getException

public Throwable getException()

Helper method that returns an exception (if completed exceptionally).

Returns:

the exception or null if the operation completed successfully

isCompletedExceptionally

public boolean isCompletedExceptionally()

Helper method to check if the operation failed.

Returns:

true if the operation failed

getCompletableFuture

public CompletableFuture<T> getCompletableFuture()

Get the CompletableFuture.

Returns:

CompletableFuture