Phase (Jikes RVM API)

java.lang.Object
- org.mmtk.plan.Phase

Direct Known Subclasses:

ComplexPhase, ConcurrentPhase, SimplePhase
```
public abstract class Phase
extends Object
```
A garbage collection proceeds as a sequence of phases. Each phase is either simple (singular) or complex (an array).
The context an individual phase executes in may be global, mutator, or collector.
Phases are executed within a stack and all synchronization between parallel GC threads is managed from within this class.

See Also:

MutatorContext.collectionPhase(short, boolean)

Field Summary

Fields
Modifier and Type	Field and Description
`private static boolean`	`allowConcurrentPhase` Do we want to allow new concurrent workers to become active
`private static int[]`	`complexPhaseCursor` Stores the current sub phase for a complex phase.
`private static short`	`concurrentPhaseId` The concurrent phase being executed
`private static boolean`	`evenMutatorResetRendezvous` Do we need to add a sync point to reset the mutator count.
`private static int`	`evenScheduledPhase` The current even (0 mod 2) scheduled phase.
`protected short`	`id` The unique phase identifier.
`private static int`	`MAX_PHASE_STACK_DEPTH` The maximum stack depth for the phase stack.
`private static int`	`MAX_PHASES` The maximum number of phases
`protected String`	`name` The name of the phase.
`private static short`	`nextPhaseId` The id to be allocated for the next phase
`private static boolean`	`oddMutatorResetRendezvous` Do we need to add a sync point to reset the mutator count.
`private static int`	`oddScheduledPhase` The current odd (1 mod 2) scheduled phase.
`private static Phase[]`	`phases` The array of phase instances.
`private static int[]`	`phaseStack` The phase stack.
`private static int`	`phaseStackPointer` The current stack pointer
`protected static short`	`SCHEDULE_COLLECTOR` Run the phase on collectors.
`protected static short`	`SCHEDULE_COMPLEX` This is a complex phase.
`protected static short`	`SCHEDULE_CONCURRENT` Run this phase concurrently with the mutators
`protected static short`	`SCHEDULE_GLOBAL` Run the phase globally.
`protected static short`	`SCHEDULE_MUTATOR` Run the phase on mutators.
`protected static short`	`SCHEDULE_PLACEHOLDER` Don't run this phase.
`private static short`	`startComplexTimer` The complex phase whose timer should be started after the next rendezvous.
`private static short`	`stopComplexTimer` The complex phase whose timer should be stopped after the next rendezvous.
`protected Timer`	`timer` The Timer that is started and stopped around the execution of this phase.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Phase(String name)
Create a new Phase.

protected Phase(String name, Timer timer)
Create a new phase.

