Package org.eclipse.jetty.util

Class IteratingCallback

java.lang.Object
org.eclipse.jetty.util.IteratingCallback
All Implemented Interfaces:
Callback, Invocable
Direct Known Subclasses:
AsyncMiddleManServlet.ProxyReader, AsyncProxyServlet.StreamReader, ControlFlusher, DemandingFlusher, FrameFlusher, HTTP2Flusher, InstructionFlusher, IteratingNestedCallback, MessageFlusher
public abstract class IteratingCallback extends Object implements Callback
This specialized callback implements a pattern that allows a large asynchronous task to be broken into smaller asynchronous sub-tasks using iteration rather than recursion.

A typical example is the write of a large content to a socket, divided in chunks. Chunk C1 is written by thread T1, which also invokes the callback, which writes chunk C2, which invokes the callback again, which writes chunk C3, and so forth.

The problem with the example above is that if the callback thread is the same that performs the I/O operation, then the process is recursive and may result in a stack overflow. To avoid the stack overflow, a thread dispatch must be performed, causing context switching and cache misses, affecting performance.

To avoid this issue, this callback atomically records whether the callback for an asynchronous sub-task has been called during the processing of the asynchronous sub-task, and if so then the processing of the large asynchronous task iterates rather than recursing.

Subclasses must implement method process() where the asynchronous sub-task is initiated and a suitable IteratingCallback.Action is returned to this callback to indicate the overall progress of the large asynchronous task. This callback is passed to the asynchronous sub-task, and a call to succeeded() on this callback represents the successful completion of the asynchronous sub-task, while a call to failed(Throwable) on this callback represents the completion with a failure of the large asynchronous task.

  • Constructor Details

    • IteratingCallback

      protected IteratingCallback()

    • IteratingCallback

      protected IteratingCallback(boolean needReset)

  • Method Details

    • process

      protected abstract IteratingCallback.Action process() throws Throwable
      Method called by iterate() to process the asynchronous sub-task.

      Implementations must initiate the asynchronous execution of the sub-task (if any) and return an appropriate action:

      Returns:
      the appropriate Action
      Throws:
      Throwable - if the sub-task processing throws

    • onSuccess

      protected void onSuccess()
      Invoked when one task has completed successfully, either by the caller thread or by the processing thread. This invocation is always serialized w.r.t the execution of process().

      This method is not invoked when a call to abort(Throwable) is made before the succeeded() callback happens.

    • onCompleteSuccess

      protected void onCompleteSuccess()
      Invoked when the overall task has completed successfully.
      See Also:

    • onCompleteFailure

      protected void onCompleteFailure(Throwable cause)
      Invoked when the overall task has completed with a failure.
      Parameters:
      cause - the throwable to indicate cause of failure
      See Also:

    • iterate

      public void iterate()
      This method must be invoked by applications to start the processing of asynchronous sub-tasks.

      It can be called at any time by any thread, and its contract is that when called, then the process() method will be called during or soon after, either by the calling thread or by another thread, but in either case by one thread only.

    • succeeded

      public void succeeded()
      Method to invoke when the asynchronous sub-task succeeds.

      This method should be considered final for all practical purposes.

      Eventually, onSuccess() is called, either by the caller thread or by the processing thread.

      Specified by:
      succeeded in interface Callback
      See Also:

    • failed

      public void failed(Throwable x)
      Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration.

      This method should be considered final for all practical purposes.

      Eventually, onCompleteFailure(Throwable) is called, either by the caller thread or by the processing thread.

      Specified by:
      failed in interface Callback
      Parameters:
      x - the reason for the operation failure
      See Also:

    • close

      public void close()
      Method to invoke to forbid further invocations to iterate() and reset().

      When this method is invoked during processing, it behaves like invoking failed(Throwable).

      See Also:

    • abort

      public void abort(Throwable failure)

      Method to invoke to stop further processing iterations.

      This method causes onCompleteFailure(Throwable) to ultimately be invoked, either during this call or later after any call to process() has returned.

      Parameters:
      failure - the cause of the abort
      See Also:

    • isClosed

      public boolean isClosed()
      Returns:
      whether this callback has been closed

    • isFailed

      public boolean isFailed()
      Returns:
      whether this callback has been failed

    • isSucceeded

      public boolean isSucceeded()
      Returns:
      whether this callback and the overall asynchronous task has been succeeded
      See Also:

    • isAborted

      public boolean isAborted()
      Returns:
      whether this callback has been aborted

    • reset

      public boolean reset()
      Resets this callback.

      A callback can only be reset to the idle state from the succeeded or failed states or if it is already idle.

      Returns:
      true if the reset was successful

    • toString

      public String toString()
      Overrides:
      toString in class Object