GridPriorityQueueCollisionSpi (gridgain-core 6.1.9 API)

java.lang.Object
- org.gridgain.grid.spi.GridSpiAdapter
- - org.gridgain.grid.spi.collision.priorityqueue.GridPriorityQueueCollisionSpi

All Implemented Interfaces:

GridCollisionSpi, GridPriorityQueueCollisionSpiMBean, GridSpi, GridSpiManagementMBean
```
@GridSpiMultipleInstancesSupport(value=true)
@GridSpiConsistencyChecked(optional=true)
public class GridPriorityQueueCollisionSpi
extends GridSpiAdapter
implements GridCollisionSpi, GridPriorityQueueCollisionSpiMBean
```
This class provides implementation for Collision SPI based on priority queue. Jobs are first ordered by their priority, if one is specified, and only first getParallelJobsNumber() jobs is allowed to execute in parallel. Other jobs will be queued up.
Configuration

Mandatory
This SPI has no mandatory configuration parameters.
Optional
This SPI has following optional configuration parameters:
- Number of jobs that can be executed in parallel (see setParallelJobsNumber(int)). This number should usually be set to no greater than number of threads in the execution thread pool.
- Priority attribute session key (see getPriorityAttributeKey()). Prior to returning from GridComputeTask.map(List, Object) method, task implementation should set a value into the task session keyed by this attribute key. See GridComputeTaskSession for more information about task session.
- Priority attribute job context key (see getJobPriorityAttributeKey()). It is used for specifying job priority. See GridComputeJobContext for more information about job context.
- Default priority value (see getDefaultPriority()). It is used when no priority is set.
- Default priority increase value (see getStarvationIncrement()). It is used for increasing priority when job gets bumped down. This future is used for preventing starvation waiting jobs execution.
- Default increasing priority flag value (see isStarvationPreventionEnabled()). It is used for enabling increasing priority when job gets bumped down. This future is used for preventing starvation waiting jobs execution.
Below is a Java example of configuration for priority collision SPI:
```
 GridPriorityQueueCollisionSpi colSpi = new GridPriorityQueueCollisionSpi();

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

 GridConfiguration cfg = new GridConfiguration();

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

 // Starts grid.
 G.start(cfg);
 
```
Here is Spring XML configuration example:
```
 <property name="collisionSpi">
     <bean class="org.gridgain.grid.spi.collision.priorityqueue.GridPriorityQueueCollisionSpi">
         <property name="priorityAttributeKey" value="myPriorityAttributeKey"/>
         <property name="parallelJobsNumber" value="10"/>
     </bean>
 </property>
 
```
Coding Example
Here is an example of a grid tasks that uses priority collision SPI configured in example above. Note that priority collision resolution is absolutely transparent to the user and is simply a matter of proper grid configuration. Also, priority may be defined only for task (it can be defined within the task, not at a job level). All split jobs will be started with priority declared in their owner task.
This example demonstrates how urgent task may be declared with a higher priority value. Priority SPI guarantees (see its configuration in example above, where number of parallel jobs is set to 1) that all jobs from MyGridUrgentTask will most likely be activated first (one by one) and jobs from MyGridUsualTask with lowest priority will wait. Once higher priority jobs complete, lower priority jobs will be scheduled.
```
 public class MyGridUsualTask extends GridComputeTaskSplitAdapter<Object, Object> {
    public static final int SPLIT_COUNT = 20;

    @GridTaskSessionResource
    private GridComputeTaskSession taskSes;

    @Override
    protected Collection<? extends GridComputeJob> split(int gridSize, Object arg) throws GridException {
        ...
        // Set low task priority (note that attribute name is used by the SPI
        // and should not be changed).
        taskSes.setAttribute("grid.task.priority", 5);

        Collection<GridComputeJob> jobs = new ArrayList<GridComputeJob>(SPLIT_COUNT);

        for (int i = 1; i <= SPLIT_COUNT; i++) {
            jobs.add(new GridComputeJobAdapter<Integer>(i) {
                ...
            });
        }
        ...
    }
 }
 
```
and
```
 public class MyGridUrgentTask extends GridComputeTaskSplitAdapter<Object, Object> {
    public static final int SPLIT_COUNT = 5;

    @GridTaskSessionResource
    private GridComputeTaskSession taskSes;

    @Override
    protected Collection<? extends GridComputeJob> split(int gridSize, Object arg) throws GridException {
        ...
        // Set high task priority (note that attribute name is used by the SPI
        // and should not be changed).
        taskSes.setAttribute("grid.task.priority", 10);

        Collection<GridComputeJob> jobs = new ArrayList<GridComputeJob>(SPLIT_COUNT);

        for (int i = 1; i <= SPLIT_COUNT; i++) {
            jobs.add(new GridComputeJobAdapter<Integer>(i) {
                ...
            });
        }
        ...
    }
 }
 
```
For information about Spring framework visit www.springframework.org

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DFLT_JOB_PRIORITY_ATTRIBUTE_KEY` Default job priority attribute key (value is `grid.job.priority`).
`static int`	`DFLT_PARALLEL_JOBS_NUM` Default number of parallel jobs allowed (value is `95` which is slightly less same as default value of threads in the execution thread pool to allow some extra threads for system processing).
`static boolean`	`DFLT_PREVENT_STARVATION_ENABLED` Default flag for preventing starvation of lower priority jobs.
`static int`	`DFLT_PRIORITY` Default priority that will be assigned if job does not have a priority attribute set (value is `0`).
`static String`	`DFLT_PRIORITY_ATTRIBUTE_KEY` Default priority attribute key (value is `grid.task.priority`).
`static int`	`DFLT_STARVATION_INCREMENT` Default value on which job priority will be increased every time when job gets bumped down.
`static int`	`DFLT_WAIT_JOBS_NUM` Default waiting jobs number.

Constructor Summary

Constructors
Constructor and Description

GridPriorityQueueCollisionSpi()

Constructors
Constructor and Description
`GridPriorityQueueCollisionSpi()`

Method Summary

Methods
Modifier and Type	Method and Description
`protected List<String>`	`getConsistentAttributeNames()` Returns back a list of attributes that should be consistent for this SPI.
`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`	`getDefaultPriority()` Gets default priority to use if a job does not have priority attribute set.
`String`	`getJobPriorityAttributeKey()` Gets key name of job priority attribute.
`Map<String,Object>`	`getNodeAttributes()` This method is called before SPI starts (before method `GridSpi.spiStart(String)` is called).
`int`	`getParallelJobsNumber()` Gets number of jobs that can be executed in parallel.
`String`	`getPriorityAttributeKey()` Gets key name of task priority attribute.
`int`	`getStarvationIncrement()` Gets value to increment job priority by every time a lower priority job gets behind a higher priority job.
`int`	`getWaitingJobsNumber()` Maximum number of jobs that are allowed to wait in waiting queue.
`boolean`	`isStarvationPreventionEnabled()` Gets flag indicating whether job starvation prevention is enabled.
`void`	`onCollision(GridCollisionContext ctx)` This is a callback called when either new grid job arrived or executing job finished its execution.
`void`	`setDefaultPriority(int dfltPri)` Sets default priority to use if a job does not have priority attribute set.
`void`	`setExternalCollisionListener(GridCollisionExternalListener lsnr)` Listener to be set for notification of external collision events (e.g.
`void`	`setJobPriorityAttributeKey(String jobPriAttrKey)` Sets job priority attribute key.
`void`	`setParallelJobsNumber(int parallelJobsNum)` Sets number of jobs that can be executed in parallel.
`void`	`setPriorityAttributeKey(String taskPriAttrKey)` Sets task priority attribute key.
`void`	`setStarvationIncrement(int starvationInc)` Sets value to increment job priority by every time a lower priority job gets behind a higher priority job.
`void`	`setStarvationPreventionEnabled(boolean preventStarvation)` Sets flag indicating whether job starvation prevention is enabled.
`void`	`setWaitingJobsNumber(int waitJobsNum)` 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.gridgain.grid.spi.GridSpiAdapter
assertParameter, checkConfigurationConsistency0, configInfo, createSpiAttributeName, getGridGainHome, getLocalNodeId, getName, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, injectables, onContextDestroyed, onContextDestroyed0, onContextInitialized, onContextInitialized0, registerMBean, 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.gridgain.grid.spi.GridSpi
getName, onContextDestroyed, onContextInitialized

Methods inherited from interface org.gridgain.grid.spi.GridSpiManagementMBean
getGridGainHome, 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 (value is 95 which is slightly less same as default value of threads in the execution thread pool to allow some extra threads for system processing).
    
    See Also:
    Constant Field Values
  - DFLT_WAIT_JOBS_NUM
```
public static final int DFLT_WAIT_JOBS_NUM
```
    Default waiting jobs number. If number of waiting jobs exceed this number, jobs will be rejected. Default value is Integer.MAX_VALUE.
    
    See Also:
    Constant Field Values
  - DFLT_PRIORITY_ATTRIBUTE_KEY
```
public static final String DFLT_PRIORITY_ATTRIBUTE_KEY
```
    Default priority attribute key (value is grid.task.priority).
    
    See Also:
    Constant Field Values
  - DFLT_JOB_PRIORITY_ATTRIBUTE_KEY
```
public static final String DFLT_JOB_PRIORITY_ATTRIBUTE_KEY
```
    Default job priority attribute key (value is grid.job.priority).
    
    See Also:
    Constant Field Values
  - DFLT_PRIORITY
```
public static final int DFLT_PRIORITY
```
    Default priority that will be assigned if job does not have a priority attribute set (value is 0).
    
    See Also:
    Constant Field Values
  - DFLT_STARVATION_INCREMENT
```
public static final int DFLT_STARVATION_INCREMENT
```
    Default value on which job priority will be increased every time when job gets bumped down.
    
    See Also:
    Constant Field Values
  - DFLT_PREVENT_STARVATION_ENABLED
```
public static final boolean DFLT_PREVENT_STARVATION_ENABLED
```
    Default flag for preventing starvation of lower priority jobs.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - GridPriorityQueueCollisionSpi
```
public GridPriorityQueueCollisionSpi()
```
- Method Detail
  - getParallelJobsNumber
```
public int getParallelJobsNumber()
```
    Gets number of jobs that can be executed in parallel.
    
    Specified by:
    
    getParallelJobsNumber in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Number of jobs that can be executed in parallel.
  - setParallelJobsNumber
```
@GridSpiConfiguration(optional=true)
public void setParallelJobsNumber(int parallelJobsNum)
```
    Sets number of jobs that can be executed in parallel.
    
    Specified by:
    
    setParallelJobsNumber in interface GridPriorityQueueCollisionSpiMBean
    
    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 GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Maximum allowed number of waiting jobs.
  - setWaitingJobsNumber
```
@GridSpiConfiguration(optional=true)
public void setWaitingJobsNumber(int waitJobsNum)
```
    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 GridPriorityQueueCollisionSpiMBean
    
    Parameters:
    waitJobsNum - Maximium jobs number.
  - getCurrentWaitJobsNumber
```
public int getCurrentWaitJobsNumber()
```
    Gets current number of jobs that wait for the execution.
    
    Specified by:
    
    getCurrentWaitJobsNumber in interface GridPriorityQueueCollisionSpiMBean
    
    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 GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Number of active jobs.
  - getCurrentRunningJobsNumber
```
public int getCurrentRunningJobsNumber()
```
    Specified by:
    
    getCurrentRunningJobsNumber in interface GridPriorityQueueCollisionSpiMBean
  - getCurrentHeldJobsNumber
```
public int getCurrentHeldJobsNumber()
```
    Gets number of currently 'held' jobs.
    
    Specified by:
    
    getCurrentHeldJobsNumber in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Number of currently 'held' jobs.
  - setPriorityAttributeKey
```
@GridSpiConfiguration(optional=true)
public void setPriorityAttributeKey(String taskPriAttrKey)
```
    Sets task priority attribute key. This key will be used to look up task priorities from task context (see GridComputeTaskSession.getAttribute(Object)).
    If not provided, default value is {@link #DFLT_PRIORITY_ATTRIBUTE_KEY}.
    
    Parameters:
    taskPriAttrKey - Priority session attribute key.
  - setJobPriorityAttributeKey
```
@GridSpiConfiguration(optional=true)
public void setJobPriorityAttributeKey(String jobPriAttrKey)
```
    Sets job priority attribute key. This key will be used to look up job priorities from job context (see GridComputeJobContext.getAttribute(Object)).
    If not provided, default value is {@link #DFLT_JOB_PRIORITY_ATTRIBUTE_KEY}.
    
    Parameters:
    jobPriAttrKey - Job priority attribute key.
  - getPriorityAttributeKey
```
public String getPriorityAttributeKey()
```
    Gets key name of task priority attribute.
    
    Specified by:
    
    getPriorityAttributeKey in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Key name of task priority attribute.
  - getJobPriorityAttributeKey
```
public String getJobPriorityAttributeKey()
```
    Gets key name of job priority attribute.
    
    Specified by:
    
    getJobPriorityAttributeKey in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Key name of job priority attribute.
  - getDefaultPriority
```
public int getDefaultPriority()
```
    Gets default priority to use if a job does not have priority attribute set.
    
    Specified by:
    
    getDefaultPriority in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Default priority to use if a task does not have priority attribute set.
  - setDefaultPriority
```
@GridSpiConfiguration(optional=true)
public void setDefaultPriority(int dfltPri)
```
    Sets default priority to use if a job does not have priority attribute set.
    
    Specified by:
    
    setDefaultPriority in interface GridPriorityQueueCollisionSpiMBean
    
    Parameters:
    dfltPri - default priority.
  - getStarvationIncrement
```
public int getStarvationIncrement()
```
    Gets value to increment job priority by every time a lower priority job gets behind a higher priority job.
    
    Specified by:
    
    getStarvationIncrement in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Value to increment job priority by every time a lower priority job gets behind a higher priority job.
  - setStarvationIncrement
```
@GridSpiConfiguration(optional=true)
public void setStarvationIncrement(int starvationInc)
```
    Sets value to increment job priority by every time a lower priority job gets behind a higher priority job.
    
    Specified by:
    
    setStarvationIncrement in interface GridPriorityQueueCollisionSpiMBean
    
    Parameters:
    starvationInc - Increment value.
  - isStarvationPreventionEnabled
```
public boolean isStarvationPreventionEnabled()
```
    Gets flag indicating whether job starvation prevention is enabled.
    
    Specified by:
    
    isStarvationPreventionEnabled in interface GridPriorityQueueCollisionSpiMBean
    
    Returns:
    Flag indicating whether job starvation prevention is enabled.
  - setStarvationPreventionEnabled
```
@GridSpiConfiguration(optional=true)
public void setStarvationPreventionEnabled(boolean preventStarvation)
```
    Sets flag indicating whether job starvation prevention is enabled.
    
    Specified by:
    
    setStarvationPreventionEnabled in interface GridPriorityQueueCollisionSpiMBean
    
    Parameters:
    preventStarvation - Flag indicating whether job starvation prevention is enabled.
  - getNodeAttributes
```
public Map<String,Object> getNodeAttributes()
                                     throws GridSpiException
