Distribution 1.0.8-prerelease

.NET 7.0
This is a prerelease version of Distribution.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Distribution --version 1.0.8-prerelease
NuGet\Install-Package Distribution -Version 1.0.8-prerelease
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Distribution" Version="1.0.8-prerelease" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Distribution --version 1.0.8-prerelease
#r "nuget: Distribution, 1.0.8-prerelease"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Distribution as a Cake Addin
#addin nuget:?package=Distribution&version=1.0.8-prerelease&prerelease

// Install Distribution as a Cake Tool
#tool nuget:?package=Distribution&version=1.0.8-prerelease&prerelease

Distribution - Virtual Actor Framework

There is decent amount of actor-like frameworks, including those that support an idea of Virtual Actors, e.g. Orleans and Proto.Actor

The two mentioned frameworks are the closest to what I would like to use, but they have some drawbacks, like extra build step or inability to use different transport protocol. Below is the list of features built in the current framework. Each of them can be considered as an advantage or a disadvantage depending on specific use-case.

Features

  • Single thread
  • Zero configuration
  • Cross platform .NET 7
  • UDP broadcasting for automatic service discovery without a single point of failure
  • Peer-To-Peer network of independent nodes without consensus leaders
  • Random placement of virtual actors within a cluster
  • Ability to create multiple instances of the same type of actor using unique ID
  • Ability to override any layer, including protocol, actor placement strategy, service discovery, etc
  • No dangerous binary serialization or 3rd party serializtion libraries
  • Simple C# POCO classes for messages, no attributes or other decorators
  • Process messages using the same or multiple actor classes with [Subscription] attribute
  • Kestrel server middleware to process message queries
  • Usage of Task methods instead of FIFO loops for asynchronous communication
  • Automatic loading and mapping for actors and messages using reflection, borrowed from Mediatr framework
  • No use of locks

Nuget

Install-Package Distribution

Sample

This is an example of using actors locally within the same app.

// Define message and response format 

public class DemoMessage { public string Name { get; set; }}
public class DemoResponse { public string Data { get; set; }}

// Define actor processing this particular message   

public class DemoActor
{
  [Processor]
  public virtual Task<DemoResponse> SomeAction(DemoMessage message)
  {
    return Task.FromResult(new DemoResponse { Data = "Response from actor" });
  }
}

// Processing

public class Client
{
  async Task SendMessageToActor()
  {
    var scene = new Scene();
    var message = new DemoMessage { Name = "Message to actor" };
    var response = await scene.Send<DemoResponse>("Custom Actor ID", message);

    Console.WriteLine("Response : " + response.Data);
  }
}

An example with a distributed network of actors in the cluster is a bit more complex and can be found in the Samples directory.

Disclaimer

In order to keep things simple and flexible, the main focus was on simplicity and scalability rather than performance.

Notes

Practically all parts of this framework use the most basic implementation of each layer meaning that it's a general purpose implementation that may need to be extended to solve more specific problems.

  1. HTTP and JSON are somewhat slow, but were chosen for communication instead of sockets to make it easier to build a network of a million of nodes without a need to manage permanent connections between peers.
  2. UDP broadcasting can detect nodes within the same network segment. To make peer discovery global there will be a need for services like Consul or manual NAT traversing.
  3. There is a heavy use of reflection for mapping between actors and messages. No benchmarks, but switching to compiled delegates may improve latency.

Improvements

Even though existing modules are the most basic at the core, they can be easily extended or overridden to achieve more specific goals.

  1. When there is no requirement to have millions of nodes, it's possible to implement ICommunicator and use sockets with Message Pack or Flat Buffers for lower latency.
  2. Peer discovery is encapsulated inside of the Beacon class. When needed, it's easy to override any of its method or implement IBeacon to use it with Consul or some other service discovery tool.
Product Versions
.NET net7.0
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.0-prerelease 31 11/6/2022
1.0.9-prerelease 32 11/6/2022
1.0.8-prerelease 65 6/9/2022
1.0.7-prerelease 66 6/7/2022
1.0.6-prerelease 66 6/3/2022
1.0.5-prerelease 66 5/31/2022
1.0.3-prerelease 70 4/4/2022
1.0.2-prerelease 93 4/3/2022