Class IteratingCallback
- 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
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 ClassesModifier and TypeClassDescriptionprotected static enum
The indication of the overall progress of the iteration that implementations ofprocess()
must return.Nested classes/interfaces inherited from interface org.eclipse.jetty.util.Callback
Callback.Combination, Callback.Completable, Callback.Completing, Callback.Nested
Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.Invocable
Invocable.Callable, Invocable.InvocationType, Invocable.ReadyTask, Invocable.Task
-
Field Summary
Fields inherited from interface org.eclipse.jetty.util.Callback
NOOP, NOT_CALLED
Fields inherited from interface org.eclipse.jetty.util.thread.Invocable
__nonBlocking
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal boolean
Method to invoke to stop further processing iterations.final void
close()
final void
Method to invoke when the asynchronous sub-task fails, or to fail the overall asynchronous task and therefore terminate the iteration.boolean
boolean
isClosed()
boolean
isFailed()
boolean
void
iterate()
This method must be invoked by applications to start the processing of asynchronous sub-tasks.protected void
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
Invoked when the overall task has completed successfully, specifically after anyIteratingCallback.Action.SCHEDULED
operations haveCallback.succeeded()
andprocess()
has returnedIteratingCallback.Action.SUCCEEDED
.protected void
protected void
Invoked when one task has completed successfully, either by the caller thread or by the processing thread.protected abstract IteratingCallback.Action
process()
Method called byiterate()
to process the asynchronous sub-task.boolean
reset()
Resets this callback.final void
Method to invoke when the asynchronous sub-task succeeds.toString()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.eclipse.jetty.util.Callback
completeWith
Methods inherited from interface org.eclipse.jetty.util.thread.Invocable
getInvocationType
-
Constructor Details
-
IteratingCallback
protected IteratingCallback() -
IteratingCallback
protected IteratingCallback(boolean needReset)
-
-
Method Details
-
process
Method called byiterate()
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 yetIteratingCallback.Action.SCHEDULED
when the sub task asynchronous execution has been startedIteratingCallback.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 ofprocess()
.This method is not invoked when a call to
abort(Throwable)
is made before thesucceeded()
callback happens. -
onFailure
Invoked when the overall task has beenaborted
orfailed
.Calls to this method are serialized with respect to
onAborted(Throwable)
,process()
,onCompleteFailure(Throwable)
andonCompleted(Throwable)
.Because
onFailure
can be called due to anabort(Throwable)
orclose()
operation, it is possible that any resources passed to aIteratingCallback.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 ofonFailure
. Such resources may be discarded here, or safely recycled in a subsequent call toonCompleted(Throwable)
oronCompleteFailure(Throwable)
, when theIteratingCallback.Action.SCHEDULED
operation has completed.- Parameters:
cause
- The cause of the failure or abort- See Also:
-
onCompleteSuccess
protected void onCompleteSuccess()Invoked when the overall task has completed successfully, specifically after anyIteratingCallback.Action.SCHEDULED
operations haveCallback.succeeded()
andprocess()
has returnedIteratingCallback.Action.SUCCEEDED
.Calls to this method are serialized with respect to
process()
,onAborted(Throwable)
andonCompleted(Throwable)
. If this method is called, thenonCompleteFailure(Throwable)
()} will never be called.- See Also:
-
onCompleteFailure
Invoked when the overall task has completed with a failure.Calls to this method are serialized with respect to
process()
,onAborted(Throwable)
andonCompleted(Throwable)
. If this method is called, thenonCompleteSuccess()
will never be called.- Parameters:
cause
- the throwable to indicate cause of failure- See Also:
-
onAborted
Invoked when the overall task has been aborted.Calls to this method are serialized with respect to
process()
,onCompleteFailure(Throwable)
andonCompleted(Throwable)
. If this method is called, thenonCompleteSuccess()
will never be called.The default implementation of this method calls
failed(Throwable)
. Overridden implementations of this method SHOULD NOT callsuper.onAborted(Throwable)
.Because
onAborted
can be called due to anabort(Throwable)
orclose()
operation, it is possible that any resources passed to aIteratingCallback.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 ofonFailure
. Such resources may be discarded here, or safely recycled in a subsequent call toonCompleted(Throwable)
oronCompleteFailure(Throwable)
, when theIteratingCallback.Action.SCHEDULED
operation has completed.- Parameters:
cause
- The cause of the abort- See Also:
-
onCompleted
Invoked when the overall task has completed.Calls to this method are serialized with respect to
process()
andonAborted(Throwable)
. The default implementation of this method will call eitheronCompleteSuccess()
oronCompleteFailure(Throwable)
thus implementations of this method should always callsuper.onCompleted(Throwable)
. -
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 callsuper.succeeded()
. Such overridden methods are not serialized with respect toprocess()
,onCompleteSuccess()
,onCompleteFailure(Throwable)
, noronAborted(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. -
failed
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 callsuper.succeeded()
. Such overridden methods are not serialized with respect toprocess()
,onCompleteSuccess()
,onCompleteFailure(Throwable)
, noronAborted(Throwable)
. They should not act on nor change any fields that may be used by those methods. -
close
public final void close()Method to invoke to forbid further invocations toiterate()
andreset()
.When this method is invoked during processing, it behaves like invoking
failed(Throwable)
.- See Also:
-
abort
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 toprocess()
has returned.- Parameters:
cause
- the cause of the abort- Returns:
true
if abort was called before the callback was complete.- 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
-
toString
-