The Dangers of async void Event Handlers

When using async/await, you’ll want to use async Task methods most of the time, and use async void methods only for event handlers (see “Async/Await – Best Practices in Asynchronous Programming“, by Stephen Cleary, MSDN Magazine, March 2013).

This conventional wisdom works great if you’re building something like a WPF (GUI) application, and event handlers are invoked occasionally as a result of user interaction (e.g. user presses a button, and an event fires). However, there is another class of event handlers that are invoked as part of a dispatcher loop in a third-party library. async void can be pretty dangerous in these cases.

async void Event Handlers in RabbitMQ

Let’s take the example of RabbitMQ. We’ll set up a basic publisher and consumer. A fundamental property of message queues is that messages are delivered in order, and that’s what we expect to happen.

First, install the RabbitMQ Client library via NuGet:

Install-Package RabbitMQ.Client

Then, we can set up a basic publisher and consumer:

        static void Main(string[] args)
        {
            Console.Title = "async RabbitMQ";

            var factory = new ConnectionFactory();

            using (var connection = factory.CreateConnection())
            using (var channel = connection.CreateModel())
            {
                const string queueName = "testqueue";

                // create queue if not already there

                channel.QueueDeclare(queueName, true, false, false, null);

                // publish

                var props = channel.CreateBasicProperties();
                    
                for (int i = 0; i < 5; i++)
                {
                    var msgBytes = Encoding.UTF8.GetBytes("Message " + i);
                    channel.BasicPublish("", queueName, props, msgBytes);
                }

                // set up consumer

                var consumer = new EventingBasicConsumer(channel);
                consumer.Received += Consumer_Received;
                channel.BasicConsume("testqueue", true, consumer);

                Console.ReadLine();
            }
        }

Our consumer will call the Consumer_Received event handler whenever a message is received. This is the first version of the event handler:

        private static void Consumer_Received(object sender, BasicDeliverEventArgs e)
        {
            var body = e.Body;
            var content = Encoding.UTF8.GetString(body);

            Console.WriteLine("Began handling " + content);

            Thread.Sleep(1000);

            Console.WriteLine("Finished handling " + content);
        }

If we run this now, the messages are processed one at a time and in order just a we expect:

rabbitmq-async-sync

Now, let’s change the event handler to an asynchronous one:

        private static async void Consumer_Received(object sender, BasicDeliverEventArgs e)
        {
            var body = e.Body;
            var content = Encoding.UTF8.GetString(body);

            Console.WriteLine("Began handling " + content);

            await Task.Delay(1000);

            Console.WriteLine("Finished handling " + content);
        }

If we run this now…

rabbitmq-async-async

…we see that our concurrency and ordering guarantees have just gone out the window.

Understanding async void, Revisited

In my recent article, “In-Depth Async in Akka .NET: Why We Need PipeTo()“, I explained what happens when you call async void methods. Let’s recap that.

Say we have this program. We’re calling an async void method in a loop.

        static void Main(string[] args)
        {
            Console.Title = "async void";

            for (int i = 0; i < 5; i++)
                RunJob("Job " + i);

            Console.ReadLine();
        }

        static async void RunJob(string str)
        {
            Console.WriteLine("Start " + str);

            await Task.Delay(1000);

            Console.WriteLine("End " + str);
        }

When you call an async void method, it’s done in a fire-and-forget manner. The caller has no way of knowing whether or when the operation ended, so it just resumes execution immediately, rather than waiting for the async void method to finish. So you end up with parallel and interleaved execution such as this:

rabbitmq-async-asyncvoid

If we change RunJob() to be synchronous instead…

        static void RunJob(string str)
        {
            Console.WriteLine("Start " + str);

            Thread.Sleep(1000);

            Console.WriteLine("End " + str);
        }

…you’ll see that everything happens one at a time and in order:

rabbitmq-async-sync2

So you have to be really careful when using async void:

  1. There is no way for the caller to await completion of the method.
  2. As a result of this, async void calls are fire-and-forget.
  3. Thus it follows that async void methods (including event handlers) will execute in parallel if called in a loop.
  4. Exceptions can cause the application to crash (see the aforementioned article by Stephen Cleary for more on this).

Fixing async void event handlers

Despite these problems, if you want to await in your event handler, you have to make it async void. To prevent parallel and interleaved execution, you have to lock. However, you can’t await in a lock block, so you need to use a different synchronisation mechanism such as a semaphore.

My own Dandago.Utilities provides a ScopedAsyncLock that allows you to neatly wrap the critical section in a using block:

        private static ScopedAsyncLockFactory factory = new ScopedAsyncLockFactory();

        private static async void Consumer_Received(object sender, BasicDeliverEventArgs e)
        {
            using (var scopedLock = await factory.CreateLockAsync())
            {
                var body = e.Body;
                var content = Encoding.UTF8.GetString(body);

                Console.WriteLine("Began handling " + content);

                await Task.Delay(1000);

                Console.WriteLine("Finished handling " + content);
            }
        }

Like this, messages are consumed one at a time, and in order:

rabbitmq-async-scopedasynclock

ScopedAsyncLockFactory uses a semaphore underneath, so don’t forget to dispose it!

Getting Started with Microsoft Orleans

Microsoft Orleans is an actor model implementation for the .NET platform. The main idea of an actor model is that you distribute your computation across a number of fine-grained elements (called actors, or in Orleans, grains) which communicate between each other using message passing, and can each execute only one message at a time. This altogether avoids any need for multithreading synchronisation, and promotes distribution of computation even across physical machines.

The Orleans team have gone to great lengths to develop an API that is friendly to .NET developers, and which hides much of the complexity of building distributed systems. In this article, I hope to get you up and running with Orleans in no time.

The source code for the latter part of this article is available at the Gigi Labs BitBucket repository.

The Visual Studio Extension

