Skip navigation links

com.tangosol.util
Class AsynchronousAgent

java.lang.Object
com.tangosol.util.AsynchronousAgent

All Implemented Interfaces:

FlowControl, java.util.concurrent.Future

Direct Known Subclasses:

AsynchronousAggregator, AsynchronousProcessor

public abstract class AsynchronousAgent

extends java.lang.Object

implements java.util.concurrent.Future, FlowControl

Base class for asynchronous operations that provides a simple implementation of the Future interface. It is assumed that subclasses at some point will provide either the result of successful execution or a failure reason.

Author:

gg/mf 2012.12.21

Field Summary

protected FlowControl	m_control The underlying FlowControl; could be null if the "automatic flow control" is turned on.
protected java.lang.Throwable	m_eReason A reason of operation failure.
protected boolean	m_fFlowControl Specifies whether or not the caller is a subject of the automatic flow control, e.g. the calling thread could be held by the service flow control logic.
protected int	m_iOrderId A unit-of-order id associated with this agent.
protected java.lang.Object	m_oResult A result of operation (if successful).

Constructor Summary

protected

AsynchronousAgent(boolean fFlowControl, int iOrderId) Construct the agent.

Method Summary

void	bind(FlowControl control) Bind this agent with the specified underlying FlowControl object.
boolean	cancel(boolean mayInterruptIfRunning)
boolean	checkBacklog(com.oracle.common.base.Continuation 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.
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.
java.lang.Object	get()
java.lang.Object	get(long cTimeout, java.util.concurrent.TimeUnit unit)
boolean	isAutoFlowControl() Specifies whether or not the caller is a subject of the automatic flow control, e.g. the calling thread could be held by the service flow control logic.
boolean	isCancelled()
boolean	isDone()
protected void	setException(java.lang.Throwable eReason) Should be called if the operation failed for any reason.
protected void	setResult(java.lang.Object oResult) Should be called if the operation completed successfully.
java.lang.String	toString()

Field Detail

m_control

protected FlowControl m_control

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

m_fFlowControl

protected final boolean m_fFlowControl

Specifies whether or not the caller is a subject of the automatic flow control, e.g. the calling thread could be held by the service flow control logic.

m_iOrderId

protected final int m_iOrderId

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

m_oResult

protected java.lang.Object m_oResult

A result of operation (if successful).

m_eReason

protected java.lang.Throwable m_eReason

A reason of operation failure.

Constructor Detail

AsynchronousAgent

protected AsynchronousAgent(boolean fFlowControl,
                            int iOrderId)

Construct the agent.

Parameters:

fFlowControl - pass true if the calling thread could be held by the service flow control logic; otherwise it's the callers responsibility to modulate the flow (e.g. ensure that the invocation rate does not outpace the response rate)

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

Method Detail

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Specified by:

cancel in interface java.util.concurrent.Future

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface java.util.concurrent.Future

isDone

public boolean isDone()

Specified by:

isDone in interface java.util.concurrent.Future

get

public java.lang.Object get()
                     throws java.lang.InterruptedException,
                            java.util.concurrent.ExecutionException

Specified by:

get in interface java.util.concurrent.Future

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

get

public java.lang.Object get(long cTimeout,
                            java.util.concurrent.TimeUnit unit)
                     throws java.lang.InterruptedException,
                            java.util.concurrent.ExecutionException,
                            java.util.concurrent.TimeoutException

Specified by:

get in interface java.util.concurrent.Future

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException

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(com.oracle.common.base.Continuation 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

setResult

protected void setResult(java.lang.Object oResult)

Should be called if the operation completed successfully.

Parameters:

oResult - the result of the asynchronous execution

setException

protected void setException(java.lang.Throwable eReason)

Should be called if the operation failed for any reason.

Parameters:

eReason - the reason of failure

isAutoFlowControl

public boolean isAutoFlowControl()

Specifies whether or not the caller is a subject of the automatic flow control, e.g. the calling thread could be held by the service flow control logic. If false, it's the callers responsibility to modulate the flow (e.g. ensure that the invocation rate does not outpace the response rate).

Returns:

true if the calling thread could be held by the flow control

toString

public java.lang.String toString()

Skip navigation links