Package org.apache.ignite.spi.loadbalancing.roundrobin

## Class RoundRobinLoadBalancingSpi

- java.lang.Object
- - org.apache.ignite.spi.IgniteSpiAdapter
  - - org.apache.ignite.spi.loadbalancing.roundrobin.RoundRobinLoadBalancingSpi

- All Implemented Interfaces:
    `IgniteSpi`, `LoadBalancingSpi`

      @IgniteSpiMultipleInstancesSupport(true)
      public class RoundRobinLoadBalancingSpi
      extends IgniteSpiAdapter
      implements LoadBalancingSpi

  This SPI iterates through nodes in round-robin fashion and pick the next sequential node. Two modes of operation are supported: per-task and global (see `setPerTask(boolean)` configuration). Global mode is used be default.

  When configured in per-task mode, implementation will pick a random node at the beginning of every task execution and then sequentially iterate through all nodes in topology starting from the picked node. For cases when split size is equal to the number of nodes, this mode guarantees that all nodes will participate in the split.

  When configured in global mode, a single sequential queue of nodes is maintained for all tasks and the next node in the queue is picked every time. In this mode (unlike in `per-task` mode) it is possible that even if split size may be equal to the number of nodes, some jobs within the same task will be assigned to the same node if multiple tasks are executing concurrently.

  # Coding Example

  If you are using `ComputeTaskSplitAdapter` then load balancing logic is transparent to your code and is handled automatically by the adapter. Here is an example of how your task will look:

       public class MyFooBarTask extends ComputeTaskSplitAdapter<Object, Object> {
          @Override
          protected Collection<? extends ComputeJob> split(int gridSize, Object arg) throws IgniteCheckedException {
              List<MyFooBarJob> jobs = new ArrayList<MyFooBarJob>(gridSize);

              for (int i = 0; i < gridSize; i++) {
                  jobs.add(new MyFooBarJob(arg));
              }

              // Node assignment via load balancer
              // happens automatically.
              return jobs;
          }
          ...
       }

  If you need more fine-grained control over how some jobs within task get mapped to a node and use affinity load balancing for some other jobs within task, then you should use `ComputeTaskAdapter`. Here is an example of how your task will look. Note that in this case we manually inject load balancer and use it to pick the best node. Doing it in such way would allow user to map some jobs manually and for others use load balancer.

       public class MyFooBarTask extends ComputeTaskAdapter<String, String> {
          // Inject load balancer.
          @LoadBalancerResource
          ComputeLoadBalancer balancer;

          // Map jobs to grid nodes.
          public Map<? extends ComputeJob, ClusterNode> map(List<ClusterNode> subgrid, String arg) throws IgniteCheckedException {
              Map<MyFooBarJob, ClusterNode> jobs = new HashMap<MyFooBarJob, ClusterNode>(subgrid.size());

              // In more complex cases, you can actually do
              // more complicated assignments of jobs to nodes.
              for (int i = 0; i < subgrid.size(); i++) {
                  // Pick the next best balanced node for the job.
                  jobs.put(new MyFooBarJob(arg), balancer.getBalancedNode())
              }

              return jobs;
          }

          // Aggregate results into one compound result.
          public String reduce(List<ComputeJobResult> results) throws IgniteCheckedException {
              // For the purpose of this example we simply
              // concatenate string representation of every
              // job result
              StringBuilder buf = new StringBuilder();

              for (ComputeJobResult res : results) {
                  // Append string representation of result
                  // returned by every job.
                  buf.append(res.getData().string());
              }

              return buf.string();
          }
       }

  # Configuration

  In order to use this load balancer, you should configure your grid instance to use `RoundRobinLoadBalancingSpi` either from Spring XML file or directly. The following configuration parameters are supported:

  ## Mandatory

  This SPI has no mandatory configuration parameters.

  ## Optional

  The following configuration parameters are optional:
  - Flag that indicates whether to use `per-task` or global round-robin modes described above (see `setPerTask(boolean)`).
  Below is Java configuration example:

       RoundRobinLoadBalancingSpi spi = new RoundRobinLoadBalancingSpi();

       // Configure SPI to use global round-robin mode.
       spi.setPerTask(false);

       IgniteConfiguration cfg = new IgniteConfiguration();

       // Override default load balancing SPI.
       cfg.setLoadBalancingSpi(spi);

       // Starts grid.
       G.start(cfg);

  Here is how you can configure `RoundRobinLoadBalancingSpi` using Spring XML configuration:

       <property name="loadBalancingSpi">
           <bean class="org.apache.ignite.spi.loadBalancing.roundrobin.RoundRobinLoadBalancingSpi">
               <!-- Set to global round-robin mode. -->
               <property name="perTask" value="false"/>
           </bean>
       </property>

  For information about Spring framework visit www.springframework.org