If you download and install the Microsoft Orleans Tools for Visual Studio extension, you’ll get a few project templates that you can use to easily create new Orleans projects:

orleans-setup-templates

This is not strictly necessary, and I will show you how to create Orleans projects without it. But it’s quite convenient to have.

The Dev/Test Host project

A really quick way to start playing with Microsoft Orleans is to create a project of type Orleans Dev/Test Host. This is one of the project types provided by the Visual Studio extension (see previous section), and it will generate a bunch of infrastructure code (Program.cs and OrleansHostWrapper.cs) that you can use as-is. In fact, just go ahead and run it:

orleans-setup-quickrun

Just give it a few seconds; Orleans will perform some initialisation tasks, and then tell you that you have a silo running. Orleans applications typically involve a client (a regular console application, Web API, etc which communicates with Orleans) and a server (known as a silo, where all the Orleans magic happens). The Orleans Dev/Test Host is simply a way of having both in the same project.

Hello World

Among the code generated with the Orleans Dev/Test Host template, you’ll find a Main() method that looks something like this:

        static void Main(string[] args)
        {
            // The Orleans silo environment is initialized in its own app domain in order to more
            // closely emulate the distributed situation, when the client and the server cannot
            // pass data via shared memory.
            AppDomain hostDomain = AppDomain.CreateDomain("OrleansHost", null, new AppDomainSetup
            {
                AppDomainInitializer = InitSilo,
                AppDomainInitializerArguments = args,
            });

            var config = ClientConfiguration.LocalhostSilo();
            GrainClient.Initialize(config);

            // TODO: once the previous call returns, the silo is up and running.
            //       This is the place your custom logic, for example calling client logic
            //       or initializing an HTTP front end for accepting incoming requests.

            Console.WriteLine("Orleans Silo is running.\nPress Enter to terminate...");
            Console.ReadLine();

            hostDomain.DoCallBack(ShutdownSilo);
        }

We can put some of our own code instead of that comment. For this, we’ll need to create an interface:

    public interface IPerson : IGrainWithStringKey
    {
        Task SayHelloAsync(string message);
    }

One important thing to note at this stage is that interfaces used by Orleans grains must always return a Task (or Task<T>), because Orleans enforces asynchrony on its actors/grains.

Another thing to note is the IGrainWithStringKey interface we’re extending. All grains have an identifier (that’s how we’re able to find them from our code); identifiers may be of type string (as in this case), Guid, long, or a special compound type.

Next, we can create a class that implements this interface:

    public class PersonGrain : Grain, IPerson
    {
        public Task SayHelloAsync(string message)
        {
            string name = this.GetPrimaryKeyString();
            Console.WriteLine($"{name} says: {message}");

            return TaskDone.Done;
        }
    }

We’re deriving our class from Orleans’ Grain type, and we’re implementing the interface we just declared. We’re getting the grain’s identifier using the GetPrimaryKeyString() method before writing out a message. The TaskDone.Done is simply a utility task that you can return from non-async methods. Similar to the Task.CompletedTask that was introduced in .NET 4.6, this is just a convenient way to avoid doing something like Task.FromResult(0) all the time.

With that done, all we need to do is replace the comment in Main() with code such as the following:

            var joe = GrainClient.GrainFactory.GetGrain<IPerson>("Joe");
            joe.SayHelloAsync("Hello!");

This gets an instance of a grain that implements IPerson, with identifier “Joe”. The grain will be created if it doesn’t already exist; Orleans abstracts out the creation and destruction of actors. Once we have an instance, we can call methods on it. They are all asynchronous, but whether you will await them depends very much on the type of application you will be writing.

orleans-setup-hello

This is already enough for you to go on experimenting with Orleans. In the next sections (which you can safely skip if you’re just starting out), I will explain how to build out a proper project structure.

Grain Class and Grain Interface projects

There are two other project types you get with the Visual Studio extension: Orleans Grain Class Collection, and Orleans Grain Interface Collection. As your project starts to grow, you should move your grain classes and interfaces out into these project types, so that your main application consists solely of client code that interacts with Orleans via the GrainClient.GrainFactory.

NuGet packages

If you don’t want to use the Visual Studio extension, you can create regular class libraries or console applications, and just add in the necessary NuGet packages. These are the projects you need to create and the NuGet packages you need to install for each:

Purpose Type NuGet package References
Client Console Application Microsoft.Orleans.Client Interfaces
Silo Console Application Microsoft.Orleans.Server Interfaces, Grains
Grains Class Library Microsoft.Orleans.Core
Microsoft.Orleans.OrleansCodeGenerator.Build
Interfaces
Interfaces Class Library Microsoft.Orleans.Core
Microsoft.Orleans.OrleansCodeGenerator.Build

While the Microsoft.Orleans.OrleansCodeGenerator.Build package is not strictly necessary, it enables code generation for grains and grain interfaces at build time, which is better than having to do it at runtime.

A More Complete Project Structure

The rest of what we need to do to make this application work (whether using the Visual Studio extension or not) is described in the Minimal Orleans Application tutorial. I’m going to adapt it so that we have separate projects for client and silo/host (which is usually the case in real applications), to use XML configuration throughout, to fit our earlier IPerson example, and to retry to connect from the client to the silo until the silo is up.

The Silo needs the following Garbage Collection configuration to go into its App.config:

<configuration>
  <runtime>
    <gcServer enabled="true"/>
    <gcConcurrent enabled="false"/>
  </runtime>
</configuration>

Add a file called OrleansConfiguration.xml to the Silo and set it to Copy always:

<?xml version="1.0" encoding="utf-8"?>
<OrleansConfiguration xmlns="urn:orleans">
  <Globals>
    <SeedNode Address="localhost" Port="11111" />
  </Globals>
  <Defaults>
    <Networking Address="localhost" Port="11111" />
    <ProxyingGateway Address="localhost" Port="30000" />
  </Defaults>
