Defining an Actor class¶

Actor classes are implemented by extending the Actor class and implementing the receive method. The receive method should define a series of case statements (which has the type PartialFunction[Any, Unit]) that defines which messages your Actor can handle, using standard Scala pattern matching, along with the implementation of how the messages should be processed.

Here is an example:

import akka.actor.Actor
import akka.event.EventHandler

class MyActor extends Actor {
  def receive = {
    case "test" => EventHandler.info(this, "received test")
    case _ => EventHandler.info(this, "received unknown message")
  }
}

Please note that the Akka Actor receive message loop is exhaustive, which is different compared to Erlang and Scala Actors. This means that you need to provide a pattern match for all messages that it can accept and if you want to be able to handle unknown messages then you need to have a default case as in the example above.

Creating Actors¶

val myActor = Actor.actorOf[MyActor]
myActor.start()

Normally you would want to import the actorOf method like this:

import akka.actor.Actor._

val myActor = actorOf[MyActor]

To avoid prefixing it with Actor every time you use it.

You can also start it in the same statement:

val myActor = actorOf[MyActor].start()

The call to actorOf returns an instance of ActorRef. This is a handle to the Actor instance which you can use to interact with the Actor. The ActorRef is immutable and has a one to one relationship with the Actor it represents. The ActorRef is also serializable and network-aware. This means that you can serialize it, send it over the wire and use it on a remote host and it will still be representing the same Actor on the original node, across the network.

Creating Actors with non-default constructor¶

If your Actor has a constructor that takes parameters then you can’t create it using actorOf[TYPE]. Instead you can use a variant of actorOf that takes a call-by-name block in which you can create the Actor in any way you like.

Here is an example:

val a = actorOf(new MyActor(..)).start() // allows passing in arguments into the MyActor constructor

Running a block of code asynchronously¶

Here we create a light-weight actor-based thread, that can be used to spawn off a task. Code blocks spawned up like this are always implicitly started, shut down and made eligible for garbage collection. The actor that is created “under the hood” is not reachable from the outside and there is no way of sending messages to it. It being an actor is only an implementation detail. It will only run the block in an event-based thread and exit once the block has run to completion.

spawn {
  ... // do stuff
}

Fire-forget¶

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

actor ! "Hello"

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: Option[AnyRef] member field. He can use this to reply to the original sender or use the reply(message: Any) method.

If invoked from an instance that is not an Actor there will be no implicit sender passed along the message and you will get an IllegalStateException if you call self.reply(..).

Send-And-Receive-Eventually¶

Using !! will send a message to the receiving Actor asynchronously but it will wait for a reply on a Future, blocking the sender Actor until either:

• A reply is received, or
• The Future times out

You can pass an explicit time-out to the !! method and if none is specified then the default time-out defined in the sender Actor will be used.

The !! method returns an Option[Any] which will be either Some(result) if returning successfully, or None if the call timed out. Here are some examples:

val resultOption = actor !! ("Hello", 1000)
if (resultOption.isDefined) ... // handle reply
else ... // handle timeout

val result: Option[String] = actor !! "Hello"
resultOption match {
  case Some(reply) => ... // handle reply
  case None =>        ... // handle timeout
}

val result = (actor !! "Hello").getOrElse(throw new RuntimeException("TIMEOUT"))

(actor !! "Hello").foreach(result => ...) // handle result

Send-And-Receive-Future¶

Using !!! will send a message to the receiving Actor asynchronously and will return a ‘Future’:

val future = actor !!! "Hello"

See Futures (Scala) for more information.

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.

actor.forward(message)

Reply using the channel¶

If you want to have a handle to an object to whom you can reply to the message, you can use the Channel abstraction. Simply call self.channel and then you can forward that to others, store it away or otherwise until you want to reply, which you do by Channel ! response:

case request =>
    val result = process(request)
    self.channel ! result

case request =>
    friend forward self.channel

We recommend that you as first choice use the channel abstraction instead of the other ways described in the following sections.

Reply using the reply and reply_? methods¶

If you want to send a message back to the original sender of the message you just received then you can use the reply(..) method.

