アクター

アクターのクラスを定義する

アクターは:class:`Actor`という基本traitを拡張することで実装することができます。また、ここで:meth:`receive`というメソッドを実装する必要があります。:meth:`receive`というメソッドはcase文の塊で(この型は`PartialFunction[Any, Unit]``です)、Scalaのパターンマッチングを使ってアクターがどのようなメッセージを処理できるかということとそのメッセージがどのように処理されるかということを定義します。

以下はこのサンプルコードです。

import akka.actor.Actor
import akka.actor.Props
import akka.event.Logging

class MyActor extends Actor {
  val log = Logging(context.system, this)

  def receive = {
    case "test" => log.info("received test")
    case _      => log.info("received unknown message")
  }
}

Akkaのアクターの``receive``メッセージループは網羅的であるということに注意してください。これはErlangやScala言語組み込みのアクターとは異なっています。つまり受け取ることのできる全てのメッセージについてのパターンマッチを書く必要があり、未知のメッセージを処理したい場合はデフォルトのcaseを書かなければいけません。これを行わなかった場合は ``ActorSystem``の``EventStream``に`akka.actor.UnhandledMessage(message, sender, recipient)``が発行されます。

また、振る舞いの戻り値の型が``Unit``であることにも注意してください。アクターが受け取ったメッセージに対して応答を返す場合、後で説明するようにこれを明示的に行う必要があります。

:meth:`receive`メソッドの結果は部分関数であり、アクターの"初期の振る舞い"とみなされます。アクターが生成された後でどのように振る舞いを変えるかということについての詳しい情報は`Become/Unbecome`_を参照してください。

Props

:class:`Propsはアクターを生成するときのオプションを指定するための設定クラスです。このクラスのインスタンスは不変なので気軽に共有することができるアクターを生成するためのレシピと考えることができます。また、このレシピにはデプロイに関係した情報(例えばどのdispatcherを使うかとかいったもの)も含めることができます。

import akka.actor.Props

val props1 = Props[MyActor]
val props2 = Props(new ActorWithArgs("arg")) // careful, see below
val props3 = Props(classOf[ActorWithArgs], "arg") // no support for value class arguments

二つ目のやり方は生成する:class:`Actor`にどのように引数を渡すかということを例示していますが、後で説明するように、アクターの外側のみで用いるべきやり方です。

最後のやり方はアクターのコンストラクタに引数を渡す場合にどのようなコンテクストでも使うことができるやり方です。Propsオブジェクトの中でどのコンストラクタを用いるべきかということを調べて、適当なコンストラクタが見つからなかった場合や複数のコンストラクタにマッチしてしまった場合には:class:IllegalArgumentException となってしまいます。

// NOT RECOMMENDED within another actor:
// encourages to close over enclosing class
val props7 = Props(new MyActor)

case class MyValueClass(v: Int) extends AnyVal

class ValueActor(value: MyValueClass) extends Actor {
  def receive = {
    case multiplier: Long => sender() ! (value.v * multiplier)
  }
}
val valueClassProp = Props(classOf[ValueActor], MyValueClass(5)) // Unsupported

class DefaultValueActor(a: Int, b: Int = 5) extends Actor {
  def receive = {
    case x: Int => sender() ! ((a + x) * b)
  }
}

val defaultValueProp1 = Props(classOf[DefaultValueActor], 2.0) // Unsupported

class DefaultValueActor2(b: Int = 5) extends Actor {
  def receive = {
    case x: Int => sender() ! (x * b)
  }
}
val defaultValueProp2 = Props[DefaultValueActor2] // Unsupported
val defaultValueProp3 = Props(classOf[DefaultValueActor2]) // Unsupported

object DemoActor {
  /**
   * Create Props for an actor of this type.
   *
   * @param magicNumber The magic number to be passed to this actor’s constructor.
   * @return a Props for creating this actor, which can then be further configured
   *         (e.g. calling `.withDispatcher()` on it)
   */
  def props(magicNumber: Int): Props = Props(new DemoActor(magicNumber))
}

class DemoActor(magicNumber: Int) extends Actor {
  def receive = {
    case x: Int => sender() ! (x + magicNumber)
  }
}

class SomeOtherActor extends Actor {
  // Props(new DemoActor(42)) would not be safe
  context.actorOf(DemoActor.props(42), "demo")
  // ...
}

object MyActor {
  case class Greeting(from: String)
  case object Goodbye
}
class MyActor extends Actor with ActorLogging {
  import MyActor._
  def receive = {
    case Greeting(greeter) => log.info(s"I was greeted by $greeter.")
    case Goodbye           => log.info("Someone said goodbye to me.")
  }
}

Propsを使ったアクターの生成

アクターは:class:`Props`のインスタンスを:class:`ActorSystem`や:class:`ActorContext`が持っている:meth:`actorOf`というファクトリメソッドに渡すことで生成できます。

import akka.actor.ActorSystem

// ActorSystem is a heavy object: create only one per application
val system = ActorSystem("mySystem")
val myActor = system.actorOf(Props[MyActor], "myactor2")

:class:`ActorSystem`を使うとトップレベルのアクターを生成できます。トップレベルのアクターはアクターシステムが提供しているガーディアンアクターによって監視されます。一方でコンテクストから生成したアクターはそのアクターの子アクターになります。

class FirstActor extends Actor {
  val child = context.actorOf(Props[MyActor], name = "myChild")
  // plus some behavior ...
}

子供から孫といった階層を作るようにしてください。そのようにすることでアプリケーションの論理的なエラー処理の構造を作ることができます。詳しくは:ref:`actor-systems`を参照してください。

:meth:`actorOf`を呼ぶことで:class:`ActorRef`のインスタンスを得ることができます。:class:`ActorRef`はアクターのインスタンスとつながっていて、アクターと対話するための唯一の手段となります。:class:`ActorRef`は不変でそれが表現しているアクターと一対一の関係を持っています。:class:`ActorRef`は永続化可能なのでネットワークを介することができます。つまり、シリアライズしたインスタンスをリモートのホストに送信した場合、元のノードのアクターをネットワークを超えて表現することができます。

nameパラメータはオプションですがアクターには名前を与えた方がよいでしょう。なぜなら、アクターの名前はログメッセージでアクターを識別するために用いるからです。アクターの名前は空文字や"$"から始まる文字列は許可されていませんが、そうした名前がURLにエンコードされた文字には含まれることがあります。(例えば、"%20"は空白文字です。)もじ与えられた名前が既に同じ親を持つ他の子アクターが利用していた場合、:class:`InvalidActorNameException`がスローされます。

アクターは生成されたら非同期に自動的に開始されます。

class Argument(val value: String) extends AnyVal
class ValueClassActor(arg: Argument) extends Actor {
  def receive = { case _ => () }
}

object ValueClassActor {
  def props1(arg: Argument) = Props(classOf[ValueClassActor], arg) // fails at runtime
  def props2(arg: Argument) = Props(classOf[ValueClassActor], arg.value) // ok
  def props3(arg: Argument) = Props(new ValueClassActor(arg)) // ok
}

依存性の注入

アクターがコンストラクタで引数を受け取る場合、`すでに述べたように`__それは:class:`Props`の生成の中で利用する必要があります。しかし、ファクトリメソッドを用意していたとしても直接コンストラクタを使うケースがあります。例えば依存性の注入を行うフレームワークがコンストラクタの引数を調べる場合です。

import akka.actor.IndirectActorProducer

class DependencyInjector(applicationContext: AnyRef, beanName: String)
  extends IndirectActorProducer {

  override def actorClass = classOf[Actor]
  override def produce =
    // obtain fresh Actor instance from DI framework ...
}

val actorRef = system.actorOf(
  Props(classOf[DependencyInjector], applicationContext, "hello"),
  "helloBean")

依存性の注入のためのテクニックや依存性注入を行うフレームワークとの統合については`Using Akka with Dependency Injection <http://letitcrash.com/post/55958814293/akka-dependency-injection>`_ guidelineやLightbend Activatorの中の`Akka Java Spring <http://www.lightbend.com/activator/template/akka-java-spring>`_ tutorialにより詳しい情報があります。

Inbox

アクターの外側のコードからアクターと通信をする場合、``ask``パターン(後で出てきます)を使うのが一つの方法ですが、それを使えない場合が二つあります。一つは複数のメッセージを受け取るような場合(例えば通知サービスとして実装されている:class:`ActorRef`を購読する場合)で、もう一つはActorのライフサイクルをwatchしている場合です。こういった場合のために:class:`Inbox`というクラスが用意されています。

このコードでは:class:`Inbox`から:class:`Inbox`への暗黙的な変換が行われています。つまりこの例ではsenderへの参照は暗黙的に:class:`Inbox`に対するものになります。このようにすることで最後の行に書かれているようなやり方で応答を受け取ることができます。アクターをwatchする方法も簡単です。

アクターのライフサクル

アクターシステムにおけるパスは生存しているアクターによって占有されている"場所"を表現しています。始めは(システムによって初期化されたアクターを除き)パスは空になっています。 actorOf() を呼びだすと Prop で表現されたアクターの*インカーネーション*が与えられたパスに生成されます。アクターのインカーネーションはパスと UID によって識別されます。再起動が行われたときには Actor のインスタンスは置き換えられますが、インカーネーションの方は置き換えられないので UID は同じものになります。

アクターのインカーネーションのライフサイクルはアクターが停止した時に終わります。この時、これに対応したライフサイクルの終了イベントが呼ばれ、これを watch しているアクターに停止が通知されます。インカーネーションが停止したのち、インカーネーションのパスは再び actorOf() を使って再利用することができるようになります。この場合新しいインカーネーションの名前は前のものと同じですがUIDは別のものになります。アクターは自分自身や他のアクター、あるいは``ActorSystem``によって停止されることがあります。(:ref:`stopping-actors-scala`を参照)

``ActorRef``はただ単に与えられたパスを表現しているのではなくいつでもインカーネーション(パスとUID)を表現しています。つまりアクターを停止して同じ名前のアクターを生成した場合、新しく生成した``ActorRef``は古いインカーネーションでなく新しいインカーネーションを指しています。

一方で ActorSelection はパスを示していて(ワイルドカードを使った場合は複数のパスを指します。)、現在そのパスを持っているのがどのインカーネーションなのかを完全に識別することができます。このため ActorSelection を watch することはできません。パスに存在するインカーネーションを watch するためには、ActorSelection に対して Identity メッセージを送信し ActorSelection から応答として ActorIdentity を受け取り、その中に含まれる正しい参照(actorSelection-scala`を参照)を使って現在のインカーネーションの ``ActorRef` を解決します。 ActorSelection が持つ resolveOne を使うとパスにマッチした ActorRef の Future が戻されるので同じようなことができます。

ライフサイクルの監視、DeathWatch

他のアクターの停止を知るために(例えば、永久に停止された場合や一時的ではない障害によって再起動された場合など)、アクターは他のアクターが停止時に発する Terminated メッセージを受け取るようにすることができます。(Stopping Actors`_も参照のこと)この機能はアクターシステムの :class:`DeathWatch というコンポーネントによって提供されています。

モニターを登録するのは簡単です。

import akka.actor.{ Actor, Props, Terminated }

class WatchActor extends Actor {
  val child = context.actorOf(Props.empty, "child")
  context.watch(child) // <-- this is the only call needed for registration
  var lastSender = context.system.deadLetters

  def receive = {
    case "kill" =>
      context.stop(child); lastSender = sender()
    case Terminated(`child`) => lastSender ! "finished"
  }
}

Terminated メッセージは登録や停止がどのような順番で起きたかとは独立して生成されることに注意してください。典型的な例として、監視を行うアクターは例え監視の登録を行った時点ですでに監視対象のアクターが停止されていたとしても Treminated メッセージを受け取ることになります。

監視の登録を複数回行うことが必ずしも複数のメッセージを作ることになるわけではありませんが、こうしたメッセージを正確に一度受け取ることができる保障はありません。監視対象のアクターの停止メッセージが作られてキューに入ってから、このメッセージが処理される前に他のところで登録が行われたら、二つ目のメッセージがキューに入ります。何故なら既に停止したアクターの監視を登録すると、直ちに: class:Terminated が生成されるためです。

同じようなことが他のアクターの生存監視を context.unwatch(target) を使ってやめた場合にも起こりえます。これは例え Terminated メッセージがメールボックスに入っていたとしても、unwatch`の呼び出しの後には監視を停止したアクターの :class:`Terminated メッセージは処理されないためです。

Start Hook

Right after starting the actor, its preStart method is invoked.

override def preStart() {
  child = context.actorOf(Props[MyActor], "child")
}

This method is called when the actor is first created. During restarts it is called by the default implementation of postRestart, which means that by overriding that method you can choose whether the initialization code in this method is called only exactly once for this actor or for every restart. Initialization code which is part of the actor’s constructor will always be called when an instance of the actor class is created, which happens at every restart.

Restart Hooks

All actors are supervised, i.e. linked to another actor with a fault handling strategy. Actors may be restarted in case an exception is thrown while processing a message (see Supervision and Monitoring). This restart involves the hooks mentioned above:

1. The old actor is informed by calling preRestart with the exception which caused the restart and the message which triggered that exception; the latter may be None if the restart was not caused by processing a message, e.g. when a supervisor does not trap the exception and is restarted in turn by its supervisor, or if an actor is restarted due to a sibling’s failure. If the message is available, then that message’s sender is also accessible in the usual way (i.e. by calling sender).

   This method is the best place for cleaning up, preparing hand-over to the fresh actor instance, etc. By default it stops all children and calls postStop.

2. The initial factory from the actorOf call is used to produce the fresh instance.

3. The new actor’s postRestart method is invoked with the exception which caused the restart. By default the preStart is called, just as in the normal start-up case.

An actor restart replaces only the actual actor object; the contents of the mailbox is unaffected by the restart, so processing of messages will resume after the postRestart hook returns. The message that triggered the exception will not be received again. Any message sent to an actor while it is being restarted will be queued to its mailbox as usual.

Stop Hook

After stopping an actor, its postStop hook is called, which may be used e.g. for deregistering this actor from other services. This hook is guaranteed to run after message queuing has been disabled for this actor, i.e. messages sent to a stopped actor will be redirected to the deadLetters of the ActorSystem.

Tell: Fire-forget

This is the preferred way of sending messages. No blocking waiting for a message. This gives the best concurrency and scalability characteristics.

actorRef ! message

If invoked from within an Actor, then the sending actor reference will be implicitly passed along with the message and available to the receiving Actor in its sender(): ActorRef member method. The target actor can use this to reply to the original sender, by using sender() ! replyMsg.

If invoked from an instance that is not an Actor the sender will be deadLetters actor reference by default.

Ask: Send-And-Receive-Future

The ask pattern involves actors as well as futures, hence it is offered as a use pattern rather than a method on ActorRef:

import akka.pattern.{ ask, pipe }
import system.dispatcher // The ExecutionContext that will be used
final case class Result(x: Int, s: String, d: Double)
case object Request

implicit val timeout = Timeout(5 seconds) // needed for `?` below

val f: Future[Result] =
  for {
    x <- ask(actorA, Request).mapTo[Int] // call pattern directly
    s <- (actorB ask Request).mapTo[String] // call by implicit conversion
    d <- (actorC ? Request).mapTo[Double] // call by symbolic name
  } yield Result(x, s, d)

f pipeTo actorD // .. or ..
pipe(f) to actorD

This example demonstrates ask together with the pipeTo pattern on futures, because this is likely to be a common combination. Please note that all of the above is completely non-blocking and asynchronous: ask produces a Future, three of which are composed into a new future using the for-comprehension and then pipeTo installs an onComplete-handler on the future to affect the submission of the aggregated Result to another actor.

Using ask will send a message to the receiving Actor as with tell, and the receiving actor must reply with sender() ! reply in order to complete the returned Future with a value. The ask operation involves creating an internal actor for handling this reply, which needs to have a timeout after which it is destroyed in order not to leak resources; see more below.

try {
  val result = operation()
  sender() ! result
} catch {
  case e: Exception =>
    sender() ! akka.actor.Status.Failure(e)
    throw e
}

If the actor does not complete the future, it will expire after the timeout period, completing it with an AskTimeoutException. The timeout is taken from one of the following locations in order of precedence:

1. explicitly given timeout as in:

import scala.concurrent.duration._
import akka.pattern.ask
val future = myActor.ask("hello")(5 seconds)

2. implicit argument of type akka.util.Timeout, e.g.

import scala.concurrent.duration._
import akka.util.Timeout
import akka.pattern.ask
implicit val timeout = Timeout(5 seconds)
val future = myActor ? "hello"

See Futures for more information on how to await or query a future.

The onComplete, onSuccess, or onFailure methods of the Future can be used to register a callback to get a notification when the Future completes, giving you a way to avoid blocking.

Forward message

You can forward a message from one actor to another. This means that the original sender address/reference is maintained even though the message is going through a 'mediator'. This can be useful when writing actors that work as routers, load-balancers, replicators etc.

target forward message

PoisonPill

You can also send an actor the akka.actor.PoisonPill message, which will stop the actor when the message is processed. PoisonPill is enqueued as ordinary messages and will be handled after messages that were already queued in the mailbox.

Graceful Stop

gracefulStop is useful if you need to wait for termination or compose ordered termination of several actors:

import akka.pattern.gracefulStop
import scala.concurrent.Await

try {
  val stopped: Future[Boolean] = gracefulStop(actorRef, 5 seconds, Manager.Shutdown)
  Await.result(stopped, 6 seconds)
  // the actor has been stopped
} catch {
  // the actor wasn't stopped within 5 seconds
  case e: akka.pattern.AskTimeoutException =>
}

object Manager {
  case object Shutdown
}

class Manager extends Actor {
  import Manager._
  val worker = context.watch(context.actorOf(Props[Cruncher], "worker"))

  def receive = {
    case "job" => worker ! "crunch"
    case Shutdown =>
      worker ! PoisonPill
      context become shuttingDown
  }

  def shuttingDown: Receive = {
    case "job" => sender() ! "service unavailable, shutting down"
    case Terminated(`worker`) =>
      context stop self
  }
}

When gracefulStop() returns successfully, the actor’s postStop() hook will have been executed: there exists a happens-before edge between the end of postStop() and the return of gracefulStop().

In the above example a custom Manager.Shutdown message is sent to the target actor to initiate the process of stopping the actor. You can use PoisonPill for this, but then you have limited possibilities to perform interactions with other actors before stopping the target actor. Simple cleanup tasks can be handled in postStop.

Upgrade

Akka supports hotswapping the Actor’s message loop (e.g. its implementation) at runtime: invoke the context.become method from within the Actor. become takes a PartialFunction[Any, Unit] that implements the new message handler. The hotswapped code is kept in a Stack which can be pushed and popped.

To hotswap the Actor behavior using become:

class HotSwapActor extends Actor {
  import context._
  def angry: Receive = {
    case "foo" => sender() ! "I am already angry?"
    case "bar" => become(happy)
  }

  def happy: Receive = {
    case "bar" => sender() ! "I am already happy :-)"
    case "foo" => become(angry)
  }

  def receive = {
    case "foo" => become(angry)
    case "bar" => become(happy)
  }
}

This variant of the become method is useful for many different things, such as to implement a Finite State Machine (FSM, for an example see Dining Hakkers). It will replace the current behavior (i.e. the top of the behavior stack), which means that you do not use unbecome, instead always the next behavior is explicitly installed.

The other way of using become does not replace but add to the top of the behavior stack. In this case care must be taken to ensure that the number of “pop” operations (i.e. unbecome) matches the number of “push” ones in the long run, otherwise this amounts to a memory leak (which is why this behavior is not the default).

case object Swap
class Swapper extends Actor {
  import context._
  val log = Logging(system, this)

  def receive = {
    case Swap =>
      log.info("Hi")
      become({
        case Swap =>
          log.info("Ho")
          unbecome() // resets the latest 'become' (just for fun)
      }, discardOld = false) // push on top instead of replace
  }
}

object SwapperApp extends App {
  val system = ActorSystem("SwapperSystem")
  val swap = system.actorOf(Props[Swapper], name = "swapper")
  swap ! Swap // logs Hi
  swap ! Swap // logs Ho
  swap ! Swap // logs Hi
  swap ! Swap // logs Ho
  swap ! Swap // logs Hi
  swap ! Swap // logs Ho
}

Encoding Scala Actors nested receives without accidentally leaking memory

See this Unnested receive example.

What happens to the Message

If an exception is thrown while a message is being processed (i.e. taken out of its mailbox and handed over to the current behavior), then this message will be lost. It is important to understand that it is not put back on the mailbox. So if you want to retry processing of a message, you need to deal with it yourself by catching the exception and retry your flow. Make sure that you put a bound on the number of retries since you don't want a system to livelock (so consuming a lot of cpu cycles without making progress). Another possibility would be to have a look at the PeekMailbox pattern.

What happens to the mailbox

If an exception is thrown while a message is being processed, nothing happens to the mailbox. If the actor is restarted, the same mailbox will be there. So all messages on that mailbox will be there as well.

What happens to the actor

If code within an actor throws an exception, that actor is suspended and the supervision process is started (see Supervision and Monitoring). Depending on the supervisor’s decision the actor is resumed (as if nothing happened), restarted (wiping out its internal state and starting from scratch) or terminated.

Initialization via constructor

Using the constructor for initialization has various benefits. First of all, it makes it possible to use val fields to store any state that does not change during the life of the actor instance, making the implementation of the actor more robust. The constructor is invoked for every incarnation of the actor, therefore the internals of the actor can always assume that proper initialization happened. This is also the drawback of this approach, as there are cases when one would like to avoid reinitializing internals on restart. For example, it is often useful to preserve child actors across restarts. The following section provides a pattern for this case.

Initialization via preStart

The method preStart() of an actor is only called once directly during the initialization of the first instance, that is, at creation of its ActorRef. In the case of restarts, preStart() is called from postRestart(), therefore if not overridden, preStart() is called on every incarnation. However, by overriding postRestart() one can disable this behavior, and ensure that there is only one call to preStart().

One useful usage of this pattern is to disable creation of new ActorRefs for children during restarts. This can be achieved by overriding preRestart():

override def preStart(): Unit = {
  // Initialize children here
}

// Overriding postRestart to disable the call to preStart()
// after restarts
override def postRestart(reason: Throwable): Unit = ()

// The default implementation of preRestart() stops all the children
// of the actor. To opt-out from stopping the children, we
// have to override preRestart()
override def preRestart(reason: Throwable, message: Option[Any]): Unit = {
  // Keep the call to postStop(), but no stopping of children
  postStop()
}

Please note, that the child actors are still restarted, but no new ActorRef is created. One can recursively apply the same principles for the children, ensuring that their preStart() method is called only at the creation of their refs.

For more information see What Restarting Means.

Initialization via message passing

There are cases when it is impossible to pass all the information needed for actor initialization in the constructor, for example in the presence of circular dependencies. In this case the actor should listen for an initialization message, and use become() or a finite state-machine state transition to encode the initialized and uninitialized states of the actor.

var initializeMe: Option[String] = None

override def receive = {
  case "init" =>
    initializeMe = Some("Up and running")
    context.become(initialized, discardOld = true)

}

def initialized: Receive = {
  case "U OK?" => initializeMe foreach { sender() ! _ }
}

If the actor may receive messages before it has been initialized, a useful tool can be the Stash to save messages until the initialization finishes, and replaying them after the actor became initialized.