Typed Actors

When to use Typed Actors

Typed actors are nice for bridging between actor systems (the “inside”) and non-actor code (the “outside”), because they allow you to write normal OO-looking code on the outside. Think of them like doors: their practicality lies in interfacing between private sphere and the public, but you don’t want that many doors inside your house, do you? For a longer discussion see this blog post.

A bit more background: TypedActors can easily be abused as RPC, and that is an abstraction which is well-known to be leaky. Hence TypedActors are not what we think of first when we talk about making highly scalable concurrent software easier to write correctly. They have their niche, use them sparingly.

The tools of the trade

Before we create our first Typed Actor we should first go through the tools that we have at our disposal, it's located in akka.actor.TypedActor.

import akka.actor.TypedActor

//Returns the Typed Actor Extension
val extension = TypedActor(system) //system is an instance of ActorSystem

//Returns whether the reference is a Typed Actor Proxy or not
TypedActor(system).isTypedActor(someReference)

//Returns the backing Akka Actor behind an external Typed Actor Proxy
TypedActor(system).getActorRefFor(someReference)

//Returns the current ActorContext,
// method only valid within methods of a TypedActor implementation
val c: ActorContext = TypedActor.context

//Returns the external proxy of the current Typed Actor,
// method only valid within methods of a TypedActor implementation
val s: Squarer = TypedActor.self[Squarer]

//Returns a contextual instance of the Typed Actor Extension
//this means that if you create other Typed Actors with this,
//they will become children to the current Typed Actor.
TypedActor(TypedActor.context)

Creating Typed Actors

To create a Typed Actor you need to have one or more interfaces, and one implementation.

Our example interface:

trait Squarer {
  def squareDontCare(i: Int): Unit //fire-forget

  def square(i: Int): Future[Int] //non-blocking send-request-reply

  def squareNowPlease(i: Int): Option[Int] //blocking send-request-reply

  def squareNow(i: Int): Int //blocking send-request-reply

  @throws(classOf[Exception]) //declare it or you will get an UndeclaredThrowableException
  def squareTry(i: Int): Int //blocking send-request-reply with possible exception
}

Alright, now we've got some methods we can call, but we need to implement those in SquarerImpl.

class SquarerImpl(val name: String) extends Squarer {

  def this() = this("default")
  def squareDontCare(i: Int): Unit = i * i //Nobody cares :(

  def square(i: Int): Future[Int] = Future.successful(i * i)

  def squareNowPlease(i: Int): Option[Int] = Some(i * i)

  def squareNow(i: Int): Int = i * i

  def squareTry(i: Int): Int = throw new Exception("Catch me!")
}

Excellent, now we have an interface and an implementation of that interface, and we know how to create a Typed Actor from that, so let's look at calling these methods.

The most trivial way of creating a Typed Actor instance of our Squarer:

val mySquarer: Squarer =
  TypedActor(system).typedActorOf(TypedProps[SquarerImpl]())

First type is the type of the proxy, the second type is the type of the implementation. If you need to call a specific constructor you do it like this:

val otherSquarer: Squarer =
  TypedActor(system).typedActorOf(TypedProps(
    classOf[Squarer],
    new SquarerImpl("foo")), "name")

Since you supply a Props, you can specify which dispatcher to use, what the default timeout should be used and more.

Method dispatch semantics

Methods returning:

• Unit will be dispatched with fire-and-forget semantics, exactly like ActorRef.tell
• scala.concurrent.Future[_] will use send-request-reply semantics, exactly like ActorRef.ask
• scala.Option[_] will use send-request-reply semantics, but will block to wait for an answer, and return scala.None if no answer was produced within the timeout, or scala.Some[_] containing the result otherwise. Any exception that was thrown during this call will be rethrown.
• Any other type of value will use send-request-reply semantics, but will block to wait for an answer, throwing java.util.concurrent.TimeoutException if there was a timeout or rethrow any exception that was thrown during this call.

Messages and immutability

While Akka cannot enforce that the parameters to the methods of your Typed Actors are immutable, we strongly recommend that parameters passed are immutable.

mySquarer.squareDontCare(10)

val oSquare = mySquarer.squareNowPlease(10) //Option[Int]

val iSquare = mySquarer.squareNow(10) //Int

val fSquare = mySquarer.square(10) //A Future[Int]

Stopping Typed Actors

Since Akka's Typed Actors are backed by Akka Actors they must be stopped when they aren't needed anymore.