</OrleansConfiguration>

Silo configuration needs (at a minimum) two things: an endpoint for inter-silo communication (that’s the Networking element) and an endpoint that clients outside the silo can use to talk to it (ProxyingGateway). In other words, our Client needs to talk to the Silo on port 30000.

In fact, we will now add a ClientConfiguration.xml file to the Client (set this also to Copy always):

<ClientConfiguration xmlns="urn:orleans">
  <Gateway Address="localhost" Port="30000"/>
</ClientConfiguration>

The PersonGrain class we saw earlier needs to go in the Grains project, and the IPerson interface needs to go in the Interfaces project.

Our program logic will look something like this (basically adapted from the Minimal Orleans Application tutorial, but without the client code):

    class Program
    {
        static SiloHost siloHost;

        static void Main(string[] args)
        {
            Console.Title = "Silo";

            // Orleans should run in its own AppDomain, we set it up like this
            AppDomain hostDomain = AppDomain.CreateDomain("OrleansHost", null,
                new AppDomainSetup()
                {
                    AppDomainInitializer = InitSilo
                });

            Console.WriteLine("Orleans Silo is running.\nPress Enter to terminate...");
            Console.ReadLine();

            // We do a clean shutdown in the other AppDomain
            hostDomain.DoCallBack(ShutdownSilo);
        }

        static void InitSilo(string[] args)
        {
            siloHost = new SiloHost(Dns.GetHostName());
            siloHost.LoadOrleansConfig();

            siloHost.InitializeOrleansSilo();
            var startedok = siloHost.StartOrleansSilo();
            if (!startedok)
                throw new SystemException(String.Format("Failed to start Orleans silo '{0}' as a {1} node", siloHost.Name, siloHost.Type));
        }

        static void ShutdownSilo()
        {
            if (siloHost != null)
            {
                siloHost.Dispose();
                GC.SuppressFinalize(siloHost);
                siloHost = null;
            }
        }
    }

Program logic in the Client should look something like this:

        static void Main(string[] args)
        {
            Console.Title = "Client";

            var config = ClientConfiguration.LoadFromFile("ClientConfiguration.xml");

            while (true)
            {
                try
                {
                    GrainClient.Initialize(config);
                    Console.WriteLine("Connected to silo!");

                    var friend = GrainClient.GrainFactory.GetGrain<IPerson>("Joe");
                    var result = friend.SayHelloAsync("Hello!");

                    Console.ReadLine();
                    break;
                }
                catch (SiloUnavailableException)
                {
                    Console.WriteLine("Silo not available! Retrying in 3 seconds.");
                    Thread.Sleep(3000);
                }
            }
        }

Set both the Silo and Client as startup projects, and run them. The silo will take a few seconds to initialise, and the client will keep trying to reach it until it’s up:

orleans-setup-dual

Distributed ID Generation with RustFlakes

Who would have thought that generating identifiers for data is hard? In line of business applications, most of the time it is sufficient to simply rely on a database’s autoincrement functionality to generate new primary keys. However, as a system scales and inevitably evolves into a distributed architecture, the database can quickly become a bottleneck.

idgen1_

This can easily be a problem when you’re accepting hideous amounts of user-generated content like Facebook and Twitter do. However, it is even more of a burden when you’re receiving data from a provider and need to map their IDs to yours. Each time you receive data, you need to check if their ID is mapped, and if not, you have to generate an ID – so you have to hit the database table twice. You can use a stored procedure to perform this logic in one round trip, but you’ll still have a performance problem as contention on the table increases.

idgen2_

Jeremiah Peschka’s 2012 article, “The Trouble with Keys“, is an excellent summary of why distributed ID generation is hard. In short, generating IDs in a database causes a bottleneck, whereas using something like GUIDs (aside from being longer and a little more inconvenient to pass around e.g. in a URL, and the rare but real potential for collisions) will cause performance issues at the database due to their random nature, because hard disks work best with sequential data.

The solution he proposes is to use a combination of timestamp, worker/machine identifier and sequence number:

idgen3_

The timestamp is the number of milliseconds since an arbitrary time in the past. The worker identifier is anything that is different for each running instance of the ID generator; it could be a MAC address (assuming you’re running not more than one per machine), or even just an arbitrary number. The sequence number is a small (8- or 16-bit) counter that resets every millisecond. Thus, each ID you generate will be unique at different points in time (because of the combination of timestamp and sequence number) and at different machines (because of the worker identifier). The resulting ID is a 128-bit number, which fits in the C# decimal data type and SQL Server’s DECIMAL data type.

Jeremiah Peschka created a library called Rustflakes which generates ID according to this concept. It is based on earlier implementations of the same algorithm by Twitter and Boundary. You can install Rustflakes via NuGet:

Install-Package RustFlakes

The example at the RustFlakes homepage is obsolete and does not work, but this little code will quickly get you generating IDs in no time:

            var workerId = new byte[] { 0, 1, 2, 3, 4, 5 };
            var idGenerator = new BigIntegerOxidation(workerId);
            var id = idGenerator.Oxidize();

The naming is a little bit funny, but basically you create an oxidation (ID generator) instance, and you call Oxidize() to generate the IDs.

If you want to use a MAC address for the workerId, you can use this code adapted from this StackOverflow answer:

            var macAddr = NetworkInterface.GetAllNetworkInterfaces()
                .Where(nic => nic.OperationalStatus == OperationalStatus.Up)
                .Select(nic => nic.GetPhysicalAddress().GetAddressBytes())
                .FirstOrDefault();

            var workerId = macAddr;

The BigIntegerOxidation is an ID generator that takes a 6-byte worker ID as input and generates a huge ID. However, there are others:

Generator Input (Worker) ID Output (Generated) ID Timestamp portion
BigIntegerOxidation byte[] System.Numerics.BigInteger 64-bit
DecimalOxidation uint decimal 48-bit
SqlServerBigIntOxidation ushort long 32-bit
UInt64Oxidation ushort ulong 32-bit

