Interface FSM<S,D>
-
- All Superinterfaces:
Actor
,ActorLogging
,Listeners
- All Known Subinterfaces:
LoggingFSM<S,D>
- All Known Implementing Classes:
AbstractFSM
,AbstractFSMWithStash
,AbstractLoggingFSM
,ClusterSingletonManager
public interface FSM<S,D> extends Actor, Listeners, ActorLogging
Finite State Machine actor trait. Use as follows:object A { trait State case class One extends State case class Two extends State case class Data(i : Int) } class A extends Actor with FSM[A.State, A.Data] { import A._ startWith(One, Data(42)) when(One) { case Event(SomeMsg, Data(x)) => ... case Event(SomeOtherMsg, _) => ... // when data not needed } when(Two, stateTimeout = 5 seconds) { ... } initialize() }
Within the partial function the following values are returned for effecting state transitions:
-
stay
for staying in the same state -stay using Data(...)
for staying in the same state, but with different data -stay forMax 5.millis
for staying with a state timeout; can be combined withusing
-goto(...)
for changing into a different state; also supportsusing
andforMax
-stop
for terminating this FSM actorEach of the above also supports the method
replying(AnyRef)
for sending a reply before changing state.While changing state, custom handlers may be invoked which are registered using
onTransition
. This is meant to enable concentrating different concerns in different places; you may choose to usewhen
for describing the properties of a state, including of course initiating transitions, but you can describe the transitions usingonTransition
to avoid having to duplicate that code among multiple paths which lead to a transition:onTransition { case Active -> _ => cancelTimer("activeTimer") }
Multiple such blocks are supported and all of them will be called, not only the first matching one.
Another feature is that other actors may subscribe for transition events by sending a
SubscribeTransitionCallback
message to this actor. Stopping a listener without unregistering will not remove the listener from the subscription list; useUnsubscribeTransitionCallback
before stopping the listener.State timeouts set an upper bound to the time which may pass before another message is received in the current state. If no external message is available, then upon expiry of the timeout a StateTimeout message is sent. Note that this message will only be received in the state for which the timeout was set and that any message received will cancel the timeout (possibly to be started again by the next transition).
Another feature is the ability to install and cancel single-shot as well as repeated timers which arrange for the sending of a user-specified message:
setTimer("tock", TockMsg, 1 second, true) // repeating setTimer("lifetime", TerminateMsg, 1 hour, false) // single-shot cancelTimer("tock") isTimerActive("tock")
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
FSM.$minus$greater$
This extractor is just convenience for matching a (S, S) pair, including a reminder what the new state is.static class
FSM.CurrentState<S>
Message type which is sent directly to the subscribed actor inpekko.actor.FSM.SubscribeTransitionCallBack
before sending anypekko.actor.FSM.Transition
messages.static class
FSM.CurrentState$
static class
FSM.Event<D>
All messages sent to thepekko.actor.FSM
will be wrapped inside anEvent
, which allows pattern matching to extract both state and data.static class
FSM.Event$
static class
FSM.Failure
Signifies that thepekko.actor.FSM
is shutting itself down because of an error, e.g.static class
FSM.Failure$
static class
FSM.FixedDelayMode$
INTERNAL APIstatic class
FSM.FixedRateMode$
INTERNAL APIstatic class
FSM.LogEntry<S,D>
Log Entry of thepekko.actor.LoggingFSM
, can be obtained by callinggetLog
.static class
FSM.LogEntry$
static class
FSM.Normal$
Default reason if callingstop()
.static class
FSM.NullFunction$
A partial function value which does not match anything and can be used to “reset”whenUnhandled
andonTermination
handlers.static interface
FSM.Reason
Reason why thispekko.actor.FSM
is shutting down.static class
FSM.Shutdown$
Reason given when someone was callingsystem.stop(fsm)
from outside; also applies toStop
supervision directive.static class
FSM.SilentState<S,D>
INTERNAL API Using a subclass for binary compatibility reasonsstatic class
FSM.SingleMode$
INTERNAL APIstatic class
FSM.State<S,D>
static class
FSM.State$
This captures all of the managed state of thepekko.actor.FSM
: the state name, the state data, possibly custom timeout, stop reason and replies accumulated while processing the last message.static class
FSM.StateTimeout$
This case object is received in case of a state timeout.static class
FSM.StopEvent<S,D>
Case class representing the state of thepekko.actor.FSM
within theonTermination
block.static class
FSM.StopEvent$
static class
FSM.SubscribeTransitionCallBack
Send this to anpekko.actor.FSM
to request first theFSM.CurrentState
and then a series ofFSM.Transition
updates.static class
FSM.SubscribeTransitionCallBack$
static class
FSM.Timer
INTERNAL APIstatic class
FSM.Timer$
static interface
FSM.TimerMode
INTERNAL APIstatic class
FSM.TransformHelper
static class
FSM.Transition<S>
Message type which is used to communicate transitions between states to all subscribed listeners (usepekko.actor.FSM.SubscribeTransitionCallBack
).static class
FSM.Transition$
static class
FSM.UnsubscribeTransitionCallBack
Unsubscribe frompekko.actor.FSM.Transition
notifications which was effected by sending the correspondingpekko.actor.FSM.SubscribeTransitionCallBack
.static class
FSM.UnsubscribeTransitionCallBack$
-
Nested classes/interfaces inherited from interface org.apache.pekko.actor.Actor
Actor.emptyBehavior$, Actor.ignoringBehavior$
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description FSM.$minus$greater$
$minus$greater()
This extractor is just convenience for matching a (S, S) pair, including a reminder what the new state is.void
applyState(FSM.State<S,D> nextState)
void
cancelTimer(java.lang.String name)
void
currentState_$eq(FSM.State<S,D> x$1)
boolean
debugEvent()
FSM.Event$
Event()
void
generation_$eq(long x$1)
void
handleEvent_$eq(scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> x$1)
void
handleTransition(S prev, S next)
void
initialize()
boolean
isStateTimerActive()
boolean
isTimerActive(java.lang.String name)
void
logTermination(FSM.Reason reason)
By defaultpekko.actor.FSM.Failure
is logged at error level and other reason types are not logged.void
makeTransition(FSM.State<S,D> nextState)
void
nextState_$eq(FSM.State<S,D> x$1)
D
nextStateData()
void
onTermination(scala.PartialFunction<FSM.StopEvent<S,D>,scala.runtime.BoxedUnit> terminationHandler)
void
onTransition(scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit> transitionHandler)
void
org$apache$pekko$actor$FSM$_setter_$Event_$eq(FSM.Event$ x$1)
void
org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq(FSM.StateTimeout$ x$1)
This case object is received in case of a state timeout.void
org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq(FSM.StopEvent$ x$1)
void
postStop()
User overridable callback.void
processEvent(FSM.Event<D> event, java.lang.Object source)
void
processMsg(java.lang.Object value, java.lang.Object source)
scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit>
receive()
Scala API: This defines the initial actor behavior, it must return a partial function with the actor logic.void
register(S name, scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> function, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
void
setStateTimeout(S state, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
void
setTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration timeout, boolean repeat)
Deprecated.Use startSingleTimer, startTimerWithFixedDelay or startTimerAtFixedRate instead.boolean
setTimer$default$4()
void
startSingleTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration delay)
void
startTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration timeout, FSM.TimerMode mode)
void
startTimerAtFixedRate(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration interval)
void
startTimerWithFixedDelay(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration delay)
void
startWith(S stateName, D stateData, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
Set initial state.scala.Option<scala.concurrent.duration.FiniteDuration>
startWith$default$3()
D
stateData()
S
stateName()
FSM.StateTimeout$
StateTimeout()
This case object is received in case of a state timeout.FSM.State<S,D>
stay()
Produce "empty" transition descriptor.FSM.State<S,D>
stop()
Produce change descriptor to stop this FSM actor with reason "Normal".FSM.State<S,D>
stop(FSM.Reason reason)
Produce change descriptor to stop this FSM actor including specified reason.FSM.State<S,D>
stop(FSM.Reason reason, D stateData)
Produce change descriptor to stop this FSM actor including specified reason.FSM.StopEvent$
StopEvent()
void
super$postStop()
CallonTermination
hook; if you want to retain this behavior when overriding make sure to callsuper.postStop()
.void
terminate(FSM.State<S,D> nextState)
void
terminateEvent_$eq(scala.PartialFunction<FSM.StopEvent<S,D>,scala.runtime.BoxedUnit> x$1)
void
timeoutFuture_$eq(scala.Option<Cancellable> x$1)
scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit>
total2pf(scala.Function2<S,S,scala.runtime.BoxedUnit> transitionHandler)
FSM.TransformHelper
transform(scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> func)
void
transitionEvent_$eq(scala.collection.immutable.List<scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit>> x$1)
void
when(S stateName, scala.concurrent.duration.FiniteDuration stateTimeout, scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> stateFunction)
Insert a new StateFunction at the end of the processing chain for the given state.scala.concurrent.duration.FiniteDuration
when$default$2()
void
whenUnhandled(scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> stateFunction)
-
Methods inherited from interface org.apache.pekko.actor.Actor
aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, context, org$apache$pekko$actor$Actor$_setter_$context_$eq, org$apache$pekko$actor$Actor$_setter_$self_$eq, postRestart, preRestart, preStart, self, sender, supervisorStrategy, unhandled
-
Methods inherited from interface org.apache.pekko.actor.ActorLogging
_log_$eq, log
-
Methods inherited from interface org.apache.pekko.routing.Listeners
gossip, gossip$default$2, listenerManagement, listeners, org$apache$pekko$routing$Listeners$_setter_$listeners_$eq
-
-
-
-
Method Detail
-
org$apache$pekko$actor$FSM$_setter_$Event_$eq
void org$apache$pekko$actor$FSM$_setter_$Event_$eq(FSM.Event$ x$1)
-
org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq
void org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq(FSM.StopEvent$ x$1)
-
org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq
void org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq(FSM.StateTimeout$ x$1)
This case object is received in case of a state timeout.
-
super$postStop
void super$postStop()
CallonTermination
hook; if you want to retain this behavior when overriding make sure to callsuper.postStop()
.Please note that this method is called by default from
preRestart()
, so override that one ifonTermination
shall not be called during restart.
-
Event
FSM.Event$ Event()
-
StopEvent
FSM.StopEvent$ StopEvent()
-
$minus$greater
FSM.$minus$greater$ $minus$greater()
This extractor is just convenience for matching a (S, S) pair, including a reminder what the new state is.
-
StateTimeout
FSM.StateTimeout$ StateTimeout()
This case object is received in case of a state timeout.
-
when
void when(S stateName, scala.concurrent.duration.FiniteDuration stateTimeout, scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> stateFunction)
Insert a new StateFunction at the end of the processing chain for the given state. If the stateTimeout parameter is set, entering this state without a differing explicit timeout setting will trigger a StateTimeout event; the same is true when using #stay.- Parameters:
stateName
- designator for the statestateTimeout
- default state timeout for this statestateFunction
- partial function describing response to input
-
when$default$2
scala.concurrent.duration.FiniteDuration when$default$2()
-
startWith
void startWith(S stateName, D stateData, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
Set initial state. Call this method from the constructor before theinitialize()
method. If different state is needed after a restart this method, followed byinitialize()
, can be used in the actor life cycle hookspekko.actor.Actor#preStart
andpekko.actor.Actor#postRestart
.- Parameters:
stateName
- initial state designatorstateData
- initial state datatimeout
- state timeout for the initial state, overriding the default timeout for that state
-
startWith$default$3
scala.Option<scala.concurrent.duration.FiniteDuration> startWith$default$3()
-
stay
FSM.State<S,D> stay()
Produce "empty" transition descriptor. Return this from a state function when no state change is to be effected.No transition event will be triggered by
stay()
. If you want to trigger an event likeS -> S
foronTransition
to handle usegoto
instead.- Returns:
- descriptor for staying in current state
-
stop
FSM.State<S,D> stop(FSM.Reason reason)
Produce change descriptor to stop this FSM actor including specified reason.
-
stop
FSM.State<S,D> stop(FSM.Reason reason, D stateData)
Produce change descriptor to stop this FSM actor including specified reason.
-
startTimerWithFixedDelay
void startTimerWithFixedDelay(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration delay)
-
startTimerAtFixedRate
void startTimerAtFixedRate(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration interval)
-
startSingleTimer
void startSingleTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration delay)
-
setTimer
void setTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration timeout, boolean repeat)
Deprecated.Use startSingleTimer, startTimerWithFixedDelay or startTimerAtFixedRate instead. This has the same semantics as startTimerAtFixedRate, but startTimerWithFixedDelay is often preferred. Since Akka 2.6.0.
-
setTimer$default$4
boolean setTimer$default$4()
-
startTimer
void startTimer(java.lang.String name, java.lang.Object msg, scala.concurrent.duration.FiniteDuration timeout, FSM.TimerMode mode)
-
cancelTimer
void cancelTimer(java.lang.String name)
-
isTimerActive
boolean isTimerActive(java.lang.String name)
-
setStateTimeout
void setStateTimeout(S state, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
-
isStateTimerActive
boolean isStateTimerActive()
-
onTransition
void onTransition(scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit> transitionHandler)
-
total2pf
scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit> total2pf(scala.Function2<S,S,scala.runtime.BoxedUnit> transitionHandler)
-
onTermination
void onTermination(scala.PartialFunction<FSM.StopEvent<S,D>,scala.runtime.BoxedUnit> terminationHandler)
-
whenUnhandled
void whenUnhandled(scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> stateFunction)
-
initialize
void initialize()
-
stateName
S stateName()
-
stateData
D stateData()
-
nextStateData
D nextStateData()
-
debugEvent
boolean debugEvent()
-
timeoutFuture_$eq
void timeoutFuture_$eq(scala.Option<Cancellable> x$1)
-
generation_$eq
void generation_$eq(long x$1)
-
register
void register(S name, scala.PartialFunction<FSM.Event<D>,FSM.State<S,D>> function, scala.Option<scala.concurrent.duration.FiniteDuration> timeout)
-
terminateEvent_$eq
void terminateEvent_$eq(scala.PartialFunction<FSM.StopEvent<S,D>,scala.runtime.BoxedUnit> x$1)
-
transitionEvent_$eq
void transitionEvent_$eq(scala.collection.immutable.List<scala.PartialFunction<scala.Tuple2<S,S>,scala.runtime.BoxedUnit>> x$1)
-
receive
scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive()
Description copied from interface:Actor
Scala API: This defines the initial actor behavior, it must return a partial function with the actor logic.
-
processMsg
void processMsg(java.lang.Object value, java.lang.Object source)
-
postStop
void postStop()
Description copied from interface:Actor
User overridable callback. Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation.
-
logTermination
void logTermination(FSM.Reason reason)
By defaultpekko.actor.FSM.Failure
is logged at error level and other reason types are not logged. It is possible to override this behavior.
-
-