Creating Persistent Actors in Akka.NET with Akka.Persistence

How to Create Akka.NET Actors with Durable State

One of the most frequently asked questions I get is about how to create stateful actors that are also durable by default, meaning that the actor can recover its state from some sort of storage engine in the event that the entire Akka.NET process needs to be restarted.

Enter Akka.Persistence - an entire framework built into Akka.NET that’s designed to allow you to create actors with durable state that can be persisted on any database or storage system you want.

In this post we’re going to explore the concepts behind Akka.Persistence, how it works, and what some of the available storage options are.

Not long ago in Akka.NET-land we had an issue occur where users noticed a dramatic drop in throughput in Akka.Remote’s message processing pipeline - and to make matters worse, this occurred in a production release of AKka.NET!

Yikes, how did that happen?

The answer is that although you can use unit tests and code reviews to detect functional problems with code changes and pull requests, using those same mechanisms to detect performance problems with code is utterly ineffective. Even skilled developers who have detailed knowledge about the internals of the .NET framework and CLR are unable to correctly predict how changes to code will impact its performance.

Hence why I developed NBench - a .NET performance-testing, stress-testing, and benchmarking framework for .NET applications that works and feels a lot like a unit test.

How to Unit Test Akka.NET Actors with Akka.TestKit

An Introduction to the Akka.TestKit

In this post we introduce the Akka.TestKit module - a library that makes it easy to unit test Akka.NET actors using all of the popular .NET unit testing frameworks.

A Brief End-to-End Akka.TestKit Example

Before going deep into the TestKit, here’s an end-to-end example of what a test usually looks like.

[TestFixture] //using NUnit
public class UserIdentityActorSpecs : TestKit{

    [Test]
    public void UserIdentityActor_should_confirm_user_creation_success()
    {
        var identity = Sys.ActorOf(Props.Create(() => new UserIdentityActor()));
        identity.Tell(new UserIdentityActor.CreateUserWithValidUserInfo());
        var result = ExpectMsg<UserIdentityActor.OperationResult>().Successful;
        Assert.True(result);
    }

}

80% of your tests will be this simple: create an actor, send it a message, and expect a response back. Let’s explore how to do it.

The concepts in this post were first introduced in a talk at the 2015 Cassandra Summit.

I’ve been a .NET developer for roughly 10 years now - since the summer after my freshman year in college in 2005 I’ve been developing in Visual Studio and .NET. I’ve founded three startups on .NET, worked for Microsoft, and founded multiple successful OSS projects in .NET - I say all of this in evidence to the depth of my commitment and investment in the .NET ecosystem.

But it’s time we, the .NET community, address a major elephant in the room - .NET is, and often has been, way behind in other ecosystems in terms of overall innovation, openness to new ideas, and flexibility.

The Experience of Being a .NET Developer

.NET has been, historically, an expensive ecosystem to play in.

Because to play in it, you have to do so by Microsoft’s rules.

It's Ballmer's World, Bro

  • You have to buy a license for Visual Studio, or more likely, an MSDN subscription.
  • You have to buy a license for Windows Server.
  • You have to buy a license for Windows Server.
  • You have to develop your web applications in a framework built by Microsoft, like ASP.NET or WCF.
  • You have to host your web applications in IIS.

And the list goes on - the point being that our entire way of developing our own products depends on a single company in Redmond choosing what tools it wants to make available to us at any given time and price.

The Impact of Marrying .NET to Microsoft

I want to share with you a little story from a point in my career with Microsoft during 2010-2011. By 2011 HTML5 had become mostly standardized and its...

Stopping an actor is a routine operation that developers often find confusing. This is because each actor is like a micro process, and all interaction with an actor is asynchronous. So shutting down an actor is more complex than stopping entities in procedural code.

In this post, I’m going to review one of the common questions that I’ve heard lately:

How do I stop an actor?!

The Ways of Stopping an Actor

In short, there are three ways to stop an actor:

  1. Stop() the actor: stops the actor immediately after it finishes processing the current message.
  2. Kill the actor: this throws an ActorKilledException which will be logged and handled. The actor will stop immediately after it finishes processing the current message.
  3. Send the actor a PoisonPill: the actor will finish processing the messages currently in its mailbox, and then Stop.

Now let’s go over each in detail.

1) The Default: Stop() an Actor

This is the go-to method to stop an actor, and should be your default approach.

What Happens When I Stop() an Actor?

This is the sequence of events when you Stop() an actor:

  1. Actor receives the Stop message and suspends the actor’s Mailbox.
  2. Actor tells all its children to Stop. Stop messages propagate down the hierarchy below the actor.
  3. Actor waits for all children to stop.
  4. Actor calls PostStop lifecycle hook method for resource cleanup.
  5. Actor shuts down.

The point of this sequence is to make sure that an actor—and any hierarchy beneath it—have a clean shut down.

How Do I Use Stop()?

You Stop() an actor...

The actor model is a radically new concept for the majority of Akka.NET users, and therein lies some challenges. In this post we’re going to outline some of the common mistakes we see from beginners all the time when we take Akka.NET questions in Gitter chat, StackOverflow, and in our emails.

7. Making message classes mutable

One of the fundamental principles of designing actor-based systems is to make 100% of all message classes immutable, meaning that once you allocate an instance of that object its state can never be modified again.

