FSM

FSMトレイトとオブジェクト

FSM トレイトは Actor を直接継承します。 FSM を拡張すると、アクターが実際に作成されたことに気づくでしょう:

class Buncher extends FSM[State, Data] {

  // fsm body ...

  initialize()
}

FSM トレイトは2つの型パラメータをとります:

1. すべての状態名のスーパータイプ、通常それを継承するケースオブジェクトのシールドトレイト

2. FSM モジュール自身によって追跡される状態データの型

状態の定義

状態は1つ以上のメソッド呼び出しで定義されます

when(<name>[, stateTimeout = <timeout>])(stateFunction).

指定する名前は、 FSM トレイトに与えられた最初の型パラメータと型互換性のあるオブジェクトでなければなりません。このオブジェクトはハッシュキーとして使用されるため、正しく equals と hashCode を確実に正しく実装する必要があります。特にそれは変更可能であってはなりません。これらの要件に最も簡単に適合するのは、ケースオブジェクトです。

stateTimeout パラメータが与えられた場合、そのままの滞在を含むこの状態へのすべての遷移は、デフォルトでこのタイムアウトを受け取ります。明示的なタイムアウトで遷移を開始すると、このデフォルトを上書きすることができます。詳しくは 遷移の開始 を参照してください。状態のタイムアウトは、アクション処理中に setStateTimeout(state, duration) を使って変更することもできます。これにより、外部メッセージなどによる実行時設定を可能にします。

stateFunction の引数は PartialFunction[Event, State] です。これは、以下に示すような部分関数のリテラル構文を使用すると便利です。

when(Idle) {
  case Event(SetTarget(ref), Uninitialized) =>
    stay using Todo(ref, Vector.empty)
}

when(Active, stateTimeout = 1 second) {
  case Event(Flush | StateTimeout, t: Todo) =>
    goto(Idle) using t.copy(queue = Vector.empty)
}

Event(msg: Any, data: D) ケースクラスは、パターンマッチングしやすくするためにFSMが保持するデータ型でパラメータ化されています。

It is recommended practice to declare the states as objects extending a sealed trait and then verify that there is a when clause for each of the states. If you want to leave the handling of a state “unhandled” (more below), it still needs to be declared like this:

when(SomeState)(FSM.NullFunction)

初期状態の定義

各FSMには出発点が必要で以下で宣言されます。

startWith(state, data[, timeout])

オプションで指定されたタイムアウト引数は、目的の初期状態に与えられた値で上書きします。デフォルトのタイムアウトを取り消したい場合は、None を使います。

処理されないイベント

状態が受信したイベントを処理しない場合、警告がログ出力されます。このとき何か別のことをしたい場合は、それを whenUnhandled(stateFunction) で指定することができます:

whenUnhandled {
  case Event(x: X, data) =>
    log.info("Received unhandled event: " + x)
    stay
  case Event(msg, _) =>
    log.warning("Received unknown event: " + msg)
    goto(Error)
}

このハンドラ内では、 stateName メソッドを使用してFSMの状態を問い合わせることができます。

重要: このハンドラはスタックされません。つまり、 whenUnhandled を呼び出すたびに前に設定されていたハンドラが置き換えられます。

遷移の開始

stateFunction の結果は、 Termination from Inside で説明されているFSMを終了しない限り、次の状態の定義でなければなりません。状態定義は、stay ディレクティブで記述されている現在の状態でも、 goto(state) によって与えられた状態と異なる状態でも構いません。結果として得られるオブジェクトは、次のような修飾子を使用してさらに修飾することができます。

• forMax(duration)

  この修飾子は、次の状態で状態のタイムアウトを設定します。これは、終了時に StateTimeout メッセージをFSMに送信するタイマーが開始されることを意味する。このタイマーは、その間に他のメッセージを受信するとキャンセルされ、そのメッセージの後に StateTimeout メッセージは処理されません。

  この修飾子を使用して、ターゲットの状態に指定されているデフォルトのタイムアウトを無効にすることもできます。デフォルトのタイムアウトをキャンセルするには、 Duration.Inf を使用します。

• using(data)

  この修飾子は、古い状態のデータを新しいデータで置き換えます。 前 のアドバイスに従えば、これが内部状態のデータが変更される唯一の場所です。

• replying(msg)

  この修飾子は、現在処理中のメッセージに応答を送信し状態は変更しません。

すべての修飾子は、簡潔に記述に記述するためにチェーンすることができます:

when(SomeState) {
  case Event(msg, _) =>
    goto(Processing) using (newData) forMax (5 seconds) replying (WillDo)
}

実際にはかっこは必要ありませんが、修飾子とその引数を視覚的に区別しているため、外国人にとっては快適で読みやすくなります。

遷移の監視

遷移は「状態と状態の間」で概念的に発生します。これは、イベント処理ブロックに入れたアクションの後であることを意味します。次の状態は、イベント処理ロジックによって返される値によってのみ定義されるため、これは明らかです。 FSMアクター内のすべてがシングルスレッドで実行されているため、内部状態変数の設定に関して正確な順序を心配する必要はありません。

