ThresholdBasedOracle (Apache Giraph Core 1.3.0-SNAPSHOT API)

java.lang.Object
- org.apache.giraph.ooc.policy.ThresholdBasedOracle

All Implemented Interfaces:

OutOfCoreOracle
```
public class ThresholdBasedOracle
extends Object
implements OutOfCoreOracle
```
Out-of-core oracle to adaptively control data kept in memory, with the goal of keeping the memory usage at a desired state. Out-of-core policy in this oracle is based on several user-defined thresholds. Also, this oracle spawns a thread to periodically check the memory usage. This thread would issue manual GC calls if JVM fails to call major/full GC for a while and the amount of used memory is about to cause high-memory pressure. This oracle, also, monitors GC activities. The monitoring mechanism looks for major/full GC calls, and updates out-of-core decisions based on the amount of available memory after such GCs. There are three out-of-core decisions: - Which IO operations should be done (load/offload of partitions and messages) - What the incoming messages rate should be (updating credits announced by this worker in credit-based flow-control mechanism) - How many processing threads should remain active (tethering rate of data generation) The following table shows the relationship of these decisions and used-defined thresholds. -------------------------------------------------------------- Memory Pressure | Manual | IO | Credit | Active | (memory usage) | GC? | Action | | Threads | -------------------------------------------------------------- | Yes | hard | 0 | 0 | | | store | | | failPressure ------------------------------------------------- | Yes | hard | 0 | fraction | | | store | | | emergencyPressure -------------------------------------------- | Yes | hard | fraction | max | | | store | | | highPressure ------------------------------------------------- | No | soft | fraction | max | | | store | | | optimalPressure ---------------------------------------------- | No | soft | max | max | | | load | | | lowPressure -------------------------------------------------- | No | hard | max | max | | | load | | | --------------------------------------------------------------

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.giraph.ooc.policy.OutOfCoreOracle
  OutOfCoreOracle.IOAction

Field Summary

Fields
Modifier and Type	Field and Description
`static LongConfOption`	`CHECK_MEMORY_INTERVAL` The interval at which memory observer thread wakes up.
`static FloatConfOption`	`EMERGENCY_MEMORY_PRESSURE` The memory pressure at which the job is cloe to fail, even though we were using maximal disk bandwidth and minimal network rate.
`static FloatConfOption`	`FAIL_MEMORY_PRESSURE` The memory pressure at/above which the job would fail
`static FloatConfOption`	`HIGH_MEMORY_PRESSURE` The memory pressure at which the job is suffering from GC overhead.
`static LongConfOption`	`LAST_GC_CALL_INTERVAL` Memory observer thread would manually call GC if major/full GC has not been called for a while.
`static FloatConfOption`	`LOW_MEMORY_PRESSURE` The memory pressure at/below which the job can use more memory without suffering from GC overhead.
`static FloatConfOption`	`OPTIMAL_MEMORY_PRESSURE` The memory pressure at which we expect GC to perform optimally for a memory intensive job.

Constructor Summary

Constructors
Constructor and Description

ThresholdBasedOracle(ImmutableClassesGiraphConfiguration conf, OutOfCoreEngine oocEngine)
Constructor

Constructors
Constructor and Description
`ThresholdBasedOracle(ImmutableClassesGiraphConfiguration conf, OutOfCoreEngine oocEngine)` Constructor

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`approve(IOCommand command)` Whether a command is appropriate to bring the memory to a more desired state.
`void`	`commandCompleted(IOCommand command)` Notification of command completion.
`void`	`gcCompleted(com.sun.management.GarbageCollectionNotificationInfo gcInfo)` Notification of GC completion.
`OutOfCoreOracle.IOAction[]`	`getNextIOActions()` Get the next set of viable IO actions to help bring memory to a more desired state.
`void`	`startIteration()` Called at the beginning of a superstep.
`void`	`updateRates(double usedMemoryFraction)` Update statistics and rate regarding communication credits and number of active threads.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - FAIL_MEMORY_PRESSURE
```
public static final FloatConfOption FAIL_MEMORY_PRESSURE
```
    The memory pressure at/above which the job would fail
  - EMERGENCY_MEMORY_PRESSURE
```
public static final FloatConfOption EMERGENCY_MEMORY_PRESSURE
```
    The memory pressure at which the job is cloe to fail, even though we were using maximal disk bandwidth and minimal network rate. We should reduce job processing rate.
  - HIGH_MEMORY_PRESSURE