The reason why immutable messages are crucial is because you can send the same message to 1000 actors concurrently and if each one of those actors makes a modification to the state of the message, all of those state changes are local to each actor.

There are no side effects to other actors when one actor modifies a message, which is why you should never need to use a lock inside an actor!

For example, this is an immutable message class:

public class Foo{ public Foo(string name, ReadOnlyList<int> points){ Name = name; Points = points; } public string Name {get; private set;} public ReadOnlyList<int> Points {get; private set;} } 

This class is immutable because:

NOTE: A lot has changed in both the .NET and Akka.NET ecosystems since this post was originally written in 2015 and we have since released an updated blog post: “Best Practices for Integrating Akka.NET with ASP.NET Core and SignalR”.

Lots of folks have been asking about Akka.NET and ASP.NET MVC integration on StackOverflow and in our Gitter chat room, so we thought it was time we created the definitive post on how to integrate these two amazing technologies together.

Note: Everything in this article also applies to Web API, Nancy, WCF, and ASP.NET WebForms.

Use Cases

So when would you want to use Akka.NET and a web framework like ASP.NET together at the same time?

Well, you might be like Joel in our “Akka.NET Goes to Wall Street” case study and need to manage concurrent reads / writes to a shared object model.

If you’re building anything resembling a chat room, web-based game, collaboration software, and more - then congratulations: managing concurrent mutations to shared state is something you’re going to have to do. Akka.NET actors are a tremendously better option than sprinkling your code with locks.

In general, what most people use Akka.NET for in the context of ASP.NET is to communicate with others network services the ASP.NET app might depend on, such as remote Windows Services via Akka.Remote and Akka.Cluster. This is especially useful if you need to do any sort of stateful web application programming, but that’s a story for a different day.

How to Start an ActorSystem in ASP.NET

If you’ve gone through Akka.NET Bootcamp, and you should if you haven’t yet, you know how to start an ActorSystem:

Our Akka.NET Virtual Meetup on August 12th was a huge success - we had about 100 users on the livestream with us and the recording of the meetup has been viewed several hundred times since.

One of the topics I covered during my presentation about using Akka.NET in production at MarkedUp was the concept of stateful applications built with actors - the idea that state can reside within your application rather than outside of it by default, and how it was this idea that made our marketing automation product possible to build.

This tweet from an attendee sums up the realization well:

Exactly right! Actors can be stateful - and that means we no longer have to factor round-trip times to SQL Server, Redis, Cassandra, or whatever into the design of our applications. The application already has the state it needs to do its job by the time a request arrives!

The Limitations of Stateless Design

The traditional way of developing web applications is stateless - and that’s a natural consequence of HTTP, itself an inherently stateless protocol.

Many people in the Akka.NET community have been asking for case studies over the last few weeks, since we shared the MarkedUp case study. There are a ton of production deployments, but getting actual case studies out always has some lag time.

To that end, I wanted to share an email case study that I received from Joel Mueller, an Akka.NET community member, that just BLEW MY MIND (reprinted with permission).

Check out Joel’s story of how Akka.NET changed the trajectory of his business, which is now a part of McGraw Hill—owners of this little thing called Standard & Poor’s—and now proud users of Akka.NET, acquiring SNL Financial for $2 billion:

SNL Financial Joel Mueller Joel Mueller, Software Architect, SNL Financial

One of the features of a larger product I’ve been working on for years is a budgeting/forecasting module for community banks. Picture an ASP.NET project that is roughly the equivalent of 200-300 interrelated Excel workbooks, using a custom mostly-Excel-compatible formula engine, lots of business rules, lots of back-end queries against both SQL and Analysis Services, and a front-end in SlickGrid that communicates with the back-end over XHR and Web API. The object model for Forecast instances is (was) stored in ASP.NET session state until changes are saved to the application database. That, of course, means one instance per session, even if two people open the same forecast.

Then, as an afterthought bullet point at the end of a list of other new features being requested, “oh by the way, can you make it work for multiple concurrent users in a single forecast, Google Docs style?”

After I was done freaking out and yelling at people, I sat down to figure out how...

This is a short update, but an important one.

The first Akka.NET Virtual Meetup will be next Wednesday, August 12 @ 18:30UTC. RSVP Here.

The first ever community-wide meetup for Akka.NET will be taking place next Wednesday, August 12. You can RSVP here.

When is the meetup?

18:30UTC on August 12, 2015. (Click here to see that in your local time zone.) We tried to find a time when people from all over the world could attend, given the geographical diversity of the Akka.NET community.

Why should I come?

I can think of a ton of reasons, but here are three:

  • To ask questions & swap ideas with other community members
  • To learn about interesting case studies or use cases for Akka that you don’t already know about
  • To have connect and have fun with other really smart developers like you!

What will be covered?

This will be a combination of speakers sharing their stories / case studies, and an open forum for Q&A with the core team. In particular, Aaron will be sharing a powerful Akka.NET case study and story. We will also:

  • providing an update on the state of the project and its trajectory
  • give timelines for upcoming Akka.NET major releases
  • have open Q&A for anyone to ask whatever they want!

Where do I join?

RSVP here. Or, if you don’t have a Google account, here is the watch page link.

See you next Wednesday!