Gets the set of allowed cluster environment identifiers.

Setting the allowed cluster environment identifiers can be used to limit the suitable environments for the inner task execution. The build system will only consider environments for suitability checking if their identifiers are contained in the returned set.

If the identifiers are null the build system will consider all environments for execution.

The build system will throw an exception if the identifiers set is non-null, but empty.

Using this parameter can be beneficial when callers want the inner task to be executed on the same machine as the caller task:

 params.setAllowedClusterEnvironmentIdentifiers(Collections.singleton(environment.getEnvironmentIdentifier()));
 

Other use-cases may include running different inner tasks after each other where the first tasks will collect the associated environment identifiers as well. These use-cases are generally require more sophisticated operations to work correctly, and is not recommended. The parameter is represented as a set to allow such behaviour, for future compatibility and extensibility.

Gets the cluster duplicate factor.

The cluster duplicate factor determines that how many clusters the inner task should be duplicated to. By default it is 0.

If the value is negative, the inner task will be duplicated to all suitable clusters.

If the value is 0 or 1, the inner task will be run on a single suitable environment.

If the value is greater than 1, the task will be duplicated to at most the specified number of environments. If there are less suitable environments than the duplicate factor, the task will run only the suitable environments without raising an error.

Generally users should set this to either -1 (to use all possible clusters), or 0 (to execute only in a single environment). However, if they already know how many units of execution the inner tasks will execute, they are recommended to set this value to the upper bound of the number of inner task invocations expected. In some cases this can improve the performance, as tasks won't be duplicated unnecessarily.

If an inner task uses non-zero duplication factor, it also needs to report the remote dispatchable capability.

Gets the duplication predicate of the associated inner task.

The duplication predicate is used to determine if the given inner task should be invoked once more.

If a duplication predicate is not set, the inner task will be duplicated to the clusters based on the cluster duplicate factor, and it will be invoked once for each duplication.

Gets the maximum build environment factor.

The maximum build environment factor specifies how many times a task should be duplicated on a given build environment. As inner tasks can be duplicated to run on a given environment with multiple concurrent instances, the maximum environment factor limits this parallelism.

Using the maximum environment factor can be useful if you have other concurrency limiting factors that are not feasible to be limited via computation tokens.

A good example for using this if your inner tasks use a shared separate JVM to perform its operations. In that case setting the maximum environment factor to 1 can be useful to limit too many concurrent inner tasks.

Generally, the value of this property is either set to 1 or be unlimited. Computation tokens are more useful for limiting concurrency for greater numbers.

If the maximum environment factor is 0 or negative, it is considered to be not limited.

Note that if this value is greater than 0, it is not guaranteed that a given task will be duplicated at least that many times.

Checks if the duplication of the inner task is cancellable.

By default, inner tasks are not duplication cancellable.

If the duplication of an inner task is set to be cancellable, the duplication will abort if it is requested manually or the enclosing task finishes.

When the duplication is cancelled, no more inner tasks will be invoked, even if the duplication predicate returns true.

Sets the allowed cluster environments which can be used for the inner task execution.

Sets the cluster duplicate factor.

Sets if the duplication of the inner task is cancellable.

Sets the duplication predicate for the inner task.

If the inner task is used with remote dispatching, the duplication predicate will not be transferred anywhere. It will be invoked on the caller machine, and there will only exist a single instance of the argument duplication predicate.

The RMI transfer properties for the runtime type of the argument is ignored.

Sets the duplcation predicate for the inner task in a way that the predicate is transferred to each invocation cluster.

If remote dispatching is involved with the starting of the inner task, the argument object will be serialized to each cluster that is a suitable environment and candidate for invoking the inner task.

The argument predicate must be Serializable.

Sets the duplicate predicate for the inner task in a way that the predicate is transferred to the coordinator machine.

If remote dispatching is involved with the starting of the inner task, the argument object will be serialized to the coordinator machine for the build execution. The coordinator machine is the computer that executes the build itself.

If the inner task is being started from an already remote dispatched enclosing task, and the inner task is to be remote dispatched to multiple clusters, it can be beneficial to use this function that transfers the predicate to the coordinator machine. Having the predicate on the coordinator can reduce the network hops required to call the predicate method.

The argument predicate must be Serializable.

Sets the maximum environment factor.