Package org.apache.ignite.spi.collision

## Interface CollisionSpi

- All Superinterfaces:
    `IgniteSpi`
  All Known Implementing Classes:
    `FifoQueueCollisionSpi`, `JobStealingCollisionSpi`, `NoopCollisionSpi`, `PriorityQueueCollisionSpi`

      public interface CollisionSpi
      extends IgniteSpi

  Collision SPI allows to regulate how grid jobs get executed when they arrive on a destination node for execution. Its functionality is similar to tasks management via customizable GCD (Great Central Dispatch) on Mac OS X as it allows developer to provide custom job dispatching on a single node. In general a grid node will have multiple jobs arriving to it for execution and potentially multiple jobs that are already executing or waiting for execution on it. There are multiple possible strategies dealing with this situation, like all jobs can proceed in parallel, or jobs can be serialized i.e., or only one job can execute in any given point of time, or only certain number or types of grid jobs can proceed in parallel, etc...

  Collision SPI provides developer with ability to use the custom logic in determining how grid jobs should be executed on a destination grid node. Ignite comes with the following ready implementations for collision resolution that cover most popular strategies:

  - `FifoQueueCollisionSpi`
  - `PriorityQueueCollisionSpi`
  - `JobStealingCollisionSpi`
  NOTE: this SPI (i.e. methods in this interface) should never be used directly. SPIs provide internal view on the subsystem and is used internally by Ignite kernal. In rare use cases when access to a specific implementation of this SPI is required - an instance of this SPI can be obtained via `Ignite.configuration()` method to check its configuration properties or call other non-SPI methods. Note again that calling methods from this interface on the obtained instance can lead to undefined behavior and explicitly not supported.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `onCollision​(CollisionContext ctx)` | This is a callback called: new grid job arrived executing job finished its execution topology changed periodically (on `EventType.EVT_NODE_METRICS_UPDATED`) When new job arrives it is added to the end of the wait list and this method is called.
    `void` | `setExternalCollisionListener​(@Nullable CollisionExternalListener lsnr)` | Listener to be set for notification of external collision events (e.g. job stealing).

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

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

- - ### Method Detail

    - #### onCollision

          void onCollision​(CollisionContext ctx)

      This is a callback called:
      - new grid job arrived
      - executing job finished its execution
      - topology changed
      - periodically (on `EventType.EVT_NODE_METRICS_UPDATED`)
      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.

      Parameters:
        `ctx` - Collision context which contains all collision lists.

    - #### setExternalCollisionListener

          void setExternalCollisionListener​(@Nullable
                                            @Nullable 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.

      Parameters:
        `lsnr` - Listener for external collision events.