You can see the difference between these generators by generating a lot of IDs in a loop:

            var idGenerator = new BigIntegerOxidation(workerId);
            //var idGenerator = new DecimalOxidation(1);
            //var idGenerator = new SqlServerBigIntOxidation(1);
            //var idGenerator = new UInt64Oxidation(1);

            while (true)
            {
                var id = idGenerator.Oxidize();
                Console.WriteLine(id);
            }

Now, when you’re picking which ID generator to use, you have to be careful, because for each of these, there is a catch. The most important thing to keep in mind is that the shorter (in bits) the ID, particularly its timestamp portion, the sooner it will run out. If you run the above loop and watch the rate at which the digits turn, you can make a rough calculation of how long it will last – but keep in mind that this is relative to the epoch, which in Rustflakes is 1st January 2013.

  • BigIntegerOxidation generates numbers that internally use 13 bytes (104 bits). Although technically these should fit in a 128-bit decimal, in practice they don’t, because their actual value is greater than decimal.MaxValue. You can pass in an arbitrary epoch to the BigIntegerOxidation constructor which will make the number smaller and it will possibly convert, but you run a serious risk of exceeding decimal.MaxValue fast (the default epoch is just under 4 years old, and we don’t know how long ago decimal.MaxValue was exceeded).
  • DecimalOxidation generates 128-bit decimals, but they’re internally generated as only 96-bit values. This should give you several years of operation, but it’s less than what you’d expect with the full 128 bits.
  • UInt64Oxidation and SqlServerBigIntOxidation have only a 32-bit timestamp portion. These will likely restart in a matter of weeks.

Dependency Injection in Microsoft Orleans

The source code for this article is available at the Gigi Labs BitBucket repository.

Microsoft Orleans added support for dependency injection in version 1.1.0, which was released in December 2015. It is based on ASP .NET Core’s style of dependency injection.

To see how this works, let’s create an interface and a class that implements it. It is not important what they do, but we will use them as dependencies.

    public interface IWhatever
    {
    }

    public class Whatever : IWhatever
    {
    }

In order to set up our dependency injection bindings, we need a special startup class with a ConfigureServices() method with a predefined signature. In our case, it will look like this:

    public class Startup
    {
        public IServiceProvider ConfigureServices(IServiceCollection services)
        {
            services.AddSingleton<IWhatever, Whatever>();

            return services.BuildServiceProvider();
        }
    }

Here we are assuming that our dependency will be in singleton scope, but if you’ve used dependency injection before, you’ll know that there are other possible scopes. In fact, you’ll notice that there are different methods supporting a variety of scopes:

orleans-di-scopes

Once we have a startup class, we need to tell Orleans to use it. This can be done either in XML configuration (refer to the official documentation on Orleans DI to see how to do this) or in code as follows:

            var config = ClusterConfiguration.LocalhostPrimarySilo();
            config.UseStartupType<Startup>();

If you’re using an Orleans Dev/Test Host project type, you’ll find this cluster configuration in OrleansHostWrapper.cs. Note that dependency injection can only be done in the server (silo) and is not currently supported in the client (so you won’t find UseStartupType() on your ClientConfiguration).

Now that we have our dependency all set up, all we need is a Grain that uses it.

    public interface IHello : IGrainWithIntegerKey
    {
        Task HelloAsync();
    }

    public class HelloGrain : Grain, IHello
    {
        private IWhatever whatever;

        public HelloGrain(IWhatever whatever)
        {
            this.whatever = whatever;
        }

        public Task HelloAsync()
        {
            Console.WriteLine("Hello!");
            return TaskDone.Done;
        }
    }

In the main program, let’s create this and call it:

            var grain = GrainClient.GrainFactory.GetGrain<IHello>(0);
            grain.HelloAsync();

Now we can run the program and see that it works without problems:

orleans-di-running

We can verify that dependency injection is working by commenting out the binding configuration in the startup class. Without it, Orleans cannot activate the grain because it cannot resolve the dependency:

orleans-di-failed

Child Per Entity Pattern in Akka .NET

In Akka .NET, actors are very lightweight, and you’re encouraged to use lots of them. It’s thus very common to have a type of entity (e.g. stock symbol, event, session, etc), and an actor dedicated to each instance of that entity.

The source code for this article is available at the Gigi Labs BitBucket Repository. The project is called Entity Per Child (instead of Child Per Entity), because somehow it stuck in my head that way!

Let’s take a practical example. You have an application which receives updates for various different stocks listed on the stock exchange; each of these is represented by a symbol (e.g. MSFT represents Microsoft):

    public class StockUpdate
    {
        public string Symbol { get; }
        public decimal Price { get; }

        public StockUpdate(string symbol, decimal price)
        {
            this.Symbol = symbol;
            this.Price = price;
        }
    }

Updates are sent to a StockCoordinatorActor (for this example we’ll simulate this by just having the ActorSystem itself send these messages):

            using (var actorSystem = ActorSystem.Create("StockActorSystem"))
            {
                var props = Props.Create<StockCoordinatorActor>();
                var coord = actorSystem.ActorOf(props, "StockCoordinatorActor");

                coord.Tell(new StockUpdate("ABC", 1.20m));
                coord.Tell(new StockUpdate("XYZ", 0.59m));
                coord.Tell(new StockUpdate("ABC", 1.21m));
                coord.Tell(new StockUpdate("HBZ", 0.86m));
                coord.Tell(new StockUpdate("FUK", 1.20m));
                coord.Tell(new StockUpdate("XYZ", 0.57m));

                Console.ReadLine();
            }

