Getting started with Akka.net

The actor model is a model for implementing highly concurrent and distributed systems. It’s implemented by frameworks/libraries such as the original Akka (for the JVM), Akka.net (the .NET implementation)and Orleans (and probably others).

See Actors for a great explanation of an implementation of an Actor object.

The general idea of the Actor model is that thread locking and other primitives are not required if changes to an object’s state can only happen on a single thread. To facilitate this, an application cannot interact with an Actor object directly, but instead passes messages to it – one might suggests this is analogous to marshaling code onto the UI thread in Windows applications (and others) or similar to using local message queues/bus such as used in Prism etc. if that helps visualize the process.

The Hello World example

As per the Akka.net website, we’ll start off with the Hello World example (from the Akka.net website).

  • Create a Console applications
  • Using Nuget, add the Akka.net package
  • Create a class named Greet, this will be used as the payload for wrapping our data that we shall pass to our Actor object. Here’s the code
    1
    2
    3
    4
    5
    6
    7
    8
    9
    public class Greet
    {
       public Greet(string who)
       {
          Who = who;
       }
     
       public string Who { get; private set; }
    }
  • Create a new class named GreetingActor. This is our Actor object that does something and will accept objects of type Greet, the code should look like this
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    public class GreetingActor : ReceiveActor
    {
       public GreetingActor()
       {
          Receive<Greet>(greet =>
             Console.WriteLine("[Thread {0}] Greeting {1}",
             Thread.CurrentThread.ManagedThreadId,
             greet.Who));
       }
    }
  • Finally we need to use the Akka.net ActorSystem to create proxies for our objects. So in the Main method we should now have
    1
    2
    3
    var system = ActorSystem.Create("MySystem");
    var greeter = system.ActorOf<GreetingActor>("greeter");
    greeter.Tell(new Greet("Hello World"));

As already mentioned, the Greet class is used to wrap the data we want to apply/send to our Actor object. It hence should be a simple immutable object which we Tell (in Akka.net parlance) to the Actor.

The Actor, GreetingActor must derive from ReceiveActor and should be set-up to Receive messages of an expected type. We can set-up a Receive for multiple types and use Tell to pass those different types as messages to our Actor.

Obviously we cannot just create the Actor object ourselves, we need for the ActorSystem to know about it and handle our interactions with it. When we create an instance of the proxy to the Actor (via ActorOf) we need to give it a unique name to differentiate the instances of the Actor object (as we don’t get an actual instance but the proxy to it). Alternatively we can pass null (or leave it to it’s default argument) if we don’t supply a name for the Actor.

Finding our Actors

We can query” our ActorSystem for an existing Actor (or multiple Actors) using the ActorSelection method. This allows us to send messages to actors across distributed systems without knowing whether they exist or not.

For example, in the below code, we’ll create three actors without caring what their names are (i.e. they’ll be generated by the ActorSystem). All we care about is that somewhere, something accepts the Greet message.

1
2
3
4
5
6
7
var system = ActorSystem.Create("MySystem");
 
system.ActorOf<GreetingActor>();
system.ActorOf<GreetingActor>();
system.ActorOf<GreetingActor>();
 
system.ActorSelection("/user/*").Tell(new Greet("Hello World"));

This code locates all /MySystem/user/* created Actors, we send a message using Tell to all Actors which support receiving such a message.

Note: The /user part of the path is automatically created for us by the ActorSystem, in this case.

If you’ve taken an instance of an Actor from the ActorOf method, you can use the following, to get the path

1
2
3
var a = system.ActorOf<GreetingActor>("a1");
 
Console.WriteLine(b.Path.ToString());

this will output akka://MySystem/user/a1 as the path to the Actor.

Stopping an Actor

Obviously, if we can create an Actor, this must (in some way or another) exist in memory or be available within our system. But what if we want to get rid of an Actor and therefore stop it listening for messages. We can use the Stop method on the ActorSystem as follows

1
2
3
var a = system.ActorOf<GreetingActor>();
 
system.Stop(a);

Stop will immediate stop an Actor, but you can also send a message to the Actor to stop which obviously may not stop the actor immediately, using the PoisonPill, like this

1
2
var a = system.ActorSelection("/user/*");
a.Tell(PoisonPill.Instance);

In this example we get all Actors and send them the PosionPill.

We can also use the Kill message, as follows

1
2
var a = system.ActorSelection("/user/*");
a.Tell(Kill.Instance);

this will result in log the ActorKilledException to denote the actors that have been killed – the documentation on this seems to suggest this is probably the only reason to use Kill over PoisonPill or Stop.

Finally we can also stop an Actor using GracefulStop

1
2
var a = system.ActorOf<GreetingActor>();
var result = a.GracefulStop(TimeSpan.FromSeconds(5));

the main use of this form of stop is that we can get a result back (eventually) via a Task. The result is a Task hence we can tell when the Actor has been shutdown. In the above the TimeSpan is a timeout.

See How to Stop an Actor… the Right Way for a fuller explanation of stopping Actors.