com.parabon.client
Interface SerializableTaskContext

All Superinterfaces:
TaskContext
All Known Implementing Classes:
SerializableTaskContextProxy, SerializableTaskContextProxy.Placeholder, SerializableTaskWrapper

public interface SerializableTaskContext
extends TaskContext


Method Summary
 void logCheckpoint()
          Log a checkpoint which may be used to restart this task at a later time.
 void logCheckpoint(boolean force)
          Log a checkpoint which may be used to restart this task at a later time.
 void logCheckpoint(DataBuffer checkpoint)
          This form of logCheckpoint should not be used for SerializableTasks.
 void logCheckpoint(DataBuffer checkpoint, boolean force)
          This form of logCheckpoint should not be used for SerializableTasks.
 
Methods inherited from interface com.parabon.runtime.TaskContext
createDataBuffer, createDataBuffer, getElement, getTempDirectory, postIntermediateResultsData, postIntermediateResultsData, postIntermediateResultsObject, postIntermediateResultsObject, reportProgress, shouldLogCheckpoint, shouldPostIntermediateResults, shouldStop
 

Method Detail

logCheckpoint

void logCheckpoint()
Log a checkpoint which may be used to restart this task at a later time. The checkpoint is formed by serializing the associated SerializableTask instance via the Serializable and ObjectOutput interfaces. Serialization will take place before logCheckpoint returns (if at all). Restarting a task from a checkpoint occurs by deserializing the resulting checkpoint and invoking its run method. Hence, logCheckpoint should only be invoked while the task is in a state such that serializaing it is guaranteed to provide a valid checkpoint; the task must remain in this state at least until logCheckpoint returns -- that is, other threads should not change the state of the task while this method is executing.

The checkpoint may or may not be reported back to the server or the client, and may or may not be saved locally on the provider. Reporting checkpoints ensures that interrupted tasks can be restarted from the last reported checkpoint rather than the initial state; in extreme cases, tasks which do not report checkpoints (or report them too infrequently) may never complete because of interruptions.

This method will tend to return immediately without logging a checkpoint if shouldLogCheckpoint returns false.

Equivalent to logCheckpoint(false).

See Also:
TaskContext.shouldLogCheckpoint(), logCheckpoint(boolean)

logCheckpoint

void logCheckpoint(boolean force)
Log a checkpoint which may be used to restart this task at a later time. The checkpoint is formed by serializing the associated SerializableTask instance via the Serializable and ObjectOutput interfaces. Serialization will take place before logCheckpoint returns (if at all). Restarting a task from a checkpoint occurs by deserializing the resulting checkpoint and invoking its run method. Hence, logCheckpoint should only be invoked while the task is in a state such that serializaing it is guaranteed to provide a valid checkpoint; the task must remain in this state at least until logCheckpoint returns -- that is, other threads should not change the state of the task while this method is executing.

The checkpoint may or may not be reported back to the server or the client, and may or may not be saved locally on the provider. Reporting checkpoints ensures that interrupted tasks can be restarted from the last reported checkpoint rather than the initial state; in extreme cases, tasks which do not report checkpoints (or report them too infrequently) may never complete because of interruptions.

If force is true, this routine will tend to log a checkpoint even if shouldLogCheckpoint is false. This functionality is useful when, for instance, the task is only able to generate checkpoints at certain infrequent points, and another checkpoint may not be available for a while; in this case, the task's knowledge is more important than the system's checkpoint-logging efficiency heuristics. Note, however, that the system may decide not to save or transmit a checkpoint even when force is true. When force is false, this method is equivalent to logCheckpoint().

Parameters:
force - true if the method should attempt to save a checkpoint even though shouldLogCheckpoint returns false. This flag is only a hint, however, and the system may override it.
See Also:
TaskContext.shouldLogCheckpoint(), logCheckpoint()

logCheckpoint

void logCheckpoint(DataBuffer checkpoint)
This form of logCheckpoint should not be used for SerializableTasks. Use logCheckpoint() instead.

Specified by:
logCheckpoint in interface TaskContext
Parameters:
checkpoint - a buffer containing all state necessary to define task. This task retains ownership of the DataBuffer and can freely modify it after this method returns without affecting the substance of the checkpoint.
See Also:
TaskContext.shouldLogCheckpoint(), TaskContext.logCheckpoint(DataBuffer, boolean)

logCheckpoint

void logCheckpoint(DataBuffer checkpoint,
                   boolean force)
This form of logCheckpoint should not be used for SerializableTasks. Use logCheckpoint(boolean) instead.

Specified by:
logCheckpoint in interface TaskContext
Parameters:
checkpoint - a buffer containing all state necessary to define task. This task retains ownership of the DataBuffer and can freely modify it after this method returns without affecting the substance of the checkpoint.
force - true if the method should attempt to save a checkpoint even though shouldLogCheckpoint returns false. This flag is only a hint, however, and the system may override it.
See Also:
TaskContext.shouldLogCheckpoint(), TaskContext.logCheckpoint(DataBuffer)