org.apache.ignite.spi.collision.fifoqueue

## Class FifoQueueCollisionSpi

- java.lang.Object
- - org.apache.ignite.spi.IgniteSpiAdapter
  - - org.apache.ignite.spi.collision.fifoqueue.FifoQueueCollisionSpi

All Implemented Interfaces:
  CollisionSpi, FifoQueueCollisionSpiMBean, IgniteSpi, IgniteSpiManagementMBean

    @IgniteSpiMultipleInstancesSupport(value=true)
    public class FifoQueueCollisionSpi
    extends IgniteSpiAdapter
    implements CollisionSpi, FifoQueueCollisionSpiMBean

This class provides implementation for Collision SPI based on FIFO queue. Jobs are ordered as they arrived and only `getParallelJobsNumber()` number of jobs is allowed to execute in parallel. Other jobs will be buffered in the passive queue.

# Configuration

## Mandatory

This SPI has no mandatory configuration parameters.

## Optional

This SPI has following optional configuration parameters:

- Number of jobs that can execute in parallel (see `setParallelJobsNumber(int)`). This number should usually be set to the number of threads in the execution thread pool.

## Java Example

`FifoQueueCollisionSpi` can be configured as follows:

     FifoQueueCollisionSpi colSpi = new FifoQueueCollisionSpi();

     // Execute all jobs sequentially by setting parallel job number to 1.
     colSpi.setParallelJobsNumber(1);

     IgniteConfiguration cfg = new IgniteConfiguration();

     // Override default collision SPI.
     cfg.setCollisionSpi(colSpi);

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

## Spring Example

`FifoQueueCollisionSpi` can be configured from Spring XML configuration file:

     <bean id="grid.custom.cfg" class="org.apache.ignite.configuration.IgniteConfiguration" singleton="true">
           ...
           <property name="collisionSpi">
               <bean class="org.apache.ignite.spi.collision.fifoqueue.FifoQueueCollisionSpi">
                   <property name="parallelJobsNumber" value="1"/>
               </bean>
           </property>
           ...
     </bean>

### Field Summary

Fields
`static int` `DFLT_PARALLEL_JOBS_NUM` Default number of parallel jobs allowed (set to number of cores times 2).
`static int` `DFLT_WAIT_JOBS_NUM` Default waiting jobs number.

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

`gridName, ignite`

### Constructor Summary

Constructors
Constructor and Description
`FifoQueueCollisionSpi()`

### Method Summary

Methods
`int` `getCurrentActiveJobsNumber()` Gets current number of jobs that are active, i.e.
`int` `getCurrentHeldJobsNumber()` Gets number of currently `'held'` jobs.
`int` `getCurrentRunningJobsNumber()`
`int` `getCurrentWaitJobsNumber()` Gets current number of jobs that wait for the execution.
`int` `getParallelJobsNumber()` Gets number of jobs that can be executed in parallel.
`int` `getWaitingJobsNumber()` Maximum number of jobs that are allowed to wait in waiting queue.
`void` `onCollision(CollisionContext ctx)` This is a callback called when either new grid job arrived or executing job finished its execution.
`void` `setExternalCollisionListener(CollisionExternalListener lsnr)` Listener to be set for notification of external collision events (e.g. job stealing).
`void` `setParallelJobsNumber(int parallelJobsNum)` Sets number of jobs that can be executed in parallel.
`void` `setWaitingJobsNumber(int waitJobsNum)` Sets maximum number of jobs that are allowed to wait in waiting queue.
`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.apache.ignite.spi.IgniteSpiAdapter

`addTimeoutObject, assertParameter, checkConfigurationConsistency0, configInfo, createSpiAttributeName, failureDetectionTimeout, failureDetectionTimeoutEnabled, failureDetectionTimeoutEnabled, getConsistentAttributeNames, getExceptionRegistry, getIgniteHome, getLocalNode, getLocalNodeId, getName, getNodeAttributes, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, initFailureDetectionTimeout, injectables, injectResources, isNodeStopping, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextDestroyed0, onContextInitialized, onContextInitialized0, registerMBean, removeTimeoutObject, setName, 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`

### Methods inherited from interface org.apache.ignite.spi.IgniteSpiManagementMBean

`getIgniteHome, getLocalNodeId, getName, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted`

### Field Detail

#### DFLT_PARALLEL_JOBS_NUM

    public static final int DFLT_PARALLEL_JOBS_NUM

Default number of parallel jobs allowed (set to number of cores times 2).

#### DFLT_WAIT_JOBS_NUM

    public static final int DFLT_WAIT_JOBS_NUM

Default waiting jobs number. If number of waiting jobs exceeds this number, jobs will be rejected. Default value is `Integer.MAX_VALUE`.

See Also:
  Constant Field Values

### Constructor Detail

#### FifoQueueCollisionSpi

    public FifoQueueCollisionSpi()

### Method Detail

#### getParallelJobsNumber

    public int getParallelJobsNumber()

Gets number of jobs that can be executed in parallel.

Specified by:
  `getParallelJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Returns:
  Number of jobs that can be executed in parallel.