- - ### Field Summary

    - ### Fields inherited from class org.apache.ignite.spi.IgniteSpiAdapter

      `ignite, igniteInstanceName`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RoundRobinLoadBalancingSpi()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ClusterNode` | `getBalancedNode​(ComputeTaskSession ses, List<ClusterNode> top, ComputeJob job)` | Gets balanced node for specified job within given task session.
    `boolean` | `isPerTask()` | See `setPerTask(boolean)`.
    `protected void` | `onContextDestroyed0()` | Method to be called in the beginning of onContextDestroyed() method.
    `protected void` | `onContextInitialized0​(IgniteSpiContext spiCtx)` | Method to be called in the end of onContextInitialized method.
    `RoundRobinLoadBalancingSpi` | `setName​(String name)` | Sets SPI name.
    `RoundRobinLoadBalancingSpi` | `setPerTask​(boolean isPerTask)` | Configuration parameter indicating whether a new round robin order should be created for every task.
    `void` | `spiStart​(@Nullable String igniteInstanceName)` | This method is called to start SPI.
    `void` | `spiStop()` | This method is called to stop SPI.
    `String` | `toString()`

    - ### Methods inherited from class org.apache.ignite.spi.IgniteSpiAdapter

      `addTimeoutObject, assertParameter, checkConfigurationConsistency0, clientFailureDetectionTimeout, configInfo, createSpiAttributeName, failureDetectionTimeout, failureDetectionTimeoutEnabled, failureDetectionTimeoutEnabled, getConsistentAttributeNames, getExceptionRegistry, getLocalNode, getName, getNodeAttributes, getSpiContext, ignite, initFailureDetectionTimeout, injectables, injectResources, isNodeStopping, onBeforeStart, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextInitialized, registerMBean, removeTimeoutObject, started, startInfo, startStopwatch, stopInfo, unregisterMBean`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.ignite.spi.IgniteSpi

      `getName, getNodeAttributes, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextInitialized`

- - ### Constructor Detail

    - #### RoundRobinLoadBalancingSpi

          public RoundRobinLoadBalancingSpi()

  - ### Method Detail

    - #### isPerTask

          public boolean isPerTask()

      See `setPerTask(boolean)`.
      Returns:
        Configuration parameter indicating whether a new round robin order should be created for every task. Default is `false`.

    - #### setPerTask

          @IgniteSpiConfiguration(optional=true)
          public RoundRobinLoadBalancingSpi setPerTask​(boolean isPerTask)

      Configuration parameter indicating whether a new round robin order should be created for every task. If `true` then load balancer is guaranteed to iterate through nodes sequentially for every task - so as long as number of jobs is less than or equal to the number of nodes, jobs are guaranteed to be assigned to unique nodes. If `false` then one round-robin order will be maintained for all tasks, so when tasks execute concurrently, it is possible for more than one job within task to be assigned to the same node.

      Default is `false`.

      Parameters:
        `isPerTask` - Configuration parameter indicating whether a new round robin order should be created for every task. Default is `false`.
      Returns:
        `this` for chaining.

    - #### spiStart

          public void spiStart​(@Nullable
                               @Nullable String igniteInstanceName)
                        throws IgniteSpiException

      This method is called to start SPI. After this method returns successfully kernel assumes that SPI is fully operational.
      Specified by:
        `spiStart` in interface `IgniteSpi`
      Parameters:
        `igniteInstanceName` - Name of Ignite instance this SPI is being started for (`null` for default Ignite instance).
      Throws:
        `IgniteSpiException` - Throws in case of any error during SPI start.

    - #### spiStop

          public void spiStop()
                       throws IgniteSpiException

      This method is called to stop SPI. After this method returns kernel assumes that this SPI is finished and all resources acquired by it are released.

      Note that this method can be called at any point including during recovery of failed start. It should make no assumptions on what state SPI will be in when this method is called.

      Specified by:
        `spiStop` in interface `IgniteSpi`
      Throws:
        `IgniteSpiException` - Thrown in case of any error during SPI stop.

    - #### onContextInitialized0

          protected void onContextInitialized0​(IgniteSpiContext spiCtx)
                                        throws IgniteSpiException

      Method to be called in the end of onContextInitialized method.
      Overrides:
        `onContextInitialized0` in class `IgniteSpiAdapter`
      Parameters:
        `spiCtx` - SPI context.
      Throws:
        `IgniteSpiException` - In case of errors.

    - #### onContextDestroyed0

          protected void onContextDestroyed0()

      Method to be called in the beginning of onContextDestroyed() method.
      Overrides:
        `onContextDestroyed0` in class `IgniteSpiAdapter`

    - #### getBalancedNode

          public ClusterNode getBalancedNode​(ComputeTaskSession ses,
                                             List<ClusterNode> top,
                                             ComputeJob job)

      Gets balanced node for specified job within given task session.
      Specified by:
        `getBalancedNode` in interface `LoadBalancingSpi`
      Parameters:
        `ses` - Grid task session for currently executing task.
        `top` - Topology of task nodes from which to pick the best balanced node for given job.
        `job` - Job for which to pick the best balanced node.
      Returns:
        Best balanced node for the given job within given task session.

    - #### setName

          public RoundRobinLoadBalancingSpi setName​(String name)

      Sets SPI name.
      Overrides:
        `setName` in class `IgniteSpiAdapter`
      Parameters:
        `name` - SPI name.
      Returns:
        `this` for chaining.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`