Now, the StockCoordinatorActor will be responsible for spawning a child actor for each symbol, and directing messages concerning that symbol to that child actor. I see a lot of questions about how to store this mapping in a dictionary, but actually, you don’t need to. Actors can easily access information about their children, so you should use that to your advantage:

    public class StockCoordinatorActor : ReceiveActor
    {
        public StockCoordinatorActor()
        {
            this.Receive<StockUpdate>(Handle, null);
        }

        private void Handle(StockUpdate update)
        {
            var childName = update.Symbol;

            // check if a child with that name exists
            var child = Context.Child(childName);

            // if it doesn't exist, create it
            if (child == ActorRefs.Nobody)
            {
                var props = Props.Create(() => new StockActor(childName));
                child = Context.ActorOf(props, childName);
            }

            // forward the message to the child actor
            child.Tell(update.Price);
        }
    }

The child actor that handles the message will simply write out the price update in this example:

    public class StockActor : ReceiveActor
    {
        private string symbol;

        public StockActor(string symbol)
        {
            this.symbol = symbol;

            this.Receive<decimal>(Handle, null);
        }

        private void Handle(decimal price)
        {
            Console.WriteLine($"{Context.Self.Path} - {this.symbol}: {price} ");
        }
    }

Let’s run this:

akkanet-child-per-entity

I’m writing out the path of the actor that handles the update, to show that these are actually children of the StockCoordinatorActor.

If you’re dealing with a large number of actors, you might want to use a ReceiveTimeout to kill off the child actors after they’ve been idle for a period of time, to keep memory usage within reason. If a new message eventually comes in, the actor will be recreated by the same child creation logic.

This approach is called the Child Per Entity pattern. It’s actually very similar to using a consistent hashing router to assign work to a pool of dedicated actors based on an ID. With Child Per Entity, you have exactly one actor per ID, while with consistent hashing, you get actors handling multiple IDs. Due to the need to map this level of indirection, Child Per Entity is simpler to use for stateful actors.

StackExchange.Redis Connection In Short

Last year I wrote an article about the right way to set up a Redis connection using StackExchange’s Redis client library. A lot of people found this useful, but at the same time the article went into a lot of detail in order to explain the dangers of doing this wrong. Also, there is a connection string format that’s a lot more concise.

So here’s how you set up a Redis connection using StackExchange.Redis, really quickly. If you need to just try this out quickly, you can grab a copy of Redis for Windows (just remember that this is not supported for production environments).

First, install the NuGet package for the Redis client library:

Install-Package StackExchange.Redis

Then, figure out what connection you need, and build a lazy factory for it (ideally the connection string should come from a configuration file):

        private static Lazy<ConnectionMultiplexer> conn
            = new Lazy<ConnectionMultiplexer>(
                () => ConnectionMultiplexer.Connect(
                    "localhost:6379,abortConnect=false,syncTimeout=3000"));

My original article goes into detail on why this lazy construct is necessary, but it is mainly because it guarantees thread safety, so the ConnectionMultiplexer will be created only once when it is needed (which is how it’s intended to be used).

You build up a connection string using a comma-separated sequence of configuration parameters (as an alternative to ConfigurationOptions in code, which the original article used). This is more concise but also makes configuration a lot easier.

At the very least, you should have one or more endpoints that you’ll connect to (6379 is the default port in case you leave it out), abortConnect=false to automatically reconnect in case a disconnection occurs (see my original article for details on this), and a reasonable syncTimeout in case some of your Redis operations take long.

The default for syncTimeout is 1 second (i.e. 1000, because the value in milliseconds), and operations against Redis should typically be a lot less than that. But we don’t work in an ideal world, and since Redis is single-threaded, expensive application commands against Redis or even internal Redis operations can cause commands to at times exceed this threshold and result in a timeout. In such cases, you don’t want an operation to fail because of a one-off spike, so just give it a little extra (3 seconds should be reasonable). However, if you get lots of timeouts, you should review your code and look for bottlenecks or blocking operations.

Once you have the means to create a connection (as above), just get the lazy value, and from it get a handle on one of the 16 Redis databases (by default it’s database 0 if not specified):

var db = conn.Value.GetDatabase();

I’ve seen a lot of code in the past that just calls GetDatabase() all the time, for each operation. That’s fine, because the Basic Usage documentation states that:

“The object returned from GetDatabase is a cheap pass-thru object, and does not need to be stored.”

Despite this, I see no point in having an unnecessary extra level of indirection in my code, so I like to store this and work directly with it. Your mileage may vary.

Once you’ve got hold of your Redis database, you can perform your regular Redis operations on it.

            db.StringSet("x", 1);
            var x = db.StringGet("x");

Second Anniversary

Gigi Labs is 2 years old today! To date, over 150 articles have been published here, mainly on software development.

Something around 30 articles of these have been migrated from Gigi Labs’ predecessor, Programmer’s Ranch. This constitutes around one third of the Ranch’s content. Some might think that I’m merely reposting the old articles, but I am going through a lot of effort to bring them up to date and provide all my content on a single website.

Regular readers of Gigi Labs probably noticed that I am posting articles a lot less regularly than I used to, and this trend is expected to continue. The reasons for that are (1) that I am occupied with other things, especially travelling, and (2) I am learning a lot of new tech, and that takes a lot of time. But this means I’ll be able to write articles that are more useful and unique.

Gigi Labs is about quality, not quantity. I’d much rather write a unique and well-researched article once in a while than a stream of basic tutorials that you can find elsewhere on the web.

I would like to thank those who have provided comments and corrections to my articles in these 2 years. My knowledge is limited and I am more than happy to learn new things from other people’s experiences. So keep them coming!

On Akka .NET Actor Creation

Abstract: this article is a bit of a rant about how actors are created in Akka .NET, and suggests a way of making it just a little bit more manageable. This is written based on my limited knowledge of Akka .NET, and I will be more than happy to stand corrected on the matters I write about.

Actors Need Props