#### setParallelJobsNumber

    @IgniteSpiConfiguration(optional=true)
    public void setParallelJobsNumber(int parallelJobsNum)

Sets number of jobs that can be executed in parallel.

Specified by:
  `setParallelJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Parameters:
  `parallelJobsNum` - Parallel jobs number.

#### getWaitingJobsNumber

    public int getWaitingJobsNumber()

Maximum number of jobs that are allowed to wait in waiting queue. If number of waiting jobs ever exceeds this number, excessive jobs will be rejected.

Specified by:
  `getWaitingJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Returns:
  Maximum allowed number of waiting jobs.

#### setWaitingJobsNumber

    @IgniteSpiConfiguration(optional=true)
    public void setWaitingJobsNumber(int waitJobsNum)

Sets maximum number of jobs that are allowed to wait in waiting queue. If number of waiting jobs ever exceeds this number, excessive jobs will be rejected.

Specified by:
  `setWaitingJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Parameters:
  `waitJobsNum` - Waiting jobs number.

#### getCurrentWaitJobsNumber

    public int getCurrentWaitJobsNumber()

Gets current number of jobs that wait for the execution.

Specified by:
  `getCurrentWaitJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Returns:
  Number of jobs that wait for execution.

#### getCurrentActiveJobsNumber

    public int getCurrentActiveJobsNumber()

Gets current number of jobs that are active, i.e. `'running + held'` jobs.

Specified by:
  `getCurrentActiveJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Returns:
  Number of active jobs.

#### getCurrentRunningJobsNumber

    public int getCurrentRunningJobsNumber()

Specified by:
  `getCurrentRunningJobsNumber` in interface `FifoQueueCollisionSpiMBean`

#### getCurrentHeldJobsNumber

    public int getCurrentHeldJobsNumber()

Gets number of currently `'held'` jobs.

Specified by:
  `getCurrentHeldJobsNumber` in interface `FifoQueueCollisionSpiMBean`
Returns:
  Number of currently `'held'` jobs.

#### spiStart

    public void spiStart(String gridName)
                  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:
  `gridName` - Name of grid instance this SPI is being started for (`null` for default grid).
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.

#### setExternalCollisionListener

    public void setExternalCollisionListener(CollisionExternalListener lsnr)

Listener to be set for notification of external collision events (e.g. job stealing). Once grid receives such notification, it will immediately invoke collision SPI.

Ignite uses this listener to enable job stealing from overloaded to underloaded nodes. However, you can also utilize it, for instance, to provide time based collision resolution. To achieve this, you most likely would mark some job by setting a certain attribute in job context (see `ComputeJobContext`) for a job that requires time-based scheduling and set some timer in your SPI implementation that would wake up after a certain period of time. Once this period is reached, you would notify this listener that a collision resolution should take place. Then inside of your collision resolution logic, you would find the marked waiting job and activate it.

Note that most collision SPI's might not have external collisions. In that case, they should simply ignore this method and do nothing when listener is set.

Specified by:
  `setExternalCollisionListener` in interface `CollisionSpi`
Parameters:
  `lsnr` - Listener for external collision events.

#### onCollision

    public void onCollision(CollisionContext ctx)

This is a callback called when either new grid job arrived or executing job finished its execution. When new job arrives it is added to the end of the wait list and this method is called. When job finished its execution, it is removed from the active list and this method is called (i.e., when grid job is finished it will not appear in any list in collision resolution).

Implementation of this method should act on all lists, each of which contains collision job contexts that define a set of operations available during collision resolution. Refer to `CollisionContext` and `CollisionJobContext` documentation for more information.

Specified by:
  `onCollision` in interface `CollisionSpi`
Parameters:
  `ctx` - Collision context which contains all collision lists.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.5.0-b1
Release Date | : December 1 2015