Constructors
Modifier	Constructor and Description
`protected`	`Phase(String name)` Create a new Phase.
`protected`	`Phase(String name, Timer timer)` Create a new phase.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`beginNewPhaseStack(int scheduledPhase)` Place a phase on the phase stack and begin processing.
`static void`	`clearConcurrentPhase()` Clear the current phase Id.
`static boolean`	`concurrentPhaseActive()`
`static void`	`continuePhaseStack()` Continue the execution of a phase stack.
`static short`	`createComplex(String name, int... scheduledPhases)` Constructs a complex phase.
`static short`	`createComplex(String name, Timer timer, int... scheduledPhases)` Constructs a complex phase, re-using a specified timer.
`static short`	`createConcurrent(String name, int atomicScheduledPhase)` Constructs a phase.
`static short`	`createConcurrent(String name, Timer timer, int atomicScheduledPhase)` Construct a phase, re-using a specified timer.
`static short`	`createSimple(String name)` Constructs a phase.
`static short`	`createSimple(String name, Timer timer)` Constructs a phase, re-using a specified timer.
`static short`	`getConcurrentPhaseId()`
`private static int`	`getCurrentPhase(boolean isEvenPhase)`
`short`	`getId()`
`static String`	`getName(short phaseId)`
`private static int`	`getNextPhase()` Pull the next scheduled phase off the stack.
`static Phase`	`getPhase(short id)` Retrieve a phase by the unique phase identifier.
`protected static short`	`getPhaseId(int scheduledPhase)`
`protected static short`	`getSchedule(int scheduledPhase)`
`protected static String`	`getScheduleName(short ordering)`
`private static int`	`incrementComplexPhaseCursor()` Increment the cursor associated with the current phase stack entry.
`static boolean`	`isPhaseStackEmpty()` Return true if phase stack is empty, false otherwise.
`protected abstract void`	`logPhase()` Display a description of this phase, for debugging purposes.
`private static boolean`	`needsMutatorResetRendezvous(boolean isEvenPhase)`
`static boolean`	`notifyConcurrentPhaseComplete()` Notify that the concurrent phase has completed successfully.
`static void`	`notifyConcurrentPhaseIncomplete()` Notify that the concurrent phase has not finished, and must be re-attempted.
`private static void`	`pauseComplexTimers()` Pause all of the timers for the complex phases sitting in the stack.
`private static int`	`peekScheduledPhase()` Peek the scheduled phase at the top of the work stack.
`private static int`	`popScheduledPhase()` Pop off the scheduled phase at the top of the work stack.
`private static void`	`processPhaseStack(boolean resume)` Processes the phase stack.
`static void`	`pushScheduledPhase(int scheduledPhase)` Push a scheduled phase onto the top of the work stack.
`static void`	`resetPhaseStack()` Clears the scheduled phase stack.
`private static void`	`resumeComplexTimers()` Resume all of the timers for the complex phases sitting in the stack.
`static int`	`scheduleCollector(short phaseId)` Take the passed phase and return an encoded phase to run that phase in a collector context;
`static int`	`scheduleComplex(short phaseId)` Take the passed phase and return an encoded phase to run that phase as a complex phase.
`static int`	`scheduleConcurrent(short phaseId)` Take the passed phase and return an encoded phase to run that phase as a concurrent phase.
`static int`	`scheduleGlobal(short phaseId)` Take the passed phase and return an encoded phase to run that phase in a global context;
`static int`	`scheduleMutator(short phaseId)` Take the passed phase and return an encoded phase to run that phase in a mutator context;
`static int`	`schedulePlaceholder(short phaseId)` Take the passed phase and return an encoded phase to run that phase in a mutator context;
`private static void`	`setNextPhase(boolean isEvenPhase, int scheduledPhase, boolean needsResetRendezvous)` Sets the next phase.

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

- Field Detail
  - MAX_PHASES
```
private static final int MAX_PHASES
```
    The maximum number of phases
    
    See Also:
    
    Constant Field Values
  - phases
```
private static final Phase[] phases
```
    The array of phase instances. Zero is unused.
  - nextPhaseId
```
private static short nextPhaseId
```
    The id to be allocated for the next phase
  - SCHEDULE_GLOBAL
```
protected static final short SCHEDULE_GLOBAL
```
    Run the phase globally.
    
    See Also:
    
    Constant Field Values
  - SCHEDULE_COLLECTOR
```
protected static final short SCHEDULE_COLLECTOR
```
    Run the phase on collectors.
    
    See Also:
    
    Constant Field Values
  - SCHEDULE_MUTATOR
```
protected static final short SCHEDULE_MUTATOR
```
    Run the phase on mutators.
    
    See Also:
    
    Constant Field Values
  - SCHEDULE_CONCURRENT
```
protected static final short SCHEDULE_CONCURRENT
```
    Run this phase concurrently with the mutators
    
    See Also:
    
    Constant Field Values
  - SCHEDULE_PLACEHOLDER
```
protected static final short SCHEDULE_PLACEHOLDER
```
    Don't run this phase.
    
    See Also:
    
    Constant Field Values
  - SCHEDULE_COMPLEX
```
protected static final short SCHEDULE_COMPLEX
```
    This is a complex phase.
    
    See Also:
    
    Constant Field Values
  - id
```
protected final short id
```
    The unique phase identifier.
  - name
```
protected final String name
```
    The name of the phase.
  - timer
```
protected final Timer timer
```
    The Timer that is started and stopped around the execution of this phase.
  - MAX_PHASE_STACK_DEPTH
```
private static final int MAX_PHASE_STACK_DEPTH
```
    The maximum stack depth for the phase stack.
    
    See Also:
    
    Constant Field Values
  - complexPhaseCursor
