org.gridgain.grid.spi.loadbalancing.roundrobin
Class GridRoundRobinLoadBalancingSpi

java.lang.Object
  org.gridgain.grid.spi.GridSpiAdapter
      org.gridgain.grid.spi.loadbalancing.roundrobin.GridRoundRobinLoadBalancingSpi

All Implemented Interfaces:

GridSpi, GridSpiManagementMBean, GridLoadBalancingSpi, GridRoundRobinLoadBalancingSpiMBean

@GridSpiInfo(author="GridGain Systems",
             url="www.gridgain.org",
             email="support@gridgain.com",
             version="x.x")
@GridSpiMultipleInstancesSupport(value=true)
public class GridRoundRobinLoadBalancingSpi
extends GridSpiAdapter
implements GridLoadBalancingSpi, GridRoundRobinLoadBalancingSpiMBean

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 GridRoundRobinLoadBalancingSpi.setPerTask(boolean) configuration).

When configured in per-task mode, implementation will pick a random starting node at the beginning of every task execution and then sequentially iterate through all nodes in topology starting from the picked node. This is the default configuration and should fit most of the use cases as it provides a fairly well-distributed split and also ensures that jobs within a single task are spread out across nodes to the maximum. 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 GridTaskSplitAdapter 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 GridTaskSplitAdapter<Object, Object> {
    @Override
    protected Collection<? extends GridJob> split(int gridSize, Object arg) throws GridException {
        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 GridTaskAdapter. 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 GridTaskAdapter<String, String> {
    // Inject load balancer.
    @GridLoadBalancerResource
    GridLoadBalancer balancer;

    // Map jobs to grid nodes.
    public Map<? extends GridJob, GridNode> map(List<GridNode> subgrid, String arg) throws GridException {
        Map<MyFooBarJob, GridNode> jobs = new HashMap<MyFooBarJob, GridNode>(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<GridJobResult> results) throws GridException {
        // For the purpose of this example we simply
        // concatenate string representation of every
        // job result
        StringBuilder buf = new StringBuilder();

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

        return buf.toString();
    }
 }
 

Configuration

In order to use this load balancer, you should configure your grid instance to use GridRoundRobinLoadBalancingSpi 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 GridRoundRobinLoadBalancingSpi.setPerTask(boolean)).

Below is Java configuration example:

 GridRandomLoadBalancingSpi = new GridRandomLoadBalancingSpi();

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

 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

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

 // Start grid.
 GridFactory.start(cfg);
 

Here is how you can configure GridRandomLoadBalancingSpi using Spring XML configuration:

 <property name="loadBalancingSpi">
     <bean class="org.gridgain.grid.spi.loadbalancing.roundrobin.GridRoundRobinLoadBalancingSpi">
         <!-- Set to global round-robin mode. -->
         <property name="perTask" value="false"/>
     </bean>
 </property>
 

For information about Spring framework visit www.springframework.org



See Also:

Documentation
Email Support
Online Forums
Issue Tracking

Author: 2005-2008 Copyright © GridGain Systems. All Rights Reserved. ver. 2.1.0

	Nikita Ivanov, GridGain Systems nivanov@gridgain.com
	Dmitriy Setrakyan, GridGain Systems dsetrakyan@gridgain.com
	Alexander Magdenko, GridGain Systems amagdenko@gridgain.com
	Boris Suchodoev, GridGain Systems bsuchodoev@gridgain.com
	Denis Kharlamov, GridGain Systems dkharlamov@gridgain.com
	close

Constructor Summary

GridRoundRobinLoadBalancingSpi()

Method Summary

GridNode	getBalancedNode(GridTaskSession ses, List<GridNode> top, GridJob job) Gets balanced node for specified job within given task session.
boolean	isPerTask() Configuration parameter indicating whether a new round robin order should be created for every task.
void	onContextDestroyed() Callback invoked prior to stopping grid before SPI context is destroyed. Once this method is complete, grid will begin shutdown sequence. Use this callback for de-initialization logic that may involve SPI context. Note that invoking SPI context after this callback is complete is considered illegal and may produce unknown results. If GridSpiAdapter is used for SPI implementation, then it will replace actual context with dummy no-op context which is usually good-enough since grid is about to shut down.
void	onContextInitialized(GridSpiContext spiCtx) Callback invoked when SPI context is initialized. SPI implementation may store SPI context for future access. This method is invoked after GridSpi.spiStart(String) method is completed, so SPI should be fully functional at this point. Use this method for post-start initialization, such as subscribing a discovery listener, sending a message to remote node, etc...
void	setPerTask(boolean isPerTask) Configuration parameter indicating whether a new round robin order should be created for every task.
void	spiStart(String gridName) This method is called to start SPI.
void	spiStop() This method is called to stop SPI.
String	toString()

Methods inherited from class org.gridgain.grid.spi.GridSpiAdapter

assertParameter, configInfo, createSpiAttributeName, getAuthor, getConsistentAttributeNames, getGridGainHome, getLocalNodeId, getName, getNodeAttributes, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion, registerMBean, setName, setSpiContext, 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.gridgain.grid.spi.GridSpi

getName, getNodeAttributes

Methods inherited from interface org.gridgain.grid.spi.GridSpiManagementMBean

getAuthor, getGridGainHome, getLocalNodeId, getName, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion

Constructor Detail

GridRoundRobinLoadBalancingSpi

public GridRoundRobinLoadBalancingSpi()

Method Detail

isPerTask

public 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 true.

Specified by:

isPerTask in interface GridRoundRobinLoadBalancingSpiMBean

Returns:

Configuration parameter indicating whether a new round robin order should be created for every task. Default is true.

setPerTask

@GridSpiConfiguration(optional=true)
public void 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 true.

Parameters:

isPerTask - Configuration parameter indicating whether a new round robin order should be created for every task. Default is true.

spiStart

public void spiStart(@Nullable
                     String gridName)
              throws GridSpiException

This method is called to start SPI. After this method returns successfully kernel assumes that SPI is fully operational.

Specified by:

spiStart in interface GridSpi

Throws:

GridSpiException - Throws in case of any error during SPI start.

Parameters:

gridName - Name of grid instance this SPI is being started for (null for default grid).

spiStop

public void spiStop()
             throws GridSpiException

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 GridSpi

Throws:

GridSpiException - Thrown in case of any error during SPI stop.

onContextInitialized

public void onContextInitialized(GridSpiContext spiCtx)
                          throws GridSpiException

Callback invoked when SPI context is initialized. SPI implementation may store SPI context for future access.

This method is invoked after GridSpi.spiStart(String) method is completed, so SPI should be fully functional at this point. Use this method for post-start initialization, such as subscribing a discovery listener, sending a message to remote node, etc...

Specified by:

onContextInitialized in interface GridSpi

Overrides:

onContextInitialized in class GridSpiAdapter

Throws:

GridSpiException - If context initialization failed (grid will be stopped).

Parameters:

spiCtx - Spi context.

onContextDestroyed

public void onContextDestroyed()

Callback invoked prior to stopping grid before SPI context is destroyed. Once this method is complete, grid will begin shutdown sequence. Use this callback for de-initialization logic that may involve SPI context. Note that invoking SPI context after this callback is complete is considered illegal and may produce unknown results.

If GridSpiAdapter is used for SPI implementation, then it will replace actual context with dummy no-op context which is usually good-enough since grid is about to shut down.

Specified by:

onContextDestroyed in interface GridSpi

Overrides:

onContextDestroyed in class GridSpiAdapter

getBalancedNode

public GridNode getBalancedNode(GridTaskSession ses,
                                List<GridNode> top,
                                GridJob job)
                         throws GridException

Gets balanced node for specified job within given task session.

Specified by:

getBalancedNode in interface GridLoadBalancingSpi

Throws:

GridException - If failed to get next balanced node.

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.

toString

public String toString()

Overrides:

toString in class Object