Creating an ActorSystem and actors in Akka .NET is one of the most basic necessities, and it is something you’ll be doing all the time. Once you have an ActorSystem, you can create actors using an IActorRefFactory implementation (i.e. the ActorSystem itself, or an actor’s Context). This requires you to use Props.

            using (var actorSystem = ActorSystem.Create("MyActorSystem"))
            {
                var props = Props.Create<MyActor>();
                var actor = actorSystem.ActorOf(props);

                Console.ReadLine();
            }

What the hell are Props?

This is explained by Unit 1 Lesson 3 of the Petabridge Akka .NET Bootcamp. Basically, the answer is something like: it’s a recipe for creating actors, but don’t worry about it for now; we’ll use it later.

As a matter of fact, it’s needed mainly for advanced scenarios such as remote deployment and clustering. Most of the time as you’re learning to use Akka .NET, you don’t really care about them.

Creating Props

There are three ways to create Props, all involving some manner of a call to Props.Create().

The first way is to give it a Type.

var props = Props.Create(typeof(MyActor));

This is discouraged by Akka .NET, because it has no type safety and in fact lets you do stupid things like this:

akka-actorcreaton-typeof

The second way is to use a generic form:

var props = Props.Create<MyActor>();

While this is encouraged in the bootcamp, I personally discourage this. This is because while it gives you type safety over the actor type, it doesn’t give you any guarantees with the parameters:

akkanet-props-generic-2

The third way is to pass in a factory method. This is a great way to create Props because it’s the only one that lets you pass dependencies into the actor’s constructor in a type-safe manner (particularly important to use constructor injection if you’re thinking of writing tests against your actors).

var props = Props.Create(() => new MyActor());

Making It Better

In reality, most of the time I don’t care about Props. So why do I have to constantly bother about them? Actually, if we take a closer look at the third way of creating Props, we can wrap them into oblivion:

akkanet-props-expression

See that generic Expression over there? That’s what we need to avoid all this madness. Based on that, we can create a generic method to take care of everything:

    public static class IActorRefFactoryExtensionscs
    {
        /// <summary>
        /// Creates an actor, creating props based on the provided
        /// actor factory method.
        /// </summary>
        /// <typeparam name="T">The actor type.</typeparam>
        /// <param name="actorRefFactory">ActorSystem or actor Context.</param>
        /// <param name="actorFactory">Actor factory method.</param>
        public static IActorRef CreateActor<T>(this IActorRefFactory actorRefFactory,
            Expression<Func<T>> actorFactory) where T : ActorBase
        {
            var props = Props.Create(actorFactory);
            var actor = actorRefFactory.ActorOf(props);
            return actor;
        }
    }

To create an actor directly from the ActorSystem, we now only need to do this:

var actor = actorSystem.CreateActor(() => new MyActor());

…and to do it from inside an actor, it’s just as easy:

var actor = Context.CreateActor(() => new MyActor());

Weird Conventions

This is where the rant begins.

Apart from all the weirdness associated with having to deal with Props in the first place, Unit 1 Lesson 3 of the Petabridge Akka .NET Bootcamp has this little gem that makes my day brighter every time I read it:

How do I make Props?

“Before we tell you how to make Props, let me tell you what NOT to do.

DO NOT TRY TO MAKE PROPS BY CALLING new Props(...). Similar to trying to make an actor by calling new MyActorClass(), this is fighting the framework and not letting Akka’s ActorSystem do its work under the hood to provide safe guarantees about actor restarts and lifecycle management.”

Here’s a similar gem from Unit 1 Lesson 1:

NOTE: When creating Props, ActorSystem, or ActorRef you will very rarely see the new keyword. These objects must be created through the factory methods built into Akka.NET. If you’re using new you might be making a mistake.”

Wait, what? These guys are telling us to call static Create() methods rather than using constructors. These are the same people who told us that using async/await in actors is bad (which has since been corrected). I don’t know, but I bet if you ask anyone who has done OOP before, they’ll tell you that if there’s a mistake, it’s in Akka .NET’s design.

But to really top it all, check out the following comment from Aaron Standard (Petabridge CTO and Akka .NET co-founder) on the Reddit thread about one of his articles (emphasis mine):

Orleans is a piss-poor implementation of the Actor model and breaks a lot of the conventions that make it powerful, aside from having an overall hideous set of programming conventions. But because MSFT released it, people will flock to it like lemmings.

“We’re going to keep working on Akka.NET because there’s a community supporting it now and because we believe in TypeSafe’s vision for actor systems.”

A case of the pot calling the kettle black? Or quoting Confucius, “Don’t complain about the snow on your neighbor’s roof when your own doorstep is unclean.”

In any case, my goal is not to start a flame war but to understand why the Akka .NET API (and codebase) is such a mess. If you look at the source code for ActorSystem, for instance, it does not do anything so particularly complicated that would justify banning constructor calls. In fact, the call to ActorSystem.Create() ends up here:

        private static ActorSystem CreateAndStartSystem(string name, Config withFallback)
        {
            var system = new ActorSystemImpl(name, withFallback);
            system.Start();
            return system;
        }

In fact, although you shouldn’t do this, this code works just as well as what we had before:

            using (var actorSystem = new ActorSystemImpl("MyActorSystem"))
            {
                actorSystem.Start();

                var actor = actorSystem.CreateActor(() => new MyActor());

                Console.ReadLine();
            }

Why is this even public such that I can call it?

Conclusion

The API provided by Akka .NET, particular in ActorSystem and actor creation, is very strange indeed. We are discouraged to do something as trivial a calling a constructor, and have to deal with Props even though we won’t need them most of the time. It is hard to speculate on why this API was written this way without having the developers provide insight on it.

At the very least, aside from pointing out these obvious flaws, this article aims to suggest best practices on how to go about creating Props, and to provide an extension method to hide the existence of Props for the majority of cases where using them directly isn’t really necessary.