```
private static int[] complexPhaseCursor
```
    Stores the current sub phase for a complex phase. Each entry corresponds to a phase stack entry
  - phaseStack
```
private static int[] phaseStack
```
    The phase stack. Stores the current nesting of phases
  - phaseStackPointer
```
private static int phaseStackPointer
```
    The current stack pointer
  - evenScheduledPhase
```
private static int evenScheduledPhase
```
    The current even (0 mod 2) scheduled phase. As we only sync at the end of a phase we need this to ensure that the primary thread setting the phase does not race with the other threads reading it.
  - oddScheduledPhase
```
private static int oddScheduledPhase
```
    The current odd (1 mod 2) scheduled phase. As we only sync at the end of a phase we need this to ensure that the primary thread setting the phase does not race with the other threads reading it.
  - evenMutatorResetRendezvous
```
private static boolean evenMutatorResetRendezvous
```
    Do we need to add a sync point to reset the mutator count. This is necessary for consecutive mutator phases and unnecessary otherwise. Again we separate in even and odd to ensure that there is no race between the primary thread setting and the helper threads reading.
  - oddMutatorResetRendezvous
```
private static boolean oddMutatorResetRendezvous
```
    Do we need to add a sync point to reset the mutator count. This is necessary for consecutive mutator phases and unnecessary otherwise. Again we separate in even and odd to ensure that there is no race between the primary thread setting and the helper threads reading.
  - startComplexTimer
```
private static short startComplexTimer
```
    The complex phase whose timer should be started after the next rendezvous. We can not start the timer at the point we determine the next complex phase as we determine the next phase at the end of the previous phase before the sync point.
  - stopComplexTimer
```
private static short stopComplexTimer
```
    The complex phase whose timer should be stopped after the next rendezvous. We can not start the timer at the point we determine the next complex phase as we determine the next phase at the end of the previous phase before the sync point.
  - concurrentPhaseId
```
private static short concurrentPhaseId
```
    The concurrent phase being executed
  - allowConcurrentPhase
```
private static boolean allowConcurrentPhase
```
    Do we want to allow new concurrent workers to become active
- Constructor Detail
  - Phase
```
protected Phase(String name)
```
    Create a new Phase. This involves creating a corresponding Timer instance, allocating a unique identifier, and registering the Phase.
    
    Parameters:
    
    name - The name for the phase.
  - Phase
```
protected Phase(String name,
                Timer timer)
```
    Create a new phase. This involves setting the corresponding Timer instance, allocating a unique identifier, and registering the Phase.
    
    Parameters:
    
    name - The name of the phase.
    
    timer - The timer, or null if this is an untimed phase.
- Method Detail
  - getPhase
```
public static Phase getPhase(short id)
```
    Retrieve a phase by the unique phase identifier.
    
    Parameters:
    
    id - The phase identifier.
    
    Returns:
    
    The Phase instance.
  - getPhaseId
```
protected static short getPhaseId(int scheduledPhase)
```
    Parameters:
    
    scheduledPhase - an encoded phase
    
    Returns:
    
    the phase id component of an encoded phase
  - getName
```
public static String getName(short phaseId)
```
    Parameters:
    
    phaseId - The unique phase identifier.
    
    Returns:
    
    The name of the phase.
  - getSchedule
```
protected static short getSchedule(int scheduledPhase)
```
    Parameters:
    
    scheduledPhase - an encoded phase
    
    Returns:
    
    the ordering component of an encoded phase
  - getScheduleName
```
protected static String getScheduleName(short ordering)
```
    Parameters:
    
    ordering - the ordering component of a phase
    
    Returns:
    
    human-readable name for the schedule
  - createSimple
```
public static short createSimple(String name)
```
    Constructs a phase.
    
    Parameters:
    
    name - Display name of the phase
    
    Returns:
    
    the id of the simple phase
  - createSimple
```
public static short createSimple(String name,
                                 Timer timer)
```
    Constructs a phase, re-using a specified timer.
    
    Parameters:
    
    name - Display name of the phase
    
    timer - the time to re-use
    
    Returns:
    
    the id of the simple phase
  - createComplex
```
public static short createComplex(String name,
                                  int... scheduledPhases)
```
    Constructs a complex phase.
    
    Parameters:
    
    name - Display name of the phase
    
    scheduledPhases - The phases in this complex phase.
    
    Returns:
    
    the phase's id
  - createComplex
