saker.build Documentation TaskDoc JavaDoc Packages
public interface TaskFuture<R>
Represents a handle to a specified task.

This interface can be used by tasks to get the result of an input task.

By querying the result an input dependency will be recorded on the subject task. (See get())

Instances of this interface can be reused and should be considered as a singleton for a given task identifier.

Methods of this class may throw (but not required in all ceses) IllegalTaskOperationException if it detects that they are being called after the corresponding task execution has finished. References to task futures should not be retained after the task execution is over.

Clients should not implement this interface.

RThe return type of the task.
Methods
public TaskDependencyFuture<R>
Gets a dependency future handle to the subject task.
public R
get()
Retrieves the result of the associated task execution.
public R
Retrieves the result of the associated task, given that it is already finished.
public Object
Gets the modification stamp of the subject task.
public TaskContext
Gets the task context which was used to retrieve this future.
public TaskIdentifier
Gets the task identifier of the subject class.
Gets a dependency future handle to the subject task.

The handle can be used to fine-grain the dependency reported for the subject task.

The returned handle is specific for the caller, it can be used to report and configure a single dependency towards the subject task.

This method can be called multiple times, different instances will be returned, but the results should not be exchanged by different parts of client code.

The dependency future handle.
Retrieves the result of the associated task execution.

This call will wait for if necessary and report an input dependency on the subject task. The output change detector on the task will be CommonTaskOutputChangeDetector.ALWAYS.

Callers should handle the possiblity of tasks returning StructuredTaskResult instances.

If this method throws a TaskExecutionFailedException, it is considered to be a valid return scenario. A dependency on the the associated task will be installed as if a return value was returned.

This call has the same effect as:

 TaskDependencyFuture<R> res = getAsDependencyFuture();
 res.setTaskOutputChangeDetector(CommonTaskOutputChangeDetector.ALWAYS);
 return res.get();
 
The result of the subject task.
TaskResultWaitingFailedExceptionIf the waiting failed. See exception subclasses for possible scenarios.
TaskExecutionFailedExceptionIf the subject task execution failed, this exception is thrown
IllegalTaskOperationExceptionIf the current task is not allowed to wait for the subject task. See exception message for more information.
Retrieves the result of the associated task, given that it is already finished.

This method will not wait for the task to finish, and will throw an exception if it is not yet finished. An input dependency on the task will be reported with the output change detector of CommonTaskOutputChangeDetector.ALWAYS.

Important: To ensure incremental reproducibility, this method will validate if the caller is allowed to retrieve the finished result of the associated task. This is done by checking if the associated task have been waited for prior to this call, or by one of the ancestors of the caller task before starting the caller task.

Example 1: Task A wants to retrieve the finished result of task B. If task A calls getFinished(), it will throw an exception, as it cannot be ensured that A is retrieving the result for a task that has been already finished.
Example 2: Task A wants to retrieve the finished result of task B. If task A calls get() first, and later getFinished(), then the second call will succeed, as task A already waited for the result of task B, therefore the finished result can be also retrieved.
Example 3: Task S waits for task B, and starts task A (in this order). Task A wants to retrieve the finished result of task B. In this case task A can call getFinished() for task B, as it can be sure that task B is finished, because its parent has already waited for task B before starting task A.

In general, when retrieving the finished result of a task, make sure that the task (Example 2) or any of its ancestors (Example 3) have waited for the task itself. If this requirement is violated, an exception will be thrown.

The build system detects this requirement when handling incremental builds. Meaning, that if retrieving a finished result for a task is no longer possible, the caller will be rerun.

Callers should handle the possiblity of tasks returning StructuredTaskResult instances.

Tasks which request computation tokens are allowed to call this method in order to add a dependency on the associated task.

This call has the same effect as:

 TaskDependencyFuture<R> res = getAsDependencyFuture();
 res.setTaskOutputChangeDetector(CommonTaskOutputChangeDetector.ALWAYS);
 return res.getFinished();
 
The result of the subject task.
TaskExecutionFailedExceptionIf the subject task execution failed, this exception is thrown
IllegalTaskOperationExceptionIf the current task is not allowed to retrieve the result for the subject task, or the subject task hasn't finished yet.
Gets the modification stamp of the subject task.

Modification stamps are unique key objects which specify the time when the subject task was last run. Stamps should be compared by equality to check if the task has been rerun. If two stamps for a given task does not equal to each other, then the caller can be sure that the associated task was rerun at least once between the previous and current execution of the caller task.

This method can only be called if the task has already finished. This call doesn't add an input dependency on the subject task. It is recommended to call get() before calling this function, or ensure that the task has finished in some other way.

When calling this method, the same rules apply as in getFinished().

The current modification stamp for the subject task.
IllegalTaskOperationExceptionIf the current task is not allowed to retrieve the result for the subject task, or the subject task hasn't finished yet.
Gets the task context which was used to retrieve this future.
The task context.
Gets the task identifier of the subject class.
The task identifier.