Package org.opendaylight.controller.cluster.raft

Class RaftActor

java.lang.Object
org.apache.pekko.actor.AbstractActor
org.apache.pekko.persistence.AbstractPersistentActor
org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor
org.opendaylight.controller.cluster.raft.RaftActor
All Implemented Interfaces:
org.apache.pekko.actor.Actor, org.apache.pekko.actor.Stash, org.apache.pekko.actor.StashFactory, org.apache.pekko.actor.StashSupport, org.apache.pekko.actor.UnrestrictedStash, org.apache.pekko.dispatch.RequiresMessageQueue<org.apache.pekko.dispatch.DequeBasedMessageQueueSemantics>, org.apache.pekko.persistence.AbstractPersistentActorLike, org.apache.pekko.persistence.Eventsourced, org.apache.pekko.persistence.PersistenceIdentity, org.apache.pekko.persistence.PersistenceRecovery, org.apache.pekko.persistence.PersistenceStash, org.apache.pekko.persistence.Snapshotter, ExecuteInSelfActor
Direct Known Subclasses:
Shard
public abstract class RaftActor extends AbstractUntypedPersistentActor
RaftActor encapsulates a state machine that needs to be kept synchronized in a cluster. It implements the RAFT algorithm as described in the paper In Search of an Understandable Consensus Algorithm

RaftActor has 3 states and each state has a certain behavior associated with it. A Raft actor can behave as,

  • A Leader
  • A Follower (or)
  • A Candidate

A RaftActor MUST be a Leader in order to accept requests from clients to change the state of it's encapsulated state machine. Once a RaftActor becomes a Leader it is also responsible for ensuring that all followers ultimately have the same log and therefore the same state machine as itself.

The current behavior of a RaftActor determines how election for leadership is initiated and how peer RaftActors react to request for votes.

Each RaftActor also needs to know the current election term. It uses this information for a couple of things. One is to simply figure out who it voted for in the last election. Another is to figure out if the message it received to update it's state is stale.