case request =>
  val result = process(request)
  self.reply(result)

In this case the result will be send back to the Actor that sent the request.

The reply method throws an IllegalStateException if unable to determine what to reply to, e.g. the sender is not an actor. You can also use the more forgiving reply_? method which returns true if reply was sent, and false if unable to determine what to reply to.

case request =>
  val result = process(request)
  if (self.reply_?(result)) ...// success
  else ... // handle failure

Reply using the sender reference¶

If the sender is an Actor then its reference will be implicitly passed along together with the message and will end up in the sender: Option[ActorRef] member field in the ActorRef. This means that you can use this field to send a message back to the sender.

// receiver code
case request =>
  val result = process(request)
  self.sender.get ! result

It’s important to know that sender.get will throw an exception if the sender is not defined, e.g. the Option is None. You can check if it is defined by invoking the sender.isDefined method, but a more elegant solution is to use foreach which will only be executed if the sender is defined in the sender member Option field. If it is not, then the operation in the foreach method is ignored.

// receiver code
case request =>
  val result = process(request)
  self.sender.foreach(_ ! result)

The same pattern holds for using the senderFuture in the section below.

Reply using the sender future¶

If a message was sent with the !! or !!! methods, which both implements request-reply semantics using Future’s, then you either have the option of replying using the reply method as above. This method will then resolve the Future. But you can also get a reference to the Future directly and resolve it yourself or if you would like to store it away to resolve it later, or pass it on to some other Actor to resolve it.

The reference to the Future resides in the senderFuture: Option[CompletableFuture[_]] member field in the ActorRef class.

Here is an example of how it can be used:

case request =>
  try {
    val result = process(request)
    self.senderFuture.foreach(_.completeWithResult(result))
  } catch {
    case e =>
      senderFuture.foreach(_.completeWithException(this, e))
  }

Summary of reply semantics and options¶

• self.reply(...) can be used to reply to an Actor or a Future.
• self.sender is a reference to the Actor you can reply to, if it exists
• self.senderFuture is a reference to the Future you can reply to, if it exists
• self.channel is a reference providing an abstraction to either self.sender or self.senderFuture if one is set, providing a single reference to store and reply to (the reference equivalent to the reply(...) method).
• self.sender and self.senderFuture will never be set at the same time, as there can only be one reference to accept a reply.

Upgrade¶

Akka supports hotswapping the Actor’s message loop (e.g. its implementation) at runtime. There are two ways you can do that:

• Send a HotSwap message to the Actor.
• Invoke the become method from within the Actor.

Both of these takes a ActorRef => 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 body using the HotSwap message:

actor ! HotSwap( self => {
  case message => self.reply("hotswapped body")
})

Using the HotSwap message for hotswapping has its limitations. You can not replace it with any code that uses the Actor’s self reference. If you need to do that the the become method is better.

To hotswap the Actor using become:

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

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

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

The become method is useful for many different things, but a particular nice example of it is in example where it is used to implement a Finite State Machine (FSM): Dining Hakkers

Here is another little cute example of become and unbecome in action:

case object Swap
class Swapper extends Actor {
 def receive = {
   case Swap =>
     println("Hi")
     become {
       case Swap =>
         println("Ho")
         unbecome() // resets the latest 'become' (just for fun)
     }
 }
}

val swap = actorOf[Swapper].start()

swap ! Swap // prints Hi
swap ! Swap // prints Ho
swap ! Swap // prints Hi
swap ! Swap // prints Ho
swap ! Swap // prints Hi
swap ! Swap // prints Ho

Downgrade¶

Since the hotswapped code is pushed to a Stack you can downgrade the code as well. There are two ways you can do that:

• Send the Actor a RevertHotswap message
• Invoke the unbecome method from within the Actor.

Both of these will pop the Stack and replace the Actor’s implementation with the PartialFunction[Any, Unit] that is at the top of the Stack.

Revert the Actor body using the RevertHotSwap message:

actor ! RevertHotSwap

Revert the Actor body using the unbecome method:

def receive: Receive = {
  case "revert" => unbecome()
}