IteratingCallback

This specialized callback implements a pattern that allows a large job to be broken into smaller tasks using iteration rather than recursion. <p> 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. </p> <p> 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. </p> <p> 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. </p> <p> Subclasses must implement method {@link #process()} where the sub task is executed and a suitable {@link IteratingCallback.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 the {@link #succeeded()} on this callback represents the completion of the sub task. </p>

Constructors

this
this()
Undocumented in source.
this
this(bool needReset)
Undocumented in source.

Members

Enums

Action
enum Action

The indication of the overall progress of the overall job that implementations of {@link #process()} must return.

Functions

close
void close()
Undocumented in source. Be warned that the author may not have intended to support it.
failed
void failed(Exception x)

Invoked when the sub task fails. Subclasses that override this method must always remember to call {@code super.failed(Exception)}.

isClosed
bool isClosed()
Undocumented in source. Be warned that the author may not have intended to support it.
isFailed
bool isFailed()

@return whether this callback has failed

isIdle
bool isIdle()
Undocumented in source. Be warned that the author may not have intended to support it.
isNonBlocking
bool isNonBlocking()
Undocumented in source. Be warned that the author may not have intended to support it.
isSucceeded
bool isSucceeded()

@return whether this callback has succeeded

iterate
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 the {@link #process()} method will be called during or soon after, either by the calling thread or by another thread.

onCompleteFailure
void onCompleteFailure(Exception cause)

Invoked when the overall task has completed with a failure.

onCompleteSuccess
void onCompleteSuccess()

Invoked when the overall task has completed successfully.

process
Action process()

Method called by {@link #iterate()} to process the sub task. <p> Implementations must start the asynchronous execution of the sub task (if any) and return an appropriate action: </p> <ul> <li>{@link Action#IDLE} when no sub tasks are available for execution but the overall job is not completed yet</li> <li>{@link Action#SCHEDULED} when the sub task asynchronous execution has been started</li> <li>{@link Action#SUCCEEDED} when the overall job is completed</li> </ul>

reset
bool reset()

Resets this callback. <p> A callback can only be reset to IDLE from the SUCCEEDED or FAILED states or if it is already IDLE. </p>

succeeded
void succeeded()

Invoked when the sub task succeeds. Subclasses that override this method must always remember to call {@code super.succeeded()}.

toString
string toString()
Undocumented in source. Be warned that the author may not have intended to support it.

Inherited Members

From Callback

NOOP
Callback NOOP;

Instance of Adapter that can be used when the callback methods need an empty implementation without incurring in the cost of allocating a new Adapter object.

succeeded
void succeeded()

<p> Callback invoked when the operation completes. </p>

failed
void failed(Exception x)

<p> Callback invoked when the operation fails. </p>

isNonBlocking
bool isNonBlocking()

@return True if the callback is known to never block the caller

Meta