The RaftActor uses akka-persistence to store it's replicated log. Furthermore through it's behaviors a Raft Actor determines

  • when a log entry should be persisted
  • when a log entry should be applied to the state machine (and)
  • when a snapshot should be saved

  • Nested Class Summary

    Nested classes/interfaces inherited from class org.apache.pekko.actor.AbstractActor

    org.apache.pekko.actor.AbstractActor.ActorContext, org.apache.pekko.actor.AbstractActor.Receive

    Nested classes/interfaces inherited from interface org.apache.pekko.actor.Actor

    org.apache.pekko.actor.Actor.emptyBehavior$, org.apache.pekko.actor.Actor.ignoringBehavior$

    Nested classes/interfaces inherited from interface org.apache.pekko.persistence.Eventsourced

    org.apache.pekko.persistence.Eventsourced.AsyncHandlerInvocation, org.apache.pekko.persistence.Eventsourced.AsyncHandlerInvocation$, org.apache.pekko.persistence.Eventsourced.PendingHandlerInvocation, org.apache.pekko.persistence.Eventsourced.RecoveryTick, org.apache.pekko.persistence.Eventsourced.RecoveryTick$, org.apache.pekko.persistence.Eventsourced.StashingHandlerInvocation, org.apache.pekko.persistence.Eventsourced.StashingHandlerInvocation$

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    RaftActor(Path stateDir, String memberId, Map<String,String> peerAddresses, Optional<ConfigParams> configParams, short payloadVersion)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    applyCommand(@Nullable Identifier identifier, StateCommand command)
    Apply a StateCommand to update the actor's state.
    final void
    deleteSnapshot(long sequenceNr)
    Deprecated, for removal: This API element is subject to removal in a future version.
    final void
    deleteSnapshots(org.apache.pekko.persistence.SnapshotSelectionCriteria criteria)
    Deprecated, for removal: This API element is subject to removal in a future version.
    protected final RaftActorBehavior
    getCurrentBehavior()
     
    protected final @Nullable org.apache.pekko.actor.ActorSelection
    getLeader()
    Derived actor can call getLeader if they need a reference to the Leader.
    protected final String
    getLeaderId()
    Returns the id of the current leader.
    final RaftActorContext
    getRaftActorContext()
     
    protected abstract @NonNull RaftActorRecoveryCohort
    getRaftActorRecoveryCohort()
    Returns the RaftActorRecoveryCohort to participate in persistence recovery.
    protected abstract @NonNull RaftActorSnapshotCohort<?>
    getRaftActorSnapshotCohort()
    Returns the RaftActorSnapshotCohort to participate in snapshot captures.
    protected final RaftRole
    getRaftState()
     
    final org.apache.pekko.actor.ActorRef
    getSender()
    Deprecated, for removal: This API element is subject to removal in a future version.
    protected final void
    handleCommand(Object message)
     
    protected void
    handleCommandImpl(@NonNull Object message)
    Deprecated.
    This method is not final for testing purposes.
    protected void
    handleNonRaftCommand(Object message)
    Method exposed for subclasses to plug-in their logic.
    protected void
    handleRecover(Object message)
     
    protected boolean
    isLeader()
    Derived actors can call the isLeader method to check if the current RaftActor is the Leader or not.
    protected final boolean
    isLeaderActive()
     
    protected boolean
    isLeadershipTransferInProgress()
     
    final boolean
    isRecoveryApplicable()
     
    final void
    loadSnapshot(String persistenceId, org.apache.pekko.persistence.SnapshotSelectionCriteria criteria, long toSequenceNr)
    Deprecated, for removal: This API element is subject to removal in a future version.
    final @NonNull String
    memberId()
    Return the unique member name of this actor.
    protected @NonNull OnDemandRaftState.AbstractBuilder<?,?>
    newOnDemandRaftStateBuilder()
     
    protected void
    onLeaderChanged(String oldLeader, String newLeader)
     
    protected abstract void
    onRecoveryComplete()
    This method is called when recovery is complete.
    protected abstract void
    onStateChanged()
    This method will be called by the RaftActor when the state of the RaftActor changes.
    protected void
    onVotingStateChangeComplete()
    This method is called on the leader when a voting change operation completes.
    protected ReplicatedLog
    overridePekkoRecoveredLog(ReplicatedLog recoveredLog)
     
    protected void
    pauseLeader(Runnable operation)
    This method is called prior to operations such as leadership transfer and actor shutdown when the leader must pause or stop its duties.
    final <A> void
    persist(A entry, org.apache.pekko.japi.Procedure<A> callback)
    Deprecated, for removal: This API element is subject to removal in a future version.
    final <A> void
    persistAsync(A entry, org.apache.pekko.japi.Procedure<A> callback)
    Deprecated, for removal: This API element is subject to removal in a future version.
    protected final PersistenceProvider
    persistence()
     
    void
    postStop()
     
    void
    preStart()
     
    protected abstract @Nullable org.apache.pekko.actor.ActorRef
    roleChangeNotifier()
    Notifier Actor for this RaftActor to notify when a role change happens.
    final void
    saveSnapshot(Object snapshot)
    Deprecated, for removal: This API element is subject to removal in a future version.
    protected void
    setPeerAddress(String peerId, String peerAddress)
    setPeerAddress sets the address of a known peer at a later time.
    protected final void
    setPersistence(boolean persistent)
     
    final void
    submitCommand(Identifier identifier, AbstractStateCommand command, boolean batchHint)
    Request a StateCommand to be applied to the finite state machine.
    protected void
    unpauseLeader()
    This method is invoked when the actions hooked to the leader becoming paused failed to execute and the leader should resume normal operations.
    protected void
    updateConfigParams(ConfigParams configParams)
     
    protected LeaderStateChanged
    wrapLeaderStateChanged(LeaderStateChanged change)
     

    Methods inherited from class org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor

    createReceive, createReceiveRecover, executeInSelf, getContext, ignoreMessage, persistenceId, unknownMessage

    Methods inherited from class org.apache.pekko.persistence.AbstractPersistentActor

    aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, clearStash, createStash, defer, deferAsync, deleteMessages, internalDefer, internalDeferAsync, internalDeleteMessagesBeforeSnapshot, internalPersist, internalPersistAll, internalPersistAllAsync, internalPersistAsync, internalStashOverflowStrategy, journal, journalPluginId, lastSequenceNr, mailbox, onPersistFailure, onPersistRejected, onRecoveryFailure, onReplaySuccess, org$apache$pekko$actor$StashSupport$_setter_$mailbox_$eq, org$apache$pekko$actor$StashSupport$_setter_$org$apache$pekko$actor$StashSupport$$capacity_$eq, org$apache$pekko$actor$StashSupport$$capacity, org$apache$pekko$actor$StashSupport$$theStash, org$apache$pekko$actor$StashSupport$$theStash_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$extension_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$instanceId_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$internalStash_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$maxMessageBatchSize_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$pendingInvocations_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$persistingEvents_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$processingCommands_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$unstashFilterPredicate_$eq, org$apache$pekko$persistence$Eventsourced$_setter_$org$apache$pekko$persistence$Eventsourced$$writerUuid_$eq, org$apache$pekko$persistence$Eventsourced$$_lastSequenceNr, org$apache$pekko$persistence$Eventsourced$$_lastSequenceNr_$eq, org$apache$pekko$persistence$Eventsourced$$currentState, org$apache$pekko$persistence$Eventsourced$$currentState_$eq, org$apache$pekko$persistence$Eventsourced$$eventBatch, org$apache$pekko$persistence$Eventsourced$$eventBatch_$eq, org$apache$pekko$persistence$Eventsourced$$extension, org$apache$pekko$persistence$Eventsourced$$instanceId, org$apache$pekko$persistence$Eventsourced$$internalStash, org$apache$pekko$persistence$Eventsourced$$journalBatch, org$apache$pekko$persistence$Eventsourced$$journalBatch_$eq, org$apache$pekko$persistence$Eventsourced$$maxMessageBatchSize, org$apache$pekko$persistence$Eventsourced$$pendingInvocations, org$apache$pekko$persistence$Eventsourced$$pendingStashingPersistInvocations, org$apache$pekko$persistence$Eventsourced$$pendingStashingPersistInvocations_$eq, org$apache$pekko$persistence$Eventsourced$$persistingEvents, org$apache$pekko$persistence$Eventsourced$$processingCommands, org$apache$pekko$persistence$Eventsourced$$sequenceNr, org$apache$pekko$persistence$Eventsourced$$sequenceNr_$eq, org$apache$pekko$persistence$Eventsourced$$unstashFilterPredicate, org$apache$pekko$persistence$Eventsourced$$writeInProgress, org$apache$pekko$persistence$Eventsourced$$writeInProgress_$eq, org$apache$pekko$persistence$Eventsourced$$writerUuid, persistAll, persistAllAsync, prepend, preRestart, receiveCommand, receiveRecover, recovery, recoveryFinished, recoveryRunning, snapshotPluginId, snapshotSequenceNr, snapshotStore, snapshotterId, stash, unhandled, unstash, unstashAll, unstashAll

    Methods inherited from class org.apache.pekko.actor.AbstractActor

    context, emptyBehavior, getSelf, org$apache$pekko$actor$Actor$_setter_$context_$eq, org$apache$pekko$actor$Actor$_setter_$self_$eq, postRestart, preRestart, receive, receiveBuilder, self, sender, supervisorStrategy

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.apache.pekko.actor.Actor

    context, org$apache$pekko$actor$Actor$_setter_$context_$eq, org$apache$pekko$actor$Actor$_setter_$self_$eq, postRestart, receive, self, sender, supervisorStrategy

    Methods inherited from interface org.apache.pekko.persistence.Eventsourced

    org$apache$pekko$persistence$Eventsourced$$changeState, org$apache$pekko$persistence$Eventsourced$$flushBatch, org$apache$pekko$persistence$Eventsourced$$flushJournalBatch, org$apache$pekko$persistence$Eventsourced$$log, org$apache$pekko$persistence$Eventsourced$$peekApplyHandler, org$apache$pekko$persistence$Eventsourced$$recovering, org$apache$pekko$persistence$Eventsourced$$setLastSequenceNr, org$apache$pekko$persistence$Eventsourced$$startRecovery, org$apache$pekko$persistence$Eventsourced$$stashInternally, org$apache$pekko$persistence$Eventsourced$$unstashInternally, org$apache$pekko$persistence$Eventsourced$$updateLastSequenceNr, org$apache$pekko$persistence$Eventsourced$$writeEventFailed, org$apache$pekko$persistence$Eventsourced$$writeEventRejected, org$apache$pekko$persistence$Eventsourced$$writeEventSucceeded

    Methods inherited from interface org.apache.pekko.actor.StashSupport

    context, self

  • Constructor Details

  • Method Details

    • memberId

      public final @NonNull String memberId()
      Return the unique member name of this actor.
      Returns:
      The member name

    • getSender

      @Deprecated(since="11.0.0", forRemoval=true) public final org.apache.pekko.actor.ActorRef getSender()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Overrides:
      getSender in class org.apache.pekko.actor.AbstractActor

    • preStart

      public void preStart() throws Exception
      Specified by:
      preStart in interface org.apache.pekko.actor.Actor
      Overrides:
      preStart in class org.apache.pekko.actor.AbstractActor
      Throws:
      Exception

    • postStop

      public void postStop() throws Exception
      Specified by:
      postStop in interface org.apache.pekko.actor.Actor
      Specified by:
      postStop in interface org.apache.pekko.actor.UnrestrictedStash
      Overrides:
      postStop in class org.apache.pekko.persistence.AbstractPersistentActor
      Throws:
      Exception

    • handleRecover

      protected void handleRecover(Object message) throws Exception
      Specified by:
      handleRecover in class AbstractUntypedPersistentActor
      Throws:
      Exception

    • overridePekkoRecoveredLog

      @NonNullByDefault protected ReplicatedLog overridePekkoRecoveredLog(ReplicatedLog recoveredLog)

    • handleNonRaftCommand

      protected void handleNonRaftCommand(Object message)
      Method exposed for subclasses to plug-in their logic. This method is invoked by handleCommand(Object) for messages which are not handled by this class. Subclasses overriding this class should fall back to this implementation for messages which they do not handle
      Parameters:
      message - Incoming command message

    • handleCommand

      protected final void handleCommand(Object message) throws InterruptedException
      Specified by:
      handleCommand in class AbstractUntypedPersistentActor
      Throws:
      InterruptedException

    • handleCommandImpl

      @Deprecated protected void handleCommandImpl(@NonNull Object message)
      Deprecated.
      This method is not final for testing purposes. DO NOT OVERRIDE IT, override handleNonRaftCommand(Object) instead.
      Handles a message.

    • newOnDemandRaftStateBuilder

      protected @NonNull OnDemandRaftState.AbstractBuilder<?,?> newOnDemandRaftStateBuilder()

    • applyCommand

      @NonNullByDefault protected abstract void applyCommand(@Nullable Identifier identifier, StateCommand command)
      Apply a StateCommand to update the actor's state.
      Parameters:
      identifier - The identifier of the persisted data. This is also the same identifier that was passed to submitCommand(Identifier, AbstractStateCommand, boolean) by the derived actor. May be null when the RaftActor is behaving as a follower or during recovery
      command - the StateCommand to apply

    • wrapLeaderStateChanged

      @NonNullByDefault protected LeaderStateChanged wrapLeaderStateChanged(LeaderStateChanged change)

    • submitCommand

      @NonNullByDefault public final void submitCommand(Identifier identifier, AbstractStateCommand command, boolean batchHint)
      Request a StateCommand to be applied to the finite state machine. Once consensus is reached, applyCommand(Identifier, StateCommand) will be called with matching arguments.
      Parameters:
      identifier - optional identifier to report back
      command - the command

    • getCurrentBehavior

      protected final RaftActorBehavior getCurrentBehavior()

    • isLeader

      protected boolean isLeader()
      Derived actors can call the isLeader method to check if the current RaftActor is the Leader or not.
      Returns:
      true it this RaftActor is a Leader false otherwise

    • isLeaderActive

      protected final boolean isLeaderActive()

    • isLeadershipTransferInProgress

      protected boolean isLeadershipTransferInProgress()

    • getLeader

      protected final @Nullable org.apache.pekko.actor.ActorSelection getLeader()
      Derived actor can call getLeader if they need a reference to the Leader. This would be useful for example in forwarding a request to an actor which is the leader.
      Returns:
      A reference to the leader if known, null otherwise

    • getLeaderId

      protected final String getLeaderId()
      Returns the id of the current leader.
      Returns:
      the current leader's id

    • getRaftState

      protected final RaftRole getRaftState()

    • getRaftActorContext

      public final RaftActorContext getRaftActorContext()

    • updateConfigParams

      protected void updateConfigParams(ConfigParams configParams)

    • isRecoveryApplicable

      public final boolean isRecoveryApplicable()

    • persistence

      @NonNullByDefault protected final PersistenceProvider persistence()

    • setPersistence

      protected final void setPersistence(boolean persistent)

    • setPeerAddress

      protected void setPeerAddress(String peerId, String peerAddress)
      setPeerAddress sets the address of a known peer at a later time.

      This is to account for situations where a we know that a peer exists but we do not know an address up-front. This may also be used in situations where a known peer starts off in a different location and we need to change it's address

      Note that if the peerId does not match the list of peers passed to this actor during construction an IllegalStateException will be thrown.

    • getRaftActorRecoveryCohort

      protected abstract @NonNull RaftActorRecoveryCohort getRaftActorRecoveryCohort()
      Returns the RaftActorRecoveryCohort to participate in persistence recovery.

    • onRecoveryComplete

      protected abstract void onRecoveryComplete()
      This method is called when recovery is complete.

    • getRaftActorSnapshotCohort

      protected abstract @NonNull RaftActorSnapshotCohort<?> getRaftActorSnapshotCohort()
      Returns the RaftActorSnapshotCohort to participate in snapshot captures.

    • onStateChanged

      protected abstract void onStateChanged()
      This method will be called by the RaftActor when the state of the RaftActor changes. The derived actor can then use methods like isLeader or getLeader to do something useful

    • roleChangeNotifier

      protected abstract @Nullable org.apache.pekko.actor.ActorRef roleChangeNotifier()
      Notifier Actor for this RaftActor to notify when a role change happens.
      Returns:
      ActorRef - ActorRef of the notifier or null if none.

    • onVotingStateChangeComplete

      protected void onVotingStateChangeComplete()
      This method is called on the leader when a voting change operation completes.

    • pauseLeader

      protected void pauseLeader(Runnable operation)
      This method is called prior to operations such as leadership transfer and actor shutdown when the leader must pause or stop its duties. This method allows derived classes to gracefully pause or finish current work prior to performing the operation. On completion of any work, the run method must be called on the given Runnable to proceed with the given operation. Important: the run method must be called on this actor's thread dispatcher as as it modifies internal state.

      The default implementation immediately runs the operation.

      Parameters:
      operation - the operation to run

    • unpauseLeader

      protected void unpauseLeader()
      This method is invoked when the actions hooked to the leader becoming paused failed to execute and the leader should resume normal operations.

      Note this method can be invoked even before the operation supplied to pauseLeader(Runnable) is invoked.

    • onLeaderChanged

      protected void onLeaderChanged(String oldLeader, String newLeader)

    • persist

      @Deprecated(since="11.0.0", forRemoval=true) public final <A> void persist(A entry, org.apache.pekko.japi.Procedure<A> callback)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      persist in interface org.apache.pekko.persistence.AbstractPersistentActorLike
      Overrides:
      persist in class org.apache.pekko.persistence.AbstractPersistentActor

    • persistAsync

      @Deprecated(since="11.0.0", forRemoval=true) public final <A> void persistAsync(A entry, org.apache.pekko.japi.Procedure<A> callback)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      persistAsync in interface org.apache.pekko.persistence.AbstractPersistentActorLike
      Overrides:
      persistAsync in class org.apache.pekko.persistence.AbstractPersistentActor

    • loadSnapshot

      @Deprecated(since="11.0.0", forRemoval=true) public final void loadSnapshot(String persistenceId, org.apache.pekko.persistence.SnapshotSelectionCriteria criteria, long toSequenceNr)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      loadSnapshot in interface org.apache.pekko.persistence.Snapshotter
      Overrides:
      loadSnapshot in class org.apache.pekko.persistence.AbstractPersistentActor

    • saveSnapshot

      @Deprecated(since="11.0.0", forRemoval=true) public final void saveSnapshot(Object snapshot)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      saveSnapshot in interface org.apache.pekko.persistence.Snapshotter
      Overrides:
      saveSnapshot in class org.apache.pekko.persistence.AbstractPersistentActor

    • deleteSnapshot

      @Deprecated(since="11.0.0", forRemoval=true) public final void deleteSnapshot(long sequenceNr)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      deleteSnapshot in interface org.apache.pekko.persistence.Snapshotter
      Overrides:
      deleteSnapshot in class org.apache.pekko.persistence.AbstractPersistentActor

    • deleteSnapshots

      @Deprecated(since="11.0.0", forRemoval=true) public final void deleteSnapshots(org.apache.pekko.persistence.SnapshotSelectionCriteria criteria)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      deleteSnapshots in interface org.apache.pekko.persistence.Snapshotter
      Overrides:
      deleteSnapshots in class org.apache.pekko.persistence.AbstractPersistentActor