Package org.apache.hadoop.hbase.procedure2

Class StateMachineProcedure<TEnvironment,TState>

java.lang.Object
org.apache.hadoop.hbase.procedure2.Procedure<TEnvironment>
org.apache.hadoop.hbase.procedure2.StateMachineProcedure<TEnvironment,TState>
All Implemented Interfaces:
Comparable<Procedure<TEnvironment>>
Direct Known Subclasses:
AbstractPeerProcedure, AbstractStateMachineNamespaceProcedure, AbstractStateMachineTableProcedure, RecoverMetaProcedure, ServerCrashProcedure, SplitWALProcedure, SwitchRpcThrottleProcedure
@Private @Evolving public abstract class StateMachineProcedure<TEnvironment,TState> extends Procedure<TEnvironment>
Procedure described by a series of steps.

The procedure implementor must have an enum of 'states', describing the various step of the procedure. Once the procedure is running, the procedure-framework will call executeFromState() using the 'state' provided by the user. The first call to executeFromState() will be performed with 'state = null'. The implementor can jump between states using setNextState(MyStateEnum.ordinal()). The rollback will call rollbackState() for each state that was executed, in reverse order.

  • Field Details

  • Constructor Details

  • Method Details

    • getCycles

      protected final int getCycles()

    • executeFromState

      protected abstract StateMachineProcedure.Flow executeFromState(TEnvironment env, TState state) throws ProcedureSuspendedException, ProcedureYieldException, InterruptedException
      called to perform a single step of the specified 'state' of the procedure
      Parameters:
      state - state to execute
      Returns:
      Flow.NO_MORE_STATE if the procedure is completed, Flow.HAS_MORE_STATE if there is another step.
      Throws:
      ProcedureSuspendedException
      ProcedureYieldException
      InterruptedException

    • rollbackState

      protected abstract void rollbackState(TEnvironment env, TState state) throws IOException, InterruptedException
      called to perform the rollback of the specified state
      Parameters:
      state - state to rollback
      Throws:
      IOException - temporary failure, the rollback will retry later
      InterruptedException

    • getState

      protected abstract TState getState(int stateId)
      Convert an ordinal (or state id) to an Enum (or more descriptive) state object.
      Parameters:
      stateId - the ordinal() of the state enum (or state id)
      Returns:
      the state enum object

    • getStateId

      protected abstract int getStateId(TState state)
      Convert the Enum (or more descriptive) state object to an ordinal (or state id).
      Parameters:
      state - the state enum object
      Returns:
      stateId the ordinal() of the state enum (or state id)

    • getInitialState

      protected abstract TState getInitialState()
      Return the initial state object that will be used for the first call to executeFromState().
      Returns:
      the initial state enum object

    • setNextState

      protected void setNextState(TState state)
      Set the next state for the procedure.
      Parameters:
      state - the state enum object

    • isYieldBeforeExecuteFromState

      protected boolean isYieldBeforeExecuteFromState(TEnvironment env, TState state)
      By default, the executor will try ro run all the steps of the procedure start to finish. Return true to make the executor yield between execution steps to give other procedures time to run their steps.
      Parameters:
      state - the state we are going to execute next.
      Returns:
      Return true if the executor should yield before the execution of the specified step. Defaults to return false.

    • addChildProcedure

      protected <T extends Procedure<TEnvironment>> void addChildProcedure(T... subProcedure)
      Add a child procedure to execute
      Parameters:
      subProcedure - the child procedure

    • execute

      protected Procedure[] execute(TEnvironment env) throws ProcedureSuspendedException, ProcedureYieldException, InterruptedException
      Description copied from class: Procedure
      The main code of the procedure. It must be idempotent since execute() may be called multiple times in case of machine failure in the middle of the execution.
      Specified by:
      execute in class Procedure<TEnvironment>
      Parameters:
      env - the environment passed to the ProcedureExecutor
      Returns:
      a set of sub-procedures to run or ourselves if there is more work to do or null if the procedure is done.
      Throws:
      ProcedureSuspendedException - Signal to the executor that Procedure has suspended itself and has set itself up waiting for an external event to wake it back up again.
      ProcedureYieldException - the procedure will be added back to the queue and retried later.
      InterruptedException - the procedure will be added back to the queue and retried later.

    • rollback

      protected void rollback(TEnvironment env) throws IOException, InterruptedException
      Description copied from class: Procedure
      The code to undo what was done by the execute() code. It is called when the procedure or one of the sub-procedures failed or an abort was requested. It should cleanup all the resources created by the execute() call. The implementation must be idempotent since rollback() may be called multiple time in case of machine failure in the middle of the execution.
      Specified by:
      rollback in class Procedure<TEnvironment>
      Parameters:
      env - the environment passed to the ProcedureExecutor
      Throws:
      IOException - temporary failure, the rollback will retry later
      InterruptedException - the procedure will be added back to the queue and retried later

    • isEofState

      protected boolean isEofState()

    • abort

      protected boolean abort(TEnvironment env)
      Description copied from class: Procedure
      The abort() call is asynchronous and each procedure must decide how to deal with it, if they want to be abortable. The simplest implementation is to have an AtomicBoolean set in the abort() method and then the execute() will check if the abort flag is set or not. abort() may be called multiple times from the client, so the implementation must be idempotent.

      NOTE: abort() is not like Thread.interrupt(). It is just a notification that allows the procedure implementor abort.

      Specified by:
      abort in class Procedure<TEnvironment>

    • failIfAborted

      protected final void failIfAborted()
      If procedure has more states then abort it otherwise procedure is finished and abort can be ignored.

    • isRollbackSupported

      protected final boolean isRollbackSupported()
      Description copied from class: Procedure
      Return whether the procedure supports rollback. If the procedure does not support rollback, we can skip the rollback state management which could increase the performance. See HBASE-28210 and HBASE-28212.
      Overrides:
      isRollbackSupported in class Procedure<TEnvironment>

    • isRollbackSupported

      protected boolean isRollbackSupported(TState state)
      Used by the default implementation of abort() to know if the current state can be aborted and rollback can be triggered.

    • isYieldAfterExecutionStep

      protected boolean isYieldAfterExecutionStep(TEnvironment env)
      Description copied from class: Procedure
      By default, the procedure framework/executor will try to run procedures start to finish. Return true to make the executor yield between each execution step to give other procedures a chance to run.
      Overrides:
      isYieldAfterExecutionStep in class Procedure<TEnvironment>
      Parameters:
      env - the environment passed to the ProcedureExecutor
      Returns:
      Return true if the executor should yield on completion of an execution step. Defaults to return false.

    • hasMoreState

      private boolean hasMoreState()

    • getCurrentState

      protected TState getCurrentState()

    • getCurrentStateId

      public int getCurrentStateId()
      This method is used from test code as it cannot be assumed that state transition will happen sequentially. Some procedures may skip steps/ states, some may add intermediate steps in future.

    • setNextState

      private void setNextState(int stateId)
      Set the next state for the procedure.
      Parameters:
      stateId - the ordinal() of the state enum (or state id)

    • toStringState

      protected void toStringState(StringBuilder builder)
      Description copied from class: Procedure
      Called from Procedure.toString() when interpolating Procedure State. Allows decorating generic Procedure State with Procedure particulars.
      Overrides:
      toStringState in class Procedure<TEnvironment>
      Parameters:
      builder - Append current ProcedureProtos.ProcedureState

    • serializeStateData

      protected void serializeStateData(ProcedureStateSerializer serializer) throws IOException
      Description copied from class: Procedure
      The user-level code of the procedure may have some state to persist (e.g. input arguments or current position in the processing state) to be able to resume on failure.
      Specified by:
      serializeStateData in class Procedure<TEnvironment>
      Parameters:
      serializer - stores the serializable state
      Throws:
      IOException

    • deserializeStateData

      protected void deserializeStateData(ProcedureStateSerializer serializer) throws IOException
      Description copied from class: Procedure
      Called on store load to allow the user to decode the previously serialized state.
      Specified by:
      deserializeStateData in class Procedure<TEnvironment>
      Parameters:
      serializer - contains the serialized state
      Throws:
      IOException