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 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 and Inner Type Summary

Modifier and Type	Class and Description
protected static enum	IteratingCallback.Action The indication of the overall progress of the iteration that implementations of `process()` must return.
private static enum	IteratingCallback.State The internal states of this callback.

Field Summary

Modifier and Type	Field and Description
private Throwable	_failure
private boolean	_iterate
private final AutoLock	_lock
private IteratingCallback.State	_state

Constructor Summary

Access	Constructor and Description
protected	IteratingCallback()
protected	IteratingCallback(boolean needReset)

Method Summary

Modifier and Type	Method and Description
public void	abort(Throwable the cause of the abort failure) Method to invoke to stop further processing iterations.
public void	close() Method to invoke to forbid further invocations to `iterate()` and `reset()`.
public void	failed(Throwable the reason for the operation failure x) Overrides default org.eclipse.jetty.util.Callback.failed. Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration.
public boolean	isAborted() Returns: whether this callback has been `aborted`
public boolean	isClosed() Returns: whether this callback has been `closed`
public boolean	isFailed() Returns: whether this callback has been `failed`
pack-priv boolean	isIdle() Returns: whether this callback is idle, and `iterate()` needs to be called
public boolean	isSucceeded() Returns: whether this callback and the overall asynchronous task has been succeeded
public void	iterate() This method must be invoked by applications to start the processing of asynchronous sub-tasks.
protected void	onCompleteFailure(Throwable the throwable to indicate cause of failure cause) Invoked when the overall task has completed with a failure.
protected void	onCompleteSuccess() Invoked when the overall task has completed successfully.
protected abstract IteratingCallback.Action	Returns: the appropriate Action process() Method called by `iterate()` to process the asynchronous sub-task.
private void	processing()
public boolean	Returns: true if the reset was successful reset() Resets this callback.
public void	succeeded() Overrides default org.eclipse.jetty.util.Callback.succeeded. Method to invoke when the asynchronous sub-task succeeds.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

_failure	back to summary
private Throwable _failure

_iterate	back to summary
private boolean _iterate

_lock	back to summary
private final AutoLock _lock

_state	back to summary
private IteratingCallback.State _state

Constructor Detail

IteratingCallback	back to summary
protected IteratingCallback()

IteratingCallback	back to summary
protected IteratingCallback(boolean needReset)

Method Detail

abort back to summary

abort	back to summary
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:Throwable the cause of the abort See Also `isAborted()`

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:Throwable: the cause of the abort

See Also

isAborted()

close back to summary

close	back to summary
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 `isClosed()`

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: isClosed()

failed back to summary

failed	back to summary
public void failed(Throwable x) Overrides default org.eclipse.jetty.util.Callback.failed. Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration. Subclasses that override this method must always remember to call `super.failed(Throwable)`. Eventually, `onCompleteFailure(Throwable)` is called, either by the caller thread or by the processing thread. Parameters x:Throwable Doc from org.eclipse.jetty.util.Callback.failed. the reason for the operation failure Annotations @Override See Also `isFailed()`

public void failed(Throwable x)

Overrides default org.eclipse.jetty.util.Callback.failed.

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

Subclasses that override this method must always remember to call super.failed(Throwable).

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

Parameters

x:Throwable

Doc from org.eclipse.jetty.util.Callback.failed.

the reason for the operation failure

Annotations

@Override

See Also

isFailed()

isAborted	back to summary
public boolean isAborted() Returns:boolean whether this callback has been `aborted`

isClosed	back to summary
public boolean isClosed() Returns:boolean whether this callback has been `closed`

isFailed	back to summary
public boolean isFailed() Returns:boolean whether this callback has been `failed`

isIdle	back to summary
pack-priv boolean isIdle() Returns:boolean whether this callback is idle, and `iterate()` needs to be called

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

iterate back to summary

iterate	back to summary
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.

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.

onCompleteFailure back to summary

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

protected void onCompleteFailure(Throwable cause)

Invoked when the overall task has completed with a failure.

Parameters

cause:Throwable: the throwable to indicate cause of failure

See Also

onCompleteSuccess()

onCompleteSuccess back to summary

onCompleteSuccess	back to summary
protected void onCompleteSuccess() Invoked when the overall task has completed successfully. See Also `onCompleteFailure(Throwable)`

protected void onCompleteSuccess()

Invoked when the overall task has completed successfully.

See Also: onCompleteFailure(Throwable)

process back to summary

process	back to summary
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: `Action#IDLE` when no sub tasks are available for execution but the overall job is not completed yet `Action#SCHEDULED` when the sub task asynchronous execution has been started `Action#SUCCEEDED` when the overall job is completed Returns:IteratingCallback.Action the appropriate Action Exceptions Throwable: if the sub-task processing throws

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:

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

Returns:IteratingCallback.Action

the appropriate Action

Exceptions

Throwable:: if the sub-task processing throws

processing	back to summary
private void processing()

reset back to summary

reset	back to summary
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:boolean true if the reset was successful

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:boolean: true if the reset was successful

succeeded back to summary

succeeded	back to summary
public void succeeded() Overrides default org.eclipse.jetty.util.Callback.succeeded. Method to invoke when the asynchronous sub-task succeeds. Subclasses that override this method must always remember to call `super.succeeded()`. Annotations @Override

