Class IteratingCallback
- java.lang.Object
-
- org.eclipse.jetty.util.IteratingCallback
-
- Direct Known Subclasses:
AsyncMiddleManServlet.ProxyReader
,AsyncProxyServlet.StreamReader
,FrameFlusher
,HTTP2Flusher
,IteratingNestedCallback
public abstract class IteratingCallback extends java.lang.Object implements Callback
This specialized callback implements a pattern that allows a large job to be broken into smaller 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 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 uses an AtomicReference to record whether success callback has been called during the processing of a sub task, and if so then the processing iterates rather than recurring.
Subclasses must implement method
process()
where the sub task is executed and a suitableIteratingCallback.Action
is returned to this callback to indicate the overall progress of the job. This callback is passed to the asynchronous execution of each sub task and a call thesucceeded()
on this callback represents the completion of the sub task.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
IteratingCallback.Action
The indication of the overall progress of the overall job that implementations ofprocess()
must return.-
Nested classes/interfaces inherited from interface org.eclipse.jetty.util.Callback
Callback.Completable, Callback.Completing, Callback.Nested
-
Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.Invocable
Invocable.InvocationType
-
-
Field Summary
-
Fields inherited from interface org.eclipse.jetty.util.thread.Invocable
__nonBlocking
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
IteratingCallback()
protected
IteratingCallback(boolean needReset)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
close()
void
failed(java.lang.Throwable x)
Invoked when the sub task fails.boolean
isClosed()
boolean
isFailed()
boolean
isSucceeded()
void
iterate()
This method must be invoked by applications to start the processing of sub tasks.protected void
onCompleteFailure(java.lang.Throwable 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
process()
Method called byiterate()
to process the sub task.boolean
reset()
Resets this callback.void
succeeded()
Invoked when the sub task succeeds.java.lang.String
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.thread.Invocable
getInvocationType
-
-
-
-
Method Detail
-
process
protected abstract IteratingCallback.Action process() throws java.lang.Throwable
Method called byiterate()
to process the sub task.Implementations must start 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:
java.lang.Throwable
- if the sub task processing throws
-
onCompleteSuccess
protected void onCompleteSuccess()
Invoked when the overall task has completed successfully.- See Also:
onCompleteFailure(Throwable)
-
onCompleteFailure
protected void onCompleteFailure(java.lang.Throwable cause)
Invoked when the overall task has completed with a failure.- Parameters:
cause
- the throwable to indicate cause of failure- See Also:
onCompleteSuccess()
-
iterate
public void iterate()
This method must be invoked by applications to start the processing of sub tasks. It can be called at any time by any thread, and it's contract is that when called, then theprocess()
method will be called during or soon after, either by the calling thread or by another thread.
-
succeeded
public void succeeded()
Invoked when the sub task succeeds. Subclasses that override this method must always remember to callsuper.succeeded()
.- Specified by:
succeeded
in interfaceCallback
- See Also:
Callback.failed(Throwable)
-
failed
public void failed(java.lang.Throwable x)
Invoked when the sub task fails. Subclasses that override this method must always remember to callsuper.failed(Throwable)
.
-
close
public void close()
-
isClosed
public boolean isClosed()
-
isFailed
public boolean isFailed()
- Returns:
- whether this callback has failed
-
isSucceeded
public boolean isSucceeded()
- Returns:
- whether this callback has succeeded
-
reset
public boolean reset()
Resets this callback.A callback can only be reset to IDLE from the SUCCEEDED or FAILED states or if it is already IDLE.
- Returns:
- true if the reset was successful
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-