TypedActor(system).stop(mySquarer)

This asynchronously stops the Typed Actor associated with the specified proxy ASAP.

TypedActor(system).poisonPill(otherSquarer)

This asynchronously stops the Typed Actor associated with the specified proxy after it's done with all calls that were made prior to this call.

Typed Actor Hierarchies

Since you can obtain a contextual Typed Actor Extension by passing in an ActorContext you can create child Typed Actors by invoking typedActorOf(..) on that:

//Inside your Typed Actor
val childSquarer: Squarer =
  TypedActor(TypedActor.context).typedActorOf(TypedProps[SquarerImpl]())
//Use "childSquarer" as a Squarer

You can also create a child Typed Actor in regular Akka Actors by giving the ActorContext as an input parameter to TypedActor.get(…).

Supervisor Strategy

By having your Typed Actor implementation class implement TypedActor.Supervisor you can define the strategy to use for supervising child actors, as described in Supervision and Monitoring and Fault Tolerance.

Lifecycle callbacks

By having your Typed Actor implementation class implement any and all of the following:

• TypedActor.PreStart
• TypedActor.PostStop
• TypedActor.PreRestart
• TypedActor.PostRestart

You can hook into the lifecycle of your Typed Actor.

Receive arbitrary messages

If your implementation class of your TypedActor extends akka.actor.TypedActor.Receiver, all messages that are not MethodCall instances will be passed into the onReceive-method.

This allows you to react to DeathWatch Terminated-messages and other types of messages, e.g. when interfacing with untyped actors.

Proxying

You can use the typedActorOf that takes a TypedProps and an ActorRef to proxy the given ActorRef as a TypedActor. This is usable if you want to communicate remotely with TypedActors on other machines, just pass the ActorRef to typedActorOf.

Lookup & Remoting

Since TypedActors are backed by Akka Actors, you can use typedActorOf to proxy ActorRefs potentially residing on remote nodes.

val typedActor: Foo with Bar =
  TypedActor(system).
    typedActorOf(
      TypedProps[FooBar],
      actorRefToRemoteActor)
//Use "typedActor" as a FooBar

Supercharging

Here's an example on how you can use traits to mix in behavior in your Typed Actors.

trait Foo {
  def doFoo(times: Int): Unit = println("doFoo(" + times + ")")
}

trait Bar {
  def doBar(str: String): Future[String] =
    Future.successful(str.toUpperCase)
}

class FooBar extends Foo with Bar

val awesomeFooBar: Foo with Bar =
  TypedActor(system).typedActorOf(TypedProps[FooBar]())

awesomeFooBar.doFoo(10)
val f = awesomeFooBar.doBar("yes")

TypedActor(system).poisonPill(awesomeFooBar)

Typed Router pattern

Sometimes you want to spread messages between multiple actors. The easiest way to achieve this in Akka is to use a Router, which can implement a specific routing logic, such as smallest-mailbox or consistent-hashing etc.

Routers are not provided directly for typed actors, but it is really easy to leverage an untyped router and use a typed proxy in front of it. To showcase this let's create typed actors that assign themselves some random id, so we know that in fact, the router has sent the message to different actors:

trait HasName {
  def name(): String
}

class Named extends HasName {
  import scala.util.Random
  private val id = Random.nextInt(1024)

  def name(): String = "name-" + id
}

In order to round robin among a few instances of such actors, you can simply create a plain untyped router, and then facade it with a TypedActor like shown in the example below. This works because typed actors of course communicate using the same mechanisms as normal actors, and methods calls on them get transformed into message sends of MethodCall messages.

def namedActor(): HasName = TypedActor(system).typedActorOf(TypedProps[Named]())

// prepare routees
val routees: List[HasName] = List.fill(5) { namedActor() }
val routeePaths = routees map { r =>
  TypedActor(system).getActorRefFor(r).path.toStringWithoutAddress
}

// prepare untyped router
val router: ActorRef = system.actorOf(RoundRobinGroup(routeePaths).props())

// prepare typed proxy, forwarding MethodCall messages to `router`
val typedRouter: HasName =
  TypedActor(system).typedActorOf(TypedProps[Named](), actorRef = router)

println("actor was: " + typedRouter.name()) // name-184
println("actor was: " + typedRouter.name()) // name-753
println("actor was: " + typedRouter.name()) // name-320
println("actor was: " + typedRouter.name()) // name-164