Using ReceiveTimeout in Akka .NET

In Akka .NET, you can opt to receive a special message when an actor is idle (i.e. does not receive any message) for a certain period of time. This message is the ReceiveTimeout, and is particularly useful to clean up idle actors when using the Entity Per Child pattern (although various other scenarios exist where this might be used).

The source code for this article is available at the Gigi Labs BitBucket repository.

Let’s consider an ActorSystem with a single actor. The ActorSystem sends a message to this actor every few seconds, using the built-in Akka .NET Scheduler:

            using (var actorSystem = ActorSystem.Create("MyActorSystem"))
            {
                var actor = actorSystem.ActorOf(
                    Props.Create<SomeActor>(), "SomeActor");

                actorSystem.Scheduler.ScheduleTellRepeatedly(
                    initialDelay: TimeSpan.FromSeconds(1),
                    interval: TimeSpan.FromSeconds(5),
                    receiver: actor,
                    message: "Hello!",
                    sender: ActorRefs.NoSender
                );

                Console.ReadLine();
            }

In the actor itself, we call SetReceiveTimeout() in order to be able to receive a ReceiveTimeout message after the specified idle period elapses. Then, we handle the ReceiveTimeout message just like we would handle any other message.

    public class SomeActor : ReceiveActor
    {
        public SomeActor()
        {
            this.Receive<string>(Handle, null);
            this.Receive<ReceiveTimeout>(Handle, null);

            var timeout = TimeSpan.FromSeconds(3);
            this.SetReceiveTimeout(timeout);
        }

        private void Handle(string msg)
        {
            Console.WriteLine(msg);
        }

        private void Handle(ReceiveTimeout msg)
        {
            Console.WriteLine("Timeout received!");
        }
    }

If we run the application with the code we have so far, we get this:

akkanet-receivetimeout-nokill

Although we are handling the ReceiveTimeout message, we aren’t really doing anything to react to it. As the ReceiveTimeout documentation states, the ReceiveTimeout will keep firing after periods of inactivity.

To disable the ReceiveTimeout altogether, just call SetReceiveTimeout() again, passing in null:

this.SetReceiveTimeout(timeout);

You will often want to kill the actor altogether. In particular when using the Entity Per Child pattern, you will want to kill off actors that aren’t in use to keep your memory footprint low; and since you’ll have a parent actor taking care of routing messages and creating child actors as needed, any new message to that actor will cause it to be recreated.

There are different ways to kill an actor, so just pick one and use it in your ReceiveTimeout handler:

        private void Handle(ReceiveTimeout msg)
        {
            Console.WriteLine("Timeout received!");

            Context.Stop(Context.Self); // stop the actor
        }

Since we’re killing the actor now, any subsequent messages become undeliverable:

akkanet-receivetimeout-kill

WPF/MVVM DataGrid with Select All

Introduction

WPF is great to quickly build tools because it’s very versatile. In this article, we’re going to disregard the WPF DataGrid’s row selection functionality, and create a DataGrid that allows (a) selection of individual items using a checkbox, and (b) selection of all/none using a master checkbox:

wpf-dgselectall-finalresult

We’re going to do this using the Model-View-ViewModel approach, which you should be already familiar with (at least in theory) before reading on.

The source code for this article is available at the Gigi Labs BitBucket repository.

Setting up MVVM

After creating a new WPF application, install the MVVM Light Toolkit using NuGet. install the libs-only version to avoid getting a lot of extra junk in your project:

Install-Package MvvmLightLibs

Create a class called MainWindowViewModel, and make it public:

    public class MainWindowViewModel
    {
    }

In MainWindow.xaml.cs (the codebehind file for the main window), set up the view model as the DataContext:

    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();

            this.DataContext = new MainWindowViewModel();
        }
    }

A Model Object

We need to create a data object (Country in this case) whose fields will be displayed in the DataGrid. For this sort of thing, it typically needs to have:

  1. An ID. We won’t use this here, but if your data is coming from a database, you’ll usually need it.
  2. A name. This will be displayed in the DataGrid.
  3. A selection boolean. This will be used to indicate whether the item has been selected or not, and we will bind the checkbox to it.

Create a class called Country. It needs to be public, and it also needs to derive from GalaSoft.MvvmLight.ObservableObject:

    public class Country : ObservableObject

This will allow us to call the handy Set() method which handles all the INotifyPropertyChanged stuff and makes sure that WPF’s data binding engine gets notified that the property has changed, so that it can update the UI:

    public class Country : ObservableObject
    {
        private int id;
        private string name;
        private bool selected;

        public int Id
        {
            get
            {
                return this.id;
            }
            set
            {
                this.Set(() => Id, ref id, value);
            }
        }

        public string Name
        {
            get
            {
                return this.name;
            }
            set
            {
                this.Set(() => Name, ref name, value);
            }
        }

        public bool Selected
        {
            get
            {
                return this.selected;
            }
            set
            {
                this.Set(() => Selected, ref selected, value);
            }
        }

        public Country(int id, string name)
        {
            this.id = id;
            this.name = name;
        }
    }

The need to do the INotifyPropertyChanged bit prevents us from using autoproperties when implementing WPF models (and adds a significant amount of boilerplate), but the MVVM Light Toolkit reduces this overhead as much as possible.

Setting Up the DataGrid

Let’s add a list of countries to our MainWindowViewModel:

    public class MainWindowViewModel : ViewModelBase
    {
        public ObservableCollection<Country> Countries { get; }

        public MainWindowViewModel()
        {
            var countries = new Country[]
            {
                new Country(1, "Japan"),
                new Country(2, "Italy"),
                new Country(3, "England"),
                new Country(4, "Norway"),
                new Country(5, "Poland")
            };

            this.Countries = new ObservableCollection<Country>(countries);
        }
    }

