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 Details

    • 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.

    • m_converter

      protected Converter<Binary,T> m_converter
      Converter from internal format.

  • Constructor Details

    • 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 Details

    • 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:

    • 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

    • setValueConverter

      public void setValueConverter(Converter<Binary,T> converter)
      Set the converter from internal format.
      Parameters:
      converter - the converter from internal format
      Implementation Note:
      This method is only called by RequestCoordinator.createContext, so it is very much internal, but it has to be public in order to be accessible.