Akka.NET Bootcamp Notes: Unit 1.2 - Defining and Handling Messages

In an effort to reinforce my personal learning and summarize the wonderful Akka.NET bootcamp that is provided by Petabridge, I am going to cover each unit in a series as I go through it. I will continue to edit the page if the information is incorrect or not available. Since the topics can be complex, I will provide a TL;DR at the bottom and sources for people who are interested in learning more. So let's get right into it!

What is a message

I think Petabridge did a wonderful job of explaining a message so I am just going to put what they wrote below:

"Any POCO can be a message. A message can be a string, a value like int, a type, an object that implements an interface... whatever you want.
That being said, the recommended approach is to make your own custom messages into semantically named classes, and to encapsulate any state you want inside those classes"

In terms of sending and handling messages, you use the Tell() method to send a message and how an actor handles the message is up to the developer. One thing to note is that if an actor receives a message that it cannot handle, the actor will choose to ignore it. Whether or not the ignored message is logged is dependent on the actor type (for example, an UntypedActor would not handle it unless defined but a ReceiveActor will automatically send it to Unhandled). When handling messages, the value of the sender is always in the receiving actor's Sender property.

To organize the definitions of messages, it is recommended to put it in another file and reference the messages. A good example of the layout for Messages.cs would be something like this. This is taken from Akka.Net's Message.cs

#region Neutral/system messages
/// <summary>
/// Marker class to continue processing.
/// </summary>
public class ContinueProcessing { }
#endregion

#region Success messages
/// <summary>
/// Base class for signaling that user input was valid.
/// </summary>
public class InputSuccess
{
    public InputSuccess(string reason)
    {
        Reason = reason;
    }

    public string Reason { get; private set; }
}
#endregion

#region Error messages
/// <summary>
/// Base class for signalling that user input was invalid.
/// </summary>
public class InputError
{
    public InputError(string reason)
    {
        Reason = reason;
    }

    public string Reason { get; private set; }
}

/// <summary>
/// User provided blank input.
/// </summary>
public class NullInputError : InputError
{
    public NullInputError(string reason) : base(reason) { }
}

/// <summary>
/// User provided invalid input (currently, input w/ odd # chars)
/// </summary>
public class ValidationError : InputError
{
    public ValidationError(string reason) : base(reason) { }
}
#endregion

TL;DR

Messages and their types

A message is the simplest object an actor can pass to encapsulate any state. Actors use messages to communicate between each other and how the actor handles the message is dependent on the actor (either ReceiveActor or UntypedActor). Messages should be separated into specific categorical classes.

Sources:

Petabridge: ReceiveActor
Petabridge: UntypedActor
Petabridge Akka.NET Bootcamp