Here, we’re inheriting from GalaSoft’s own ViewModelBase class, which gives us access to various methods we typically need when doing WPF with MVVM (we’ll use a couple of these later). Other than that, we’re simply creating an ObservableCollection of countries. ObservableCollection is great because it automatically notifies the UI that an item has been added or removed. Although it’s not strictly necessary here, it’s quite ubiquitous in WPF code that uses MVVM.

Next, let’s add the actual DataGrid in MainWindow.xaml:

<Window x:Class="WpfDataGridSelectAll.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:WpfDataGridSelectAll"
        mc:Ignorable="d"
        Title="Choose Countries" Height="350" Width="525">
    <DataGrid AutoGenerateColumns="False"
              ItemsSource="{Binding Path=Countries, Mode=OneWay}">
        <DataGrid.Columns>
            <DataGridTemplateColumn>
                <DataGridTemplateColumn.CellTemplate>
                    <DataTemplate>
                        <CheckBox HorizontalAlignment="Center"
                                  IsChecked="{Binding Path=Selected,
                                      UpdateSourceTrigger=PropertyChanged}" />
                    </DataTemplate>
                </DataGridTemplateColumn.CellTemplate>
            </DataGridTemplateColumn>
            <DataGridTextColumn Header="Country" Binding="{Binding Path=Name}" />
        </DataGrid.Columns>
    </DataGrid>
</Window>

Note that I could have used a DataGridCheckBoxColumn for the checkbox, but I didn’t. That’s because there’s this annoying problem where you need 2 clicks to select a checkbox in a DataGrid (one to give the row focus, and the other to check the checkbox). A simple solution for this issue is to use a DataGridTemplateColumn instead, and set UpdateSourceTrigger=PropertyChanged.

So now we have a simple DataGrid:

wpf-dgselectall-justdatagrid

Basic Select All

Let’s add a checkbox in the header of the checkbox column. This will act as the master checkbox. When you click this, it will toggle all the other checkboxes.

            <DataGridTemplateColumn>
                <DataGridTemplateColumn.Header>
                    <CheckBox IsChecked="{Binding Path=DataContext.AllSelected,
                                   UpdateSourceTrigger=PropertyChanged,
                                   RelativeSource={RelativeSource FindAncestor,
                                       AncestorType={x:Type Window}}}" />
                </DataGridTemplateColumn.Header>

The binding is a little elaborate because it needs to look for the AllSelected property (which we’ll implement next) on the MainWindowViewModel, which is actually the DataContext of the window.

Next, in the MainWindowViewModel, let’s add a property that the above binding will work with:

        private bool allSelected;

        public bool AllSelected
        {
            get
            {
                return this.allSelected;
            }
            set
            {
                this.Set(() => AllSelected, ref allSelected, value);

                foreach (var country in this.Countries)
                    country.Selected = value;
            }
        }

Note how in the setter, we’re doing some extra logic. When we change the checked value of the master checkbox, we go in and change the Selected state of all the countries accordingly.

This is enough to give us a working Select All/None toggle:

wpf-dgselectall-basic

If you click the top checkbox, all the others will be checked. And if you uncheck it, all the others will be unchecked.

Full Select All

What we did in the previous section has a flaw:

wpf-dgselectall-flaw

If you check the master checkbox, but then uncheck one of the other checkboxes, the master checkbox remains checked! And likewise, if start with nothing checked, and check all of them one by one, this is not reflected in the master checkbox.

In order to make this work properly, the individual checkboxes need a way to tell the view model that their state has changed, so that it can update the master checkbox as needed. One way to do this is to have the Country take a function that it will call whenever the selection state changes:

    public class Country : ObservableObject
    {
        private int id;
        private string name;
        private bool selected;
        private Action<bool> onSelectionChanged;

        // ...

        public bool Selected
        {
            get
            {
                return this.selected;
            }
            set
            {
                this.Set(() => Selected, ref selected, value);

                this.onSelectionChanged(value);
            }
        }

        public Country(int id, string name, Action<bool> onSelectionChanged)
        {
            this.id = id;
            this.name = name;
            this.onSelectionChanged = onSelectionChanged;
        }
    }

In the MainWindowViewModel, we now need to update the Country initialisation to pass in a method which we’ll create next:

        public MainWindowViewModel()
        {
            var countries = new Country[]
            {
                new Country(1, "Japan", OnCountrySelectionChanged),
                new Country(2, "Italy", OnCountrySelectionChanged),
                new Country(3, "England", OnCountrySelectionChanged),
                new Country(4, "Norway", OnCountrySelectionChanged),
                new Country(5, "Poland", OnCountrySelectionChanged)
            };

            this.Countries = new ObservableCollection<Country>(countries);
        }

The method that gets called whenever a checkbox changes needs to cater for two edge cases:

  1. Master checkbox is checked (i.e. all are selected), but a checkbox just got unchecked. The master checkbox needs to be unchecked.
  2. Master checkbox is unchecked (i.e. not all are selected), and all checkboxes are now checked. The master checkbox needs to be checked.

Here’s the implementation:

        private void OnCountrySelectionChanged(bool value)
        {
            if (allSelected && !value)
            { // all are selected, and one gets turned off
                allSelected = false;
                RaisePropertyChanged(() => this.AllSelected);
            }
            else if (!allSelected && this.Countries.All(c => c.Selected))
            { // last one off one gets turned on, resulting in all being selected
                allSelected = true;
                RaisePropertyChanged(() => this.AllSelected);
            }
        }

Note how we are not setting the AllSelected property directly, as that would execute the foreach statement that affects the other checkboxes. Instead, we are bypassing this by setting the backing field, and notifying WPF’s data binding engine that it needs to get the latest value for the AllSelected property.

And this gives us a fully working master checkbox:

wpf-dgselectall-finalresult

"You don't learn to walk by following rules. You learn by doing, and by falling over." — Richard Branson