onTransition {
  case Idle -> Active => setTimer("timeout", Tick, 1 second, repeat = true)
  case Active -> _    => cancelTimer("timeout")
  case x -> Idle      => log.info("entering Idle from " + x)
}

onTransition(handler _)

def handler(from: StateType, to: StateType) {
  // handle it here ...
}

状態の変換

when() ブロックの引数として提供される部分関数は、Scalaの関数型プログラミングツールの完全な補足を使用して変換できます。型推論を保持するために、いくつかの共通の処理ロジックが異なる節に適用される場合に使用されるヘルパー関数があります:

when(SomeState)(transform {
  case Event(bytes: ByteString, read) => stay using (read + bytes.length)
} using {
  case s @ FSM.State(state, read, timeout, stopReason, replies) if read > 1000 =>
    goto(Processing)
})

言うまでもありませんが、このメソッドへの引数は記憶され、いくつかの when() ブロックに同じ変換を適用すると、複数回使用されます。

val processingTrigger: PartialFunction[State, State] = {
  case s @ FSM.State(state, read, timeout, stopReason, replies) if read > 1000 =>
    goto(Processing)
}

when(SomeState)(transform {
  case Event(bytes: ByteString, read) => stay using (read + bytes.length)
} using processingTrigger)

タイマー

状態のタイムアウトに加えて、FSMは String の名前で識別されるタイマーを管理します。以下でタイマーをセットします。

setTimer(name, msg, interval, repeat)

 msg は、 interval が経過した後に送信されるメッセージオブジェクトです。 repeat が true の場合、タイマーは interval パラメータによって与えられた固定間隔でスケジュールされます。新しいタイマーを追加する前に、同じ名前の既存のタイマーが自動的に取り消されます。

以下でタイマーをキャンセルします。

cancelTimer(name)

これは、すぐに動作することが保証されています。つまり、タイマーがすでに起動してキューに入れられていても、これを呼び出した後にスケジュールされたメッセージは処理されません。以下でタイマーの状態を問合せます。

isTimerActive(name)

これらの名前付きタイマーは、他のメッセージの介在による影響を受けないため、状態のタイムアウトを補完します。

内部からの終了

FSMは、次のように最後の状態を指定することによって停止されます。

stop([reason[, data]])

理由は、 Normal (デフォルト)、 Shutdown または Failure(reason) のいずれかで、第2引数は終了処理中に利用可能な状態のデータを変更するために与えます。

when(Error) {
  case Event("stop", _) =>
    // do cleanup ...
    stop()
}

onTermination(handler) を使って、FSMが停止したときに実行されるカスタムコードを指定することができます。ハンドラは引数として StopEvent(reason, stateName, stateData) を取る部分関数です:

onTermination {
  case StopEvent(FSM.Normal, state, data)         => // ...
  case StopEvent(FSM.Shutdown, state, data)       => // ...
  case StopEvent(FSM.Failure(cause), state, data) => // ...
}

whenUnhandled の場合、このハンドラはスタックされていないので、 onTermination を呼び出すたびに、以前に設定されたハンドラが置き換えられます。

外部からの終了

stop メソッドを使用してFSMに関連付けられた ActorRef を停止すると、 postStop フックが実行されます。 FSM トレイトによるデフォルト実装は、 StopEvent(Shutdown, ...) を処理する準備ができている場合に:meth:onTermination ハンドラを実行します。

イベントのトレース

環境設定 の akka.actor.debug.fsm を設定すると、 LoggingFSM インスタンスによって、イベントのトレースのロギングを有効にできます ：

import akka.actor.LoggingFSM
class MyFSM extends LoggingFSM[StateType, Data] {
  // body elided ...
}

以下は、DEBUGレベル出力します。

• StateTimeout とスケジュールされたタイマーメッセージを含むすべての処理済みイベント

• 名前付きタイマーの設定とキャンセル

• すべての状態遷移

ライフサイクルの変更と特別なメッセージは、 Actors の説明のとおりにロギングすることができます。

ローリングイベントログ

LoggingFSM トレイトは、FSMにもう一つの機能を追加します。デバッグ中(FSMがどのように特定のエラー状態に陥ったのかをトレースするため)や他のクリエイティブな用途のために使用されるローリングイベントログです。

import akka.actor.LoggingFSM
class MyFSM extends LoggingFSM[StateType, Data] {
  override def logDepth = 12
  onTermination {
    case StopEvent(FSM.Failure(_), state, data) =>
      val lastEvents = getLog.mkString("\n\t")
      log.warning("Failure in state " + state + " with data " + data + "\n" +
        "Events leading up to this point:\n\t" + lastEvents)
  }
  // ...
}

logDepth のデフォルトは0で、これはイベントログをオフにします。

イベントログの内容は、 getLog メソッドを使って取得できます。このメソッドは IndexedSeq[LogEntry] を返します。最も古いエントリはインデックス0になります。