Class IteratingCallback

java.lang.Object

org.eclipse.jetty.util.IteratingCallback

All Implemented Interfaces:

Callback, Invocable

Direct Known Subclasses:

AsyncMiddleManServlet.ProxyReader, AsyncMiddleManServlet.ProxyReader, AsyncMiddleManServlet.ProxyReader, AsyncMiddleManServlet.ProxyReader, AsyncMiddleManServlet.ProxyWriter, AsyncMiddleManServlet.ProxyWriter, AsyncMiddleManServlet.ProxyWriter, AsyncMiddleManServlet.ProxyWriter, AsyncProxyServlet.StreamReader, AsyncProxyServlet.StreamReader, AsyncProxyServlet.StreamReader, AsyncProxyServlet.StreamReader, ControlFlusher, InstructionFlusher, IteratingNestedCallback, MessageFlusher, WebSocketDemander

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static enum	IteratingCallback.Action	The indication of the overall progress of the iteration that implementations of process() must return.

Nested classes/interfaces inherited from interface Callback

Callback.Combination, Callback.Completable, Callback.Completing, Callback.Nested

Nested classes/interfaces inherited from interface Invocable

Invocable.Callable, Invocable.InvocationType, Invocable.ReadyTask, Invocable.Task

Field Summary

Fields inherited from interface Callback

NOOP, NOT_CALLED

Fields inherited from interface Invocable

__nonBlocking

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	IteratingCallback()
protected	IteratingCallback(boolean needReset)

Method Summary

Modifier and Type	Method	Description
final boolean	abort(Throwable cause)	Method to invoke to stop further processing iterations.
final void	close()	Method to invoke to forbid further invocations to iterate() and reset().
final void	failed(Throwable cause)	Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration.
boolean	isAborted()
boolean	isClosed()
boolean	isFailed()
boolean	isSucceeded()
void	iterate()	This method must be invoked by applications to start the processing of asynchronous sub-tasks.
protected void	onAborted(Throwable cause)	Invoked when the overall task has been aborted.
protected void	onCompleted(Throwable causeOrNull)	Invoked when the overall task has completed.
protected void	onCompleteFailure(Throwable cause)	Invoked when the overall task has completed with a failure.
protected void	onCompleteSuccess()	Invoked when the overall task has completed successfully, specifically after any IteratingCallback.Action.SCHEDULED operations have Callback.succeeded() and process() has returned IteratingCallback.Action.SUCCEEDED.
protected void	onFailure(Throwable cause)	Invoked when the overall task has been aborted or failed.
protected void	onSuccess()	Invoked when one task has completed successfully, either by the caller thread or by the processing thread.
protected abstract IteratingCallback.Action	process()	Method called by iterate() to process the asynchronous sub-task.
boolean	reset()	Resets this callback.
final void	succeeded()	Method to invoke when the asynchronous sub-task succeeds.
String	toString()

Methods inherited from class Object

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

Methods inherited from interface Callback

completeWith

Methods inherited from interface Invocable

getInvocationType

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:

• IteratingCallback.Action.IDLE when no sub tasks are available for execution but the overall job is not completed yet
• IteratingCallback.Action.SCHEDULED when the sub task asynchronous execution has been started
• IteratingCallback.Action.SUCCEEDED when the overall job is completed

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.

onFailure

protected void onFailure(Throwable cause)

Invoked when the overall task has been aborted or failed.

Calls to this method are serialized with respect to onAborted(Throwable), process(), onCompleteFailure(Throwable) and onCompleted(Throwable).

Because onFailure can be called due to an abort(Throwable) or close() operation, it is possible that any resources passed to a IteratingCallback.Action.SCHEDULED operation may still be in use, and thus should not be recycled by this call. For example any buffers passed to a write operation should not be returned to a buffer pool by implementations of onFailure. Such resources may be discarded here, or safely recycled in a subsequent call to onCompleted(Throwable) or onCompleteFailure(Throwable), when the IteratingCallback.Action.SCHEDULED operation has completed.

Parameters:

cause - The cause of the failure or abort

See Also:

• onCompleted(Throwable)
• onCompleteFailure(Throwable)

onCompleteSuccess

protected void onCompleteSuccess()

Invoked when the overall task has completed successfully, specifically after any IteratingCallback.Action.SCHEDULED operations have Callback.succeeded() and process() has returned IteratingCallback.Action.SUCCEEDED.

Calls to this method are serialized with respect to process(), onAborted(Throwable) and onCompleted(Throwable). If this method is called, then onCompleteFailure(Throwable) ()} will never be called.

See Also:

• onCompleteFailure(Throwable)

onCompleteFailure

protected void onCompleteFailure(Throwable cause)

Invoked when the overall task has completed with a failure.

Calls to this method are serialized with respect to process(), onAborted(Throwable) and onCompleted(Throwable). If this method is called, then onCompleteSuccess() will never be called.

Parameters:

cause - the throwable to indicate cause of failure

See Also:

• onCompleteSuccess()

onAborted

protected void onAborted(Throwable cause)

Invoked when the overall task has been aborted.

Calls to this method are serialized with respect to process(), onCompleteFailure(Throwable) and onCompleted(Throwable). If this method is called, then onCompleteSuccess() will never be called.

The default implementation of this method calls failed(Throwable). Overridden implementations of this method SHOULD NOT call super.onAborted(Throwable).

Because onAborted can be called due to an abort(Throwable) or close() operation, it is possible that any resources passed to a IteratingCallback.Action.SCHEDULED operation may still be in use, and thus should not be recycled by this call. For example any buffers passed to a write operation should not be returned to a buffer pool by implementations of onFailure. Such resources may be discarded here, or safely recycled in a subsequent call to onCompleted(Throwable) or onCompleteFailure(Throwable), when the IteratingCallback.Action.SCHEDULED operation has completed.

Parameters:

cause - The cause of the abort

See Also:

• onCompleted(Throwable)
• onCompleteFailure(Throwable)

onCompleted

protected void onCompleted(Throwable causeOrNull)

Invoked when the overall task has completed.

Calls to this method are serialized with respect to process() and onAborted(Throwable). The default implementation of this method will call either onCompleteSuccess() or onCompleteFailure(Throwable) thus implementations of this method should always call super.onCompleted(Throwable).

Parameters:

causeOrNull - the cause of any abort or failure, else null for success.

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 final void succeeded()

Method to invoke when the asynchronous sub-task succeeds.

For most purposes, this method should be considered final and should only be overridden in extraordinary circumstances. Subclasses that override this method must always call super.succeeded(). Such overridden methods are not serialized with respect to process(), onCompleteSuccess(), onCompleteFailure(Throwable), nor onAborted(Throwable). They should not act on nor change any fields that may be used by those methods. Eventually, onSuccess() is called, either by the caller thread or by the processing thread.

Specified by:

succeeded in interface Callback

See Also:

• Callback.failed(Throwable)

failed

public final void failed(Throwable cause)

Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration.

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

For most purposes, this method should be considered final and should only be overridden in extraordinary circumstances. Subclasses that override this method must always call super.succeeded(). Such overridden methods are not serialized with respect to process(), onCompleteSuccess(), onCompleteFailure(Throwable), nor onAborted(Throwable). They should not act on nor change any fields that may be used by those methods.

Specified by:

failed in interface Callback

Parameters:

cause - the reason for the operation failure

See Also:

• isFailed()

close

public final 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:

• isClosed()

abort

public final boolean abort(Throwable cause)

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:

cause - the cause of the abort

Returns:

true if abort was called before the callback was complete.

See Also:

• isAborted()

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:

• onCompleteSuccess()

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