```
public static final FloatConfOption HIGH_MEMORY_PRESSURE
```
    The memory pressure at which the job is suffering from GC overhead.
  - OPTIMAL_MEMORY_PRESSURE
```
public static final FloatConfOption OPTIMAL_MEMORY_PRESSURE
```
    The memory pressure at which we expect GC to perform optimally for a memory intensive job.
  - LOW_MEMORY_PRESSURE
```
public static final FloatConfOption LOW_MEMORY_PRESSURE
```
    The memory pressure at/below which the job can use more memory without suffering from GC overhead.
  - CHECK_MEMORY_INTERVAL
```
public static final LongConfOption CHECK_MEMORY_INTERVAL
```
    The interval at which memory observer thread wakes up.
  - LAST_GC_CALL_INTERVAL
```
public static final LongConfOption LAST_GC_CALL_INTERVAL
```
    Memory observer thread would manually call GC if major/full GC has not been called for a while. The period where we expect GC to be happened in past is specified in this parameter
- Constructor Detail
  - ThresholdBasedOracle
```
public ThresholdBasedOracle(ImmutableClassesGiraphConfiguration conf,
                            OutOfCoreEngine oocEngine)
```
    Constructor
    
    Parameters:
    
    conf - configuration
    
    oocEngine - out-of-core engine
- Method Detail
  - updateRates
```
public void updateRates(double usedMemoryFraction)
```
    Update statistics and rate regarding communication credits and number of active threads.
    
    Parameters:
    
    usedMemoryFraction - the fraction of used memory over max memory
  - getNextIOActions
```
public OutOfCoreOracle.IOAction[] getNextIOActions()
```
    Description copied from interface: OutOfCoreOracle
    
    Get the next set of viable IO actions to help bring memory to a more desired state.
    
    Specified by:
    
    getNextIOActions in interface OutOfCoreOracle
    
    Returns:
    
    an array of viable IO actions, sorted from highest priority to lowest priority
  - approve
```
public boolean approve(IOCommand command)
```
    Description copied from interface: OutOfCoreOracle
    
    Whether a command is appropriate to bring the memory to a more desired state. A command is not executed unless it is approved by the oracle. This method is specially important where there are multiple IO threads performing IO operations for the out-of-core mechanism. The approval becomes significantly important to prevent all IO threads from performing identical command type, if that is a necessity. For instance, execution of a particular command type by only one thread may bring the memory to a desired state, and the rest of IO threads may perform other types of commands.
    
    Specified by:
    
    approve in interface OutOfCoreOracle
    
    Parameters:
    
    command - the IO command that is about to execute
    
    Returns:
    
    'true' if the command is approved for execution. 'false' if the command should not be executed
  - commandCompleted
```
public void commandCompleted(IOCommand command)
```
    Description copied from interface: OutOfCoreOracle
    
    Notification of command completion. Oracle may update its status and commit the changes a command may cause.
    
    Specified by:
    
    commandCompleted in interface OutOfCoreOracle
    
    Parameters:
    
    command - the IO command that is completed
  - gcCompleted
```
public void gcCompleted(com.sun.management.GarbageCollectionNotificationInfo gcInfo)
```
    Description copied from interface: OutOfCoreOracle
    
    Notification of GC completion. Oracle may take certain decisions based on GC information (such as amount of time it took, memory it reclaimed, etc.)
    
    Specified by:
    
    gcCompleted in interface OutOfCoreOracle
    
    Parameters:
    
    gcInfo - GC information
  - startIteration
```
public void startIteration()
```
    Description copied from interface: OutOfCoreOracle
    
    Called at the beginning of a superstep.
    
    Specified by:
    
    startIteration in interface OutOfCoreOracle

Class ThresholdBasedOracle

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.giraph.ooc.policy.OutOfCoreOracle

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FAIL_MEMORY_PRESSURE

EMERGENCY_MEMORY_PRESSURE

HIGH_MEMORY_PRESSURE

OPTIMAL_MEMORY_PRESSURE

LOW_MEMORY_PRESSURE

CHECK_MEMORY_INTERVAL

LAST_GC_CALL_INTERVAL

Constructor Detail

ThresholdBasedOracle

Method Detail

updateRates

getNextIOActions

approve

commandCompleted

gcCompleted

startIteration