public void succeeded()

Overrides default org.eclipse.jetty.util.Callback.succeeded.

Method to invoke when the asynchronous sub-task succeeds.

Subclasses that override this method must always remember to call super.succeeded().

Annotations

@Override

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

org.eclipse.jetty.util back to summary

protected final Enum IteratingCallback.Action

Class Inheritance

extends Enum<IteratingCallback.Action>

java.lang.Object
java.lang.Enum
org.eclipse.jetty.util.IteratingCallback.Action

The indication of the overall progress of the iteration that implementations of process() must return.

Field Summary

Modifier and Type	Field and Description
public static final IteratingCallback.Action	IDLE Indicates that `process()` has no more work to do, but the iteration is not completed yet, probably waiting for additional events to trigger more work.
public static final IteratingCallback.Action	SCHEDULED Indicates that `process()` has initiated an asynchronous sub-task, where the execution has started but the callback that signals the completion of the asynchronous sub-task may have not yet been invoked.
public static final IteratingCallback.Action	SUCCEEDED Indicates that `process()` has completed the whole iteration successfully.

Constructor Summary

Access	Constructor and Description
private	Action()

Method Summary

Modifier and Type	Method and Description
public static IteratingCallback.Action	valueOf(String name)
public static IteratingCallback.Action[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

IDLE	back to summary
public static final IteratingCallback.Action IDLE Indicates that `process()` has no more work to do, but the iteration is not completed yet, probably waiting for additional events to trigger more work.

SCHEDULED	back to summary
public static final IteratingCallback.Action SCHEDULED Indicates that `process()` has initiated an asynchronous sub-task, where the execution has started but the callback that signals the completion of the asynchronous sub-task may have not yet been invoked.

SUCCEEDED	back to summary
public static final IteratingCallback.Action SUCCEEDED Indicates that `process()` has completed the whole iteration successfully.

Constructor Detail

Action	back to summary
private Action()

Method Detail

valueOf	back to summary
public static IteratingCallback.Action valueOf(String name)

values	back to summary
public static IteratingCallback.Action[] values()

org.eclipse.jetty.util back to summary

private final Enum IteratingCallback.State

Class Inheritance

extends Enum<IteratingCallback.State>

java.lang.Object
java.lang.Enum
org.eclipse.jetty.util.IteratingCallback.State

The internal states of this callback.

Field Summary

Modifier and Type	Field and Description
public static final IteratingCallback.State	ABORTED This callback has been `aborted`, and cannot be `reset`.
public static final IteratingCallback.State	CALLED The asynchronous sub-task was completed successfully via a call to `succeeded()` while in `PROCESSING` state.
public static final IteratingCallback.State	CLOSED This callback has been `closed` and cannot be `reset`.
public static final IteratingCallback.State	FAILED The iteration terminated with a failure via a call to `IteratingCallback#failed(Throwable)`.
public static final IteratingCallback.State	IDLE This callback is idle, ready to iterate.
public static final IteratingCallback.State	PENDING Method `process()` returned `Action#SCHEDULED` and this callback is waiting for the asynchronous sub-task to complete.
public static final IteratingCallback.State	PROCESSING This callback is just about to call `process()`, or within it, or just exited from it, either normally or by throwing.
public static final IteratingCallback.State	SUCCEEDED The iteration terminated successfully as indicated by `Action#SUCCEEDED` returned from `IteratingCallback#process()`.

Constructor Summary

Access	Constructor and Description
private	State()

Method Summary

Modifier and Type	Method and Description
public static IteratingCallback.State	valueOf(String name)
public static IteratingCallback.State[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

ABORTED	back to summary
public static final IteratingCallback.State ABORTED This callback has been `aborted`, and cannot be `reset`.

CALLED	back to summary
public static final IteratingCallback.State CALLED The asynchronous sub-task was completed successfully via a call to `succeeded()` while in `PROCESSING` state.

CLOSED	back to summary
public static final IteratingCallback.State CLOSED This callback has been `closed` and cannot be `reset`.

FAILED	back to summary
public static final IteratingCallback.State FAILED The iteration terminated with a failure via a call to `IteratingCallback#failed(Throwable)`.

IDLE	back to summary
public static final IteratingCallback.State IDLE This callback is idle, ready to iterate.

PENDING	back to summary
public static final IteratingCallback.State PENDING Method `process()` returned `Action#SCHEDULED` and this callback is waiting for the asynchronous sub-task to complete.

PROCESSING	back to summary
public static final IteratingCallback.State PROCESSING This callback is just about to call `process()`, or within it, or just exited from it, either normally or by throwing.

SUCCEEDED	back to summary
public static final IteratingCallback.State SUCCEEDED The iteration terminated successfully as indicated by `Action#SUCCEEDED` returned from `IteratingCallback#process()`.

Constructor Detail

State	back to summary
private State()

Method Detail

valueOf	back to summary
public static IteratingCallback.State valueOf(String name)

values	back to summary
public static IteratingCallback.State[] values()

public abstract Class IteratingCallback

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

protected final Enum IteratingCallback.Action

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Enum IteratingCallback.State

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail