GridCompute (gridgain-core 6.1.9 API)

All Known Implementing Classes:

GridComputeImpl
```
public interface GridCompute
```
Defines compute grid functionality for executing tasks and closures over nodes in the GridProjection. Instance of GridCompute is obtained from grid projection as follows:
```
 GridCompute c = GridGain.grid().compute();
 
```
The methods are grouped as follows:
- apply(...) methods execute GridClosure jobs over nodes in the projection.
- call(...) methods execute Callable jobs over nodes in the projection. Use GridCallable for better performance as it implements Serializable.
- run(...) methods execute Runnable jobs over nodes in the projection. Use GridRunnable for better performance as it implements Serializable.
- broadcast(...) methods broadcast jobs to all nodes in the projection.
- affinity(...) methods colocate jobs with nodes on which a specified key is cached.
Note that if attempt is made to execute a computation over an empty projection (i.e. projection that does not have any alive nodes), then GridEmptyProjectionException will be thrown out of result future.
Serializable
Also note that Runnable and Callable implementations must support serialization as required by the configured marshaller. For example, GridOptimizedMarshaller requires Serializable objects by default, but can be configured not to. Generally speaking objects that implement Serializable or Externalizable will perform better. For Runnable and Callable interfaces GridGain provides analogous GridRunnable and GridCallable classes which are Serializable and should be used to run computations on the grid.
Load Balancing
In all cases other than broadcast(...), GridGain must select a node for a computation to be executed. The node will be selected based on the underlying GridLoadBalancingSpi, which by default sequentially picks next available node from grid projection. Other load balancing policies, such as random or adaptive, can be configured as well by selecting a different load balancing SPI in grid configuration. If your logic requires some custom load balancing behavior, consider implementing GridComputeTask directly.
Fault Tolerance
GridGain guarantees that as long as there is at least one grid node standing, every job will be executed. Jobs will automatically failover to another node if a remote node crashed or has rejected execution due to lack of resources. By default, in case of failover, next load balanced node will be picked for job execution. Also jobs will never be re-routed to the nodes they have failed on. This behavior can be changed by configuring any of the existing or a custom GridFailoverSpi in grid configuration.
Resource Injection
All compute jobs, including closures, runnables, callables, and tasks can be injected with grid resources. Both, field and method based injections are supported. The following grid resources can be injected:
Refer to corresponding resource documentation for more information. Here is an example of how to inject instance of Grid into a computation:
```
 public class MyGridJob extends GridRunnable {
      ...
      @GridInstanceResource
      private Grid grid;
      ...
  }
 
```
Computation SPIs
Note that regardless of which method is used for executing computations, all relevant SPI implementations configured for this grid instance will be used (i.e. failover, load balancing, collision resolution, checkpoints, etc.). If you need to override configured defaults, you should use compute task together with GridComputeTaskSpis annotation. Refer to GridComputeTask documentation for more information.

Method Summary

Methods
Modifier and Type	Method and Description
`<R> GridFuture<R>`	`affinityCall(String cacheName, Object affKey, Callable<R> job)` Executes given job on the node where data for provided affinity key is located (a.k.a.
`GridFuture<?>`	`affinityRun(String cacheName, Object affKey, Runnable job)` Executes given job on the node where data for provided affinity key is located (a.k.a.
`<T,R> GridFuture<Collection<R>>`	`apply(GridClosure<T,R> job, Collection<? extends T> args)` Executes provided closure job on nodes within this grid projection.
`<R,T> GridFuture<R>`	`apply(GridClosure<T,R> job, T arg)` Executes provided closure job on a node in this grid projection.
`<R1,R2,T> GridFuture<R2>`	`apply(GridClosure<T,R1> job, Collection<? extends T> args, GridReducer<R1,R2> rdc)` Executes provided closure job on nodes within this grid projection.
`<R> GridFuture<Collection<R>>`	`broadcast(Callable<R> job)` Broadcasts given job to all nodes in grid projection.
`<R,T> GridFuture<Collection<R>>`	`broadcast(GridClosure<T,R> job, T arg)` Broadcasts given closure job with passed in argument to all nodes in grid projection.
`GridFuture<?>`	`broadcast(Runnable job)` Broadcasts given job to all nodes in grid projection.
`<R> GridFuture<R>`	`call(Callable<R> job)` Executes provided job on a node in this grid projection.
`<R> GridFuture<Collection<R>>`	`call(Collection<? extends Callable<R>> jobs)` Executes collection of jobs on nodes within this grid projection.
`<R1,R2> GridFuture<R2>`	`call(Collection<? extends Callable<R1>> jobs, GridReducer<R1,R2> rdc)` Executes collection of jobs on nodes within this grid projection.
`void`	`cancelJob(GridUuid jobId)` Cancels job with the given job ID, if it is currently running inside this projection.
`void`	`cancelTask(GridUuid sesId)` Cancels task with the given execution session ID, if it currently running inside this projection.
`<T,R> GridComputeTaskFuture<R>`	`execute(Class<? extends GridComputeTask<T,R>> taskCls, T arg)` Executes given task on the grid projection.
`<T,R> GridComputeTaskFuture<R>`	`execute(GridComputeTask<T,R> task, T arg)` Executes given task on this grid projection.
`<T,R> GridComputeTaskFuture<R>`	`execute(String taskName, T arg)` Executes given task on this grid projection.
`ExecutorService`	`executorService()` Creates new `ExecutorService` which will execute all submitted `Callable` and `Runnable` jobs on nodes in this grid projection.
`void`	`localDeployTask(Class<? extends GridComputeTask> taskCls, ClassLoader clsLdr)` Explicitly deploys a task with given class loader on the local node.
`Map<String,Class<? extends GridComputeTask<?,?>>>`	`localTasks()` Gets map of all locally deployed tasks keyed by their task name .
`GridProjection`	`projection()` Gets grid projection to which this `GridCompute` instance belongs.
`GridFuture<?>`	`run(Collection<? extends Runnable> jobs)` Executes collection of jobs on grid nodes within this grid projection.
`GridFuture<?>`	`run(Runnable job)` Executes provided job on a node in this grid projection.
`<R> GridComputeTaskFuture<R>`	`taskFuture(GridUuid sesId)` Gets task future based on execution session ID.
`void`	`undeployTask(String taskName)` Makes the best attempt to undeploy a task with given name from this grid projection.
`GridCompute`	`withName(String taskName)` Sets task name for the next executed task on this projection in the current thread.
`GridCompute`	`withNoFailover()` Sets no-failover flag for the next executed task on this projection in the current thread.
`GridCompute`	`withTimeout(long timeout)` Sets task timeout for the next executed task on this projection in the current thread.

- Method Detail
  - projection
```
GridProjection projection()
```
    Gets grid projection to which this GridCompute instance belongs.
    
    Returns:
    Grid projection to which this GridCompute instance belongs.
  - affinityRun
```
GridFuture<?> affinityRun(@Nullable
                        String cacheName,
                        Object affKey,
                        Runnable job)
```
    Executes given job on the node where data for provided affinity key is located (a.k.a. affinity co-location).
    
    Parameters:
    cacheName - Name of the cache to use for affinity co-location.
    affKey - Affinity key.
    job - Job which will be co-located on the node with given affinity key.
    
    Returns:
    Future for this execution.
    See Also:
    GridComputeJobContext.cacheName(), GridComputeJobContext.affinityKey()
  - affinityCall
```
<R> GridFuture<R> affinityCall(@Nullable
                             String cacheName,
                             Object affKey,
                             Callable<R> job)
```
    Executes given job on the node where data for provided affinity key is located (a.k.a. affinity co-location).
    
    Parameters:
    cacheName - Name of the cache to use for affinity co-location.
    affKey - Affinity key.
    job - Job which will be co-located on the node with given affinity key.
    
    Returns:
    Future with job result.
    See Also:
    GridComputeJobContext.cacheName(), GridComputeJobContext.affinityKey()
  - execute
```
<T,R> GridComputeTaskFuture<R> execute(Class<? extends GridComputeTask<T,R>> taskCls,
                                     @Nullable
                                     T arg)
```
    Executes given task on the grid projection. For step-by-step explanation of task execution process refer to GridComputeTask documentation.
    
    Parameters:
    taskCls - Class of the task to execute. If class has GridComputeTaskName annotation, then task is deployed under a name specified within annotation. Otherwise, full class name is used as task name.
    arg - Optional argument of task execution, can be null.
    
    Returns:
    Task future.
  - execute
```
<T,R> GridComputeTaskFuture<R> execute(GridComputeTask<T,R> task,
                                     @Nullable
                                     T arg)
```
    Executes given task on this grid projection. For step-by-step explanation of task execution process refer to GridComputeTask documentation.
    
    Parameters:
    task - Instance of task to execute. If task class has GridComputeTaskName annotation, then task is deployed under a name specified within annotation. Otherwise, full class name is used as task name.
    arg - Optional argument of task execution, can be null.
    
    Returns:
    Task future.
  - execute
```
<T,R> GridComputeTaskFuture<R> execute(String taskName,
                                     @Nullable
                                     T arg)
```
    Executes given task on this grid projection. For step-by-step explanation of task execution process refer to GridComputeTask documentation.
    If task for given name has not been deployed yet, then taskName will be used as task class name to auto-deploy the task (see localDeployTask(Class, ClassLoader) method).
    
    Parameters:
    taskName - Name of the task to execute.
    arg - Optional argument of task execution, can be null.
    
    Returns:
    Task future.
    See Also:
    for information about task execution.
  - broadcast
```
GridFuture<?> broadcast(Runnable job)
```
    Broadcasts given job to all nodes in grid projection.
    
    Parameters:
    job - Job to broadcast to all projection nodes.
    
    Returns:
    Future for this execution.
  - broadcast
```
<R> GridFuture<Collection<R>> broadcast(Callable<R> job)
```
    Broadcasts given job to all nodes in grid projection. Every participating node will return a job result. Collection of all returned job results is returned from the result future.
    
    Parameters:
    job - Job to broadcast to all projection nodes.
    
    Returns:
    Future with collection of results for this execution.
  - broadcast
```
<R,T> GridFuture<Collection<R>> broadcast(GridClosure<T,R> job,
                                        @Nullable
                                        T arg)
```
    Broadcasts given closure job with passed in argument to all nodes in grid projection. Every participating node will return a job result. Collection of all returned job results is returned from the result future.
    
    Parameters:
    job - Job to broadcast to all projection nodes.
    arg - Job closure argument.
    
    Returns:
    Future with collection of results for this execution.
  - run
```
GridFuture<?> run(Runnable job)
```
    Executes provided job on a node in this grid projection.
    
    Parameters:
    job - Job closure to execute.
    
    Returns:
    Future of this execution.
  - run
```
GridFuture<?> run(Collection<? extends Runnable> jobs)
```
    Executes collection of jobs on grid nodes within this grid projection.
    
    Parameters:
    jobs - Collection of jobs to execute.
    
    Returns:
    Future for this execution.
  - call
```
<R> GridFuture<R> call(Callable<R> job)
```
    Executes provided job on a node in this grid projection. The result of the job execution is returned from teh result closure.
    
    Parameters:
    job - Job to execute.
    
    Returns:
    Future with job result for this execution.
  - call
```
<R> GridFuture<Collection<R>> call(Collection<? extends Callable<R>> jobs)
```
    Executes collection of jobs on nodes within this grid projection. Collection of all returned job results is returned from the result future.
    
    Parameters:
    jobs - Collection of jobs to execute.
    
    Returns:
    Future with collection of job results for this execution.
  - call
```
<R1,R2> GridFuture<R2> call(Collection<? extends Callable<R1>> jobs,
                          GridReducer<R1,R2> rdc)
```
    Executes collection of jobs on nodes within this grid projection. The returned job results will be reduced into an individual result by provided reducer.
    
    Parameters:
    jobs - Collection of jobs to execute.
    rdc - Reducer to reduce all job results into one individual return value.
    
    Returns:
    Future with reduced job result for this execution.
  - apply
```
<R,T> GridFuture<R> apply(GridClosure<T,R> job,
                        @Nullable
                        T arg)
```
    Executes provided closure job on a node in this grid projection. This method is different from run(...) and call(...) methods in a way that it receives job argument which is then passed into the closure at execution time.
    
    Parameters:
    job - Job to run.
    arg - Job argument.
    
    Returns:
    Future with job result for this execution.
  - apply
```
<T,R> GridFuture<Collection<R>> apply(GridClosure<T,R> job,
                                    Collection<? extends T> args)
```
    Executes provided closure job on nodes within this grid projection. A new job is executed for every argument in the passed in collection. The number of actual job executions will be equal to size of the job arguments collection.
    
    Parameters:
    job - Job to run.
    args - Job arguments.
    
    Returns:
    Future with collection of job results.
  - apply
```
<R1,R2,T> GridFuture<R2> apply(GridClosure<T,R1> job,
                             Collection<? extends T> args,
                             GridReducer<R1,R2> rdc)
```
    Executes provided closure job on nodes within this grid projection. A new job is executed for every argument in the passed in collection. The number of actual job executions will be equal to size of the job arguments collection. The returned job results will be reduced into an individual result by provided reducer.
    
    Parameters:
    job - Job to run.
    args - Job arguments.
    rdc - Reducer to reduce all job results into one individual return value.
    
    Returns:
    Future with reduced job result for this execution.
  - executorService
```
ExecutorService executorService()
```
    Creates new ExecutorService which will execute all submitted Callable and Runnable jobs on nodes in this grid projection. This essentially creates a Distributed Thread Pool that can be used as a replacement for local thread pools.
    
    Returns:
    Grid-enabled ExecutorService.
  taskFuture
  
  @Nullable <R> GridComputeTaskFuture<R> taskFuture(GridUuid sesId)
  
  Gets task future based on execution session ID. If task execution was started on local node and this projection includes local node then the future for this task will be returned.
  
  Type Parameters:
  R - Task result type.
  Parameters:
  sesId - Session ID for task execution.
  
  Returns:
  Task future if task was started on this node and this node belongs to this projection, or null otherwise.
  
  cancelTask
  
  void cancelTask(GridUuid sesId) throws GridException
  
  Cancels task with the given execution session ID, if it currently running inside this projection.
  
  Parameters:
  sesId - Execution session ID.
  
  Throws:
  
  GridException - If task cancellation failed.
  
  cancelJob
  
  void cancelJob(GridUuid jobId) throws GridException
  
  Cancels job with the given job ID, if it is currently running inside this projection.
  
  Parameters:
  jobId - Job ID.
  
  Throws:
  
  GridException - If task cancellation failed.
  
  withName
  
  GridCompute withName(String taskName)
  
  Sets task name for the next executed task on this projection in the current thread. When task starts execution, the name is reset, so one name is used only once. You may use this method to set task name when executing jobs directly, without explicitly defining GridComputeTask.
  Here is an example.
  GridGain.grid().withName("MyTask").run(new MyRunnable() {...});
  
  Parameters:
  taskName - Task name.
  
  Returns:
  This GridCompute instance for chaining calls.
  
  withTimeout
  
  GridCompute withTimeout(long timeout)
  
  Sets task timeout for the next executed task on this projection in the current thread. When task starts execution, the timeout is reset, so one timeout is used only once. You may use this method to set task name when executing jobs directly, without explicitly defining GridComputeTask.
  Here is an example.
  GridGain.grid().withTimeout(10000).run(new MyRunnable() {...});
  
  Parameters:
  timeout - Computation timeout in milliseconds.
  
  Returns:
  This GridCompute instance for chaining calls.
  
  withNoFailover
  
  GridCompute withNoFailover()
  
  Sets no-failover flag for the next executed task on this projection in the current thread. If flag is set, job will be never failed over even if remote node crashes or rejects execution. When task starts execution, the no-failover flag is reset, so all other task will use default failover policy, unless this flag is set again.
  Here is an example.
  GridGain.grid().compute().withNoFailover().run(new MyRunnable() {...});
  
  Returns:
  Grid projection (this).
  
  localDeployTask
  
  void localDeployTask(Class<? extends GridComputeTask> taskCls, ClassLoader clsLdr) throws GridException
  
  Explicitly deploys a task with given class loader on the local node. Upon completion of this method, a task can immediately be executed on the grid, considering that all participating remote nodes also have this task deployed.
  Note that tasks are automatically deployed upon first execution (if peer-class-loading is enabled), so use this method only when the provided class loader is different from the taskClass.getClassLoader().
  Another way of class deployment is deployment from local class path. Classes from local class path always have a priority over P2P deployed ones.
  Note that class can be deployed multiple times on remote nodes, i.e. re-deployed. GridGain maintains internal version of deployment for each instance of deployment (analogous to class and class loader in Java). Execution happens always on the latest deployed instance.
  This method has no effect if the class passed in was already deployed.
  
  Parameters:
  taskCls - Task class to deploy. If task class has GridComputeTaskName annotation, then task will be deployed under the name specified within annotation. Otherwise, full class name will be used as task's name.
  clsLdr - Task class loader. This class loader is in charge of loading all necessary resources for task execution.
  
  Throws:
  
  GridException - If task is invalid and cannot be deployed.
  
  localTasks
  
  Map<String,Class<? extends GridComputeTask<?,?>>> localTasks()
  
  Gets map of all locally deployed tasks keyed by their task name .
  
  Returns:
  Map of locally deployed tasks keyed by their task name.
  
  undeployTask
  
  void undeployTask(String taskName) throws GridException
  
  Makes the best attempt to undeploy a task with given name from this grid projection. Note that this method returns immediately and does not wait until the task will actually be undeployed on every node.
  
  Parameters:
  taskName - Name of the task to undeploy.
  
  Throws:
  
  GridException - Thrown if undeploy failed.

Interface GridCompute

Serializable

Load Balancing

Fault Tolerance

Resource Injection

Computation SPIs

Method Summary

Method Detail

projection

affinityRun

affinityCall

execute

execute

execute

broadcast

broadcast

broadcast

run

run

call

call

call

apply

apply

apply

executorService

taskFuture

cancelTask

cancelJob

withName

withTimeout

withNoFailover

localDeployTask

localTasks

undeployTask