```
public static short createComplex(String name,
                                  Timer timer,
                                  int... scheduledPhases)
```
    Constructs a complex phase, re-using a specified timer.
    
    Parameters:
    
    name - Display name of the phase
    
    timer - Timer for this phase to contribute to
    
    scheduledPhases - The phases in this complex phase.
    
    Returns:
    
    the phase's id
  - createConcurrent
```
public static final short createConcurrent(String name,
                                           int atomicScheduledPhase)
```
    Constructs a phase.
    
    Parameters:
    
    name - Display name of the phase
    
    atomicScheduledPhase - The corresponding atomic phase to run in a stop the world collection
    
    Returns:
    
    the phase's id
  - createConcurrent
```
public static final short createConcurrent(String name,
                                           Timer timer,
                                           int atomicScheduledPhase)
```
    Construct a phase, re-using a specified timer.
    
    Parameters:
    
    name - Display name of the phase
    
    timer - Timer for this phase to contribute to
    
    atomicScheduledPhase - The corresponding atomic phase to run in a stop the world collection
    
    Returns:
    
    the phase's id
  - scheduleComplex
```
public static int scheduleComplex(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase as a complex phase.
    
    Parameters:
    
    phaseId - The phase to run as complex
    
    Returns:
    
    The encoded phase value.
  - scheduleConcurrent
```
public static int scheduleConcurrent(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase as a concurrent phase.
    
    Parameters:
    
    phaseId - The phase to run as concurrent
    
    Returns:
    
    The encoded phase value.
  - scheduleGlobal
```
public static int scheduleGlobal(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase in a global context;
    
    Parameters:
    
    phaseId - The phase to run globally
    
    Returns:
    
    The encoded phase value.
  - scheduleCollector
```
public static int scheduleCollector(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase in a collector context;
    
    Parameters:
    
    phaseId - The phase to run on collectors
    
    Returns:
    
    The encoded phase value.
  - scheduleMutator
```
public static int scheduleMutator(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase in a mutator context;
    
    Parameters:
    
    phaseId - The phase to run on mutators
    
    Returns:
    
    The encoded phase value.
  - schedulePlaceholder
```
public static int schedulePlaceholder(short phaseId)
```
    Take the passed phase and return an encoded phase to run that phase in a mutator context;
    
    Parameters:
    
    phaseId - The phase to run on mutators
    
    Returns:
    
    The encoded phase value.
  - getId
```
public final short getId()
```
    Returns:
    
    The unique identifier for this phase.
  - logPhase
```
protected abstract void logPhase()
```
    Display a description of this phase, for debugging purposes.
  - beginNewPhaseStack
```
public static void beginNewPhaseStack(int scheduledPhase)
```
    Place a phase on the phase stack and begin processing.
    
    Parameters:
    
    scheduledPhase - The phase to execute
  - continuePhaseStack
```
public static void continuePhaseStack()
```
    Continue the execution of a phase stack. Used for incremental and concurrent collection.
  - processPhaseStack
```
private static void processPhaseStack(boolean resume)
```
    Processes the phase stack. This method is called by multiple threads.
    
    Parameters:
    
    resume - whether to resume garbage collection. If set to true, GC status will be set to Plan.GC_PROPER when the first phase is processed.
  - getCurrentPhase
```
private static int getCurrentPhase(boolean isEvenPhase)
```
    Parameters:
    
    isEvenPhase - whether an even or odd phase will be returned
    
    Returns:
    
    the next phase
  - needsMutatorResetRendezvous
```
private static boolean needsMutatorResetRendezvous(boolean isEvenPhase)
```
    Parameters:
    
    isEvenPhase - whether the phase is even or odd
    
    Returns:
    
    whether we need a mutator reset rendezvous in this phase
  - setNextPhase
```
private static void setNextPhase(boolean isEvenPhase,
                                 int scheduledPhase,
                                 boolean needsResetRendezvous)
```
    Sets the next phase. If we are in an even phase the next phase is odd.
    
    Parameters:
    
    isEvenPhase - whether the phase is even
    
    scheduledPhase - the scheduled phase
    
    needsResetRendezvous - whether it's necessary to rendezvous. This is only necessary for consecutive mutator phases.
  - getNextPhase
```
private static int getNextPhase()
```
    Pull the next scheduled phase off the stack. This may involve processing several complex phases and skipping placeholders, etc.
    
    Returns:
    
    The next phase to run, or -1 if no phases are left.
  - pauseComplexTimers
```
private static void pauseComplexTimers()
```
    Pause all of the timers for the complex phases sitting in the stack.
  - resumeComplexTimers
```
private static void resumeComplexTimers()
```
    Resume all of the timers for the complex phases sitting in the stack.
  - isPhaseStackEmpty
```
public static boolean isPhaseStackEmpty()
```
    Return true if phase stack is empty, false otherwise.
    
    Returns:
    
    true if phase stack is empty, false otherwise.
  - resetPhaseStack
```
public static void resetPhaseStack()
```
    Clears the scheduled phase stack.
  - pushScheduledPhase
```
public static void pushScheduledPhase(int scheduledPhase)
```
    Push a scheduled phase onto the top of the work stack.
    
    Parameters:
    
    scheduledPhase - The scheduled phase.
  - incrementComplexPhaseCursor
```
private static int incrementComplexPhaseCursor()
```
    Increment the cursor associated with the current phase stack entry. This is used to remember the current sub phase when executing a complex phase.
    
    Returns:
    
    The old value of the cursor.
  - popScheduledPhase
```
private static int popScheduledPhase()
```
    Pop off the scheduled phase at the top of the work stack.
    
    Returns:
    
    the scheduled phase at the top of the work stack
  - peekScheduledPhase
```
private static int peekScheduledPhase()
```
    Peek the scheduled phase at the top of the work stack.
    
    Returns:
    
    the scheduled phase at the top of the work stack
  - getConcurrentPhaseId
```
public static short getConcurrentPhaseId()
```
    Returns:
    
    the current phase Id.
  - clearConcurrentPhase
```
public static void clearConcurrentPhase()
```
    Clear the current phase Id.
  - concurrentPhaseActive
```
public static boolean concurrentPhaseActive()
```
    Returns:
    
    trueif there is an active concurrent phase.
  - notifyConcurrentPhaseComplete
```
public static boolean notifyConcurrentPhaseComplete()
```
    Notify that the concurrent phase has completed successfully. This must only be called by a single thread after it has determined that the phase has been completed successfully.
    
    Returns:
    
    true if more concurrent work needs to be done right now, false otherwise
  - notifyConcurrentPhaseIncomplete
```
public static void notifyConcurrentPhaseIncomplete()
```
    Notify that the concurrent phase has not finished, and must be re-attempted.

Class Phase

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_PHASES

phases

nextPhaseId

SCHEDULE_GLOBAL

SCHEDULE_COLLECTOR

SCHEDULE_MUTATOR

SCHEDULE_CONCURRENT

SCHEDULE_PLACEHOLDER

SCHEDULE_COMPLEX

id

name

timer

MAX_PHASE_STACK_DEPTH

complexPhaseCursor

phaseStack

phaseStackPointer

evenScheduledPhase

oddScheduledPhase

evenMutatorResetRendezvous

oddMutatorResetRendezvous

startComplexTimer

stopComplexTimer

concurrentPhaseId

allowConcurrentPhase

Constructor Detail

Phase

Phase

Method Detail

getPhase

getPhaseId

getName

getSchedule

getScheduleName

createSimple

createSimple

createComplex

createComplex

createConcurrent

createConcurrent

scheduleComplex

scheduleConcurrent

scheduleGlobal

scheduleCollector

scheduleMutator

schedulePlaceholder

getId

logPhase

beginNewPhaseStack

continuePhaseStack

processPhaseStack

getCurrentPhase

needsMutatorResetRendezvous

setNextPhase

getNextPhase

pauseComplexTimers

resumeComplexTimers

isPhaseStackEmpty

resetPhaseStack

pushScheduledPhase

incrementComplexPhaseCursor

popScheduledPhase

peekScheduledPhase

getConcurrentPhaseId

clearConcurrentPhase

concurrentPhaseActive

notifyConcurrentPhaseComplete

notifyConcurrentPhaseIncomplete