```
    This method is called before SPI starts (before method GridSpi.spiStart(String) is called). It allows SPI implementation to add attributes to a local node. Kernal collects these attributes from all SPI implementations loaded up and then passes it to discovery SPI so that they can be exchanged with other nodes.
    
    Specified by:
    
    getNodeAttributes in interface GridSpi
    
    Overrides:
    
    getNodeAttributes in class GridSpiAdapter
    
    Returns:
    Map of local node attributes this SPI wants to add.
    
    Throws:
    
    GridSpiException - Throws in case of any error.
  - spiStart
```
public void spiStart(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
    
    Parameters:
    gridName - Name of grid instance this SPI is being started for (null for default grid).
    
    Throws:
    
    GridSpiException - Throws in case of any error during SPI start.
  - 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.
  - setExternalCollisionListener
```
public void setExternalCollisionListener(GridCollisionExternalListener 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.
    GridGain 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 GridComputeJobContext) 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 GridCollisionSpi
    
    Parameters:
    lsnr - Listener for external collision events.
  - onCollision
```
public void onCollision(GridCollisionContext 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 GridCollisionContext and GridCollisionJobContext documentation for more information.
    
    Specified by:
    
    onCollision in interface GridCollisionSpi
    
    Parameters:
    ctx - Collision context which contains all collision lists.
  - getConsistentAttributeNames
```
protected List<String> getConsistentAttributeNames()
```
    Returns back a list of attributes that should be consistent for this SPI. Consistency means that remote node has to have the same attribute with the same value.
    
    Overrides:
    
    getConsistentAttributeNames in class GridSpiAdapter
    
    Returns:
    List or attribute names.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class GridPriorityQueueCollisionSpi

Configuration

Mandatory

Optional

Coding Example

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

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

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

Field Detail

DFLT_PARALLEL_JOBS_NUM

DFLT_WAIT_JOBS_NUM

DFLT_PRIORITY_ATTRIBUTE_KEY

DFLT_JOB_PRIORITY_ATTRIBUTE_KEY

DFLT_PRIORITY

DFLT_STARVATION_INCREMENT

DFLT_PREVENT_STARVATION_ENABLED

Constructor Detail

GridPriorityQueueCollisionSpi

Method Detail

getParallelJobsNumber

setParallelJobsNumber

getWaitingJobsNumber

setWaitingJobsNumber

getCurrentWaitJobsNumber

getCurrentActiveJobsNumber

getCurrentRunningJobsNumber

getCurrentHeldJobsNumber

setPriorityAttributeKey

setJobPriorityAttributeKey

getPriorityAttributeKey

getJobPriorityAttributeKey

getDefaultPriority

setDefaultPriority

getStarvationIncrement

setStarvationIncrement

isStarvationPreventionEnabled

setStarvationPreventionEnabled

getNodeAttributes

spiStart

spiStop

setExternalCollisionListener

onCollision

getConsistentAttributeNames

toString