saker.build Documentation TaskDoc JavaDoc Packages
public interface StructuredTaskResult
Represents a special kind of task result which should be handled as a structured output with fields that haven't completed yet.

Structured tasks results can serve as a placeholder result for a task and make their data partially available.

Sometimes tasks divide their work into multiple sub-tasks. In this case the result of a task can include values from the sub-tasks. This would require from the parent task to wait all of its child worker tasks and then construct an appropriate object that contains these results. This behaviour can hinder dependent tasks in their execution as this can result in waiting for tasks which are unrelated to the work of the dependent task.

Take the following example:

Task A is a complex task that divides its work into separate partitions. Task A will return a complex object as a result, with fields of X and Y, each corresponding to the result of its worker tasks.
Task B has an input dependency on task A, and will use the field X of its result. This means that task B will be stalled until task A finishes completely.

This is an undesirable scenario, as task B only needs the result of the sub-task X, while the long running of sub-task Y can stall the execution of task B.

In order to avoid this, structured task results were introduced which are able to separate the concerns of unrelated results contained by their parent.

With structured results, task B in the example above will not be stalled, as task A can return before the completion of its sub-tasks. Task A returns a structured task results with the fields X and Y, which have the values of the sub-task task identifiers. Task B will receive the structured result from task A, and see the task identifier for sub-task X. It will then wait for sub-task X, and proceed with its execution. We can see that in this case it was not necessary for task B to wait for the completion of sub-task Y to get the result from sub-task X.

Tasks can choose to retrieve the actual objectified, non-structured result by calling toResult(TaskResultResolver).

If a task doesn't want to handle structured task results (but it is still encouraged to to so), it can choose to call getActualTaskResult(TaskIdentifier, TaskResultResolver) which converts any possible structured results to object representation.

The TaskContext instance for the tasks can be used for the TaskResultResolver parameter of the methods in this interface.

Implementations are not required to implement Object.hashCode() and Object.equals(Object), but if they do, they must ensure that if two results equal, then they semantically provide access to the same results. The actual end results are not required to equal, but the semantics along which they are accessed must. E.g. Two StructuredObjectTaskResult can equal if their enclosed task identifier equal, however, it is not required that the task outputs of the associated task identifiers are equal.

Note: When constructing strucuted task results, make sure to not have circular references in them.

Methods
public static StructuredTaskResult
Creates a structured task result object that returns the argument literal object.
public static Object
getActualTaskResult(TaskDependencyFuture<?> taskdependencyfuture)
Gets the actual object result for the given task dependency future.
public static Object
Gets the actual object result for the given task future.
public static Object
Gets the actual object result for the given task identifier.
public static TaskResultDependencyHandle
Gets the dependency handle to the actual object of task results associated with the given task identifier.
public Object
Converts the structured result to plain object.
public default TaskResultDependencyHandle
Gets the task result dependency handle to the plain result object.
Creates a structured task result object that returns the argument literal object.

The argument must not be a structured task result in nature. That is, it should be suitable to be directly returned from the toResult(TaskResultResolver) function.

The returned structured task result implements Object.hashCode() and Object.equals(Object) that is based on the enclosed value.

literalThe value to enclose in a structured task result.
The structured task result with the argument value.
saker.build 0.8.10
public static Object getActualTaskResult(TaskDependencyFuture<?> taskdependencyfuture) throws NullPointerException
Gets the actual object result for the given task dependency future.

If the result of the specified task is an instance of StructuredTaskResult, it will be objectified by calling toResult(TaskResultResolver) with the TaskDependencyFuture.getTaskContext() as a result resolver.

taskdependencyfutureThe task dependency future.
The objectified task result.
NullPointerExceptionIf the task dependency future is null.
public static Object getActualTaskResult(TaskFuture<?> taskfuture) throws NullPointerException
Gets the actual object result for the given task future.

If the result of the specified task is an instance of StructuredTaskResult, it will be objectified by calling toResult(TaskResultResolver) with the TaskFuture.getTaskContext() as a result resolver.

taskfutureThe future handle for the task.
The objectified task result.
NullPointerExceptionIf the future is null.
Gets the actual object result for the given task identifier.

The result of the specified task will be retrieved by calling TaskResultResolver.getTaskResult(TaskIdentifier), and if the task result is an instance of StructuredTaskResult, it will be objectified by calling toResult(TaskResultResolver).

taskidThe task identifier to get the task result of.
resultsThe task result resolver to retrieve the results from.
The objectified task result for the specified identifier.
NullPointerExceptionIf any of the arguments are null.
Gets the dependency handle to the actual object of task results associated with the given task identifier.

The method will get the dependency handle to the result object that would be retrieved using getActualTaskResult(TaskIdentifier, TaskResultResolver). If the result of the associated task is an instance of StructuredTaskResult, then the toResultDependencyHandle(TaskResultResolver) method is used to retrieve the result.

The method installs a dependency for the task result of the associated task that signals a change if the StructuredTaskResult nature of the result changes.

taskidThe task identifier to get the task result of.
resultsThe task result resolver to retrieve the results from.
The dependency handle to the actual result of the given task.
NullPointerExceptionIf any of the arguments are null.
Converts the structured result to plain object.

Calling this method will ensure that the return value will not have any structured task result related fields in it.

resultsThe results to resolve the task identifiers against.
The objectified structured result represented by this instance.
NullPointerExceptionIf the argument is null.
RuntimeExceptionIn cases when the result cannot be computed properly. (E.g. task execution failure)
Gets the task result dependency handle to the plain result object.

The TaskResultDependencyHandle.get() method must return the semantically same object as toResult(TaskResultResolver).

The TaskResultDependencyHandle.setTaskOutputChangeDetector(TaskOutputChangeDetector) method may or may not report dependencies to the backing task. It may be very well that there's no backing task.

resultsThe results to resolve the task identifiers against.
The result dependency handle to the result plain object.
NullPointerExceptionIf the argument is null.