akkadotnet / akka.net

Canonical actor model implementation for .NET with local + distributed actors in C# and F#.

Akka.NET

Akka.NET is a .NET port of the popular Akka project from the Scala / Java community. We are an idiomatic .NET implementation of the actor model built on top of the .NET Common Language Runtime.

• Website: https://getakka.net/
• Twitter 🐦: AkkaDotNet
• Discussions 📣: Akka.NET GitHub Discussions
• Chat 💬: Akka.NET on Discord
• StackOverflow ✔️: Akka.NET on StackOverflow

Akka.NET is a .NET Foundation project.

How is Akka.NET Used?

Akka.NET can be used in-process or inside large, distributed real-time systems; we support a wide variety of use cases.

Akka.NET can be used to solve the following types of problems:

1. Concurrency - Akka.NET actors only process messages one-at-a-time and they do so in first in, first out (FIFO) order; this means that any application state internal to an actor is automatically thread-safe without having to use locks or any other shared-memory synchronization mechanisms.
2. Stream Processing - Akka.NET actors and Akka.Streams make it easy to build streaming applications, used for processing incoming streams of data or incoming streams of live events such as UI or network events inside native applications.
3. Event-Driven Programming - actors make it easy to build event-driven applications, as actors' message-processing routines naturally express these types of designs.
4. Event Sourcing and CQRS - Akka.Persistence, used by actors to make their state re-entrant and recoverable across restarts or migrations between nodes, natively supports event sourcing. Akka.Persistence.Query can be used to compute CQRS-style projections and materialized views from Akka.Persistence data.
5. Location Transparency - Akka.Remote makes it simple for actors in remote processes to transparently communicate with each other.
6. Highly Available, Fault-Tolerant Distributed Systems - Akka.Cluster, Akka.Cluster.Sharding, and other tools built on top of Akka.Cluster make it possible to build highly available and fault-tolerant distributed systems by leveraging peer-to-peer programming models with topology-aware message routing and distribution.
7. Low Latency, High Throughput - Akka.NET aims to be low latency and high throughput, processing 10s millions of messages per second in-memory and hundreds of thousands of messages per second over remote connections.

Where Can I Learn Akka.NET?

You can start by taking the Akka.NET Bootcamp, but there are many other great learning resources for Akka.NET Online.

• Petabridge's Akka.NET Videos on YouTube
• ".NET Conf - When and How to Use the Actor Model An Introduction to Akka.NET Actors"
• Reactive Applications with Akka.NET
• Akka.NET Succinctly

Build Status

Stage	Status
Build
NuGet Pack
.NET Framework Unit Tests
.NET 7 Unit Tests (Windows)
.NET 7 Unit Tests (Linux)
.NET 7 MultiNode Tests (Windows)
.NET 7 MultiNode Tests (Linux)
Docs

Install Akka.NET via NuGet

If you want to include Akka.NET in your project, you can install it directly from NuGet

To install Akka.NET Distributed Actor Framework, run the following command in the Package Manager Console

PM> Install-Package Akka.Hosting

Akka.Hosting includes the base Akka NuGet package and also provides an easy interface to integrate Akka.NET with the most-used parts of the Microsoft.Extensions ecosystem: Configuration, Logging, Hosting, and DependencyInjection. We encourage developers to adopt it.

And if you need F# support:

PM> Install-Package Akka.FSharp

Akka.NET Project Templates

To create your own Akka.NET projects using our templates (Akka.Templates), install them via the dotnet CLI:

dotnet new install "Akka.Templates::*"

This will make our templates available via dotnet new on the CLI and as new project templates inside any .NET IDE such as Visual Studio or JetBrains Rider. You can view the full list of templates included in our package here: https://github.com/akkadotnet/akkadotnet-templates#available-templates

Builds

Please see Building Akka.NET.

To access nightly Akka.NET builds, please see the instructions here.

Support

If you need help getting started with Akka.NET, there's a number of great community resources online:

• Subscribe to the Akka.NET project feed on Twitter: https://twitter.com/AkkaDotNet (@AkkaDotNet)
• Join the Akka.NET Discord: https://discord.gg/GSCfPwhbWP
• Ask Akka.NET questions on Stack Overflow: http://stackoverflow.com/questions/tagged/akka.net

If you and your company are interested in getting professional Akka.NET support, you can contact Petabridge for dedicated Akka.NET support.

akka.net's Issues

DeadLettersSpec

Port the test spec for DeadLetters

Faster Scheduling of Mailboxes

Make the default dispatcher use the new NaiveThreadPool for scheduling.
Should give a perf boost about * 2-3 times

Add Serialize all messages/creators

http://doc.akka.io/docs/akka/2.0.1/scala/serialization.html

""""
Verification
If you want to verify that your messages are serializable you can enable the following config option:

val config = ConfigFactory.parseString("""
akka {
actor {
serialize-messages = on
}
}
""")

When a call to ActorRef.Post occurs, the passed message needs to be serialized and then deserialized directly before put on the mailbox queue.

This feature is to ensure that your messages are immutable,(in test environments) not passing mutable data around.

There is a setting for this in the ActorSystem.Settings

ActorPathSpec

Port the ActorPathSpec to ensure that ActorPath behaves according to the akka spec

ActorRefSpec

Port the ActorRefSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

Integrating Pigeon.Configuration with Web/App.config?

@rogeralsing I'm in the process of integrating Pigeon into a couple of our ASP.NET MVC-based services this week - I'm building an Actor system that is hosted inside an IIS process.

It will accept messages via Remote actors (and I'm going to use that as an opportunity to work on some of the Remote actor issues assigned to me,) but also directly through HTTP requests made to ASP.NET MVC controllers.

This prompted me to ask - going forward, how should we try to reconcile the traditional Web.config model with the Akka-style config model? I can stick my Akka configuration in AppSettings I suppose in the meantime.

We can either keep our configuration model totally separate, or maybe find a happy medium?

EventBusSpec

Port the EventBusSpec

Support full startup flow of actors

We need to support full startup message flow for actors.
Watching children etc.

ActorSystemSpec

Port the ActorSystemSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

Move to an organization?

I've noticed that community projects under an appropriate organization (e.g. github.com/fsprojects) seem to get more contributors and a sense of mutual contribution/ownership.

So I'm wondering whether this project could move to an akkanet organization? Or perhaps start a "dotnetprojects" community space akin to the "fsprojects" space - which has proved very successful at bringing F# community projects together?

Just an idea, you may have plans like this in any case.

Buffer RemoteActorRef messages

We should add support to buffer messages sent to an RemoteActorRef so that we can pass a single larger message to the remote system instead of multiple single messages.

If the RemoteActorRef has it's own mailbox processor.
We can pull multiple messages from that once it runs.
Put those in a Batch message and pass to the remote system

Actor deployment using config and code

Add support for deploying actors via code and config.

Add Akka cluster support

This is a big undertaking in and of itself, but it's a massively useful feature when used in combination with Remote Actors:

http://doc.akka.io/docs/akka/2.2.3/common/cluster.html

Akka is still working on implementing some parts of their own clustering roadmap, but I think it would be a useful goal to have in mind from the beginning.

Extend Ask support

We should extend the ask support to allow passing a timeout param (Timespan and milliseconds)
We should also allow asking for a specific type.

Add custom TaskScheduler for async await operations within an actor

If one add async code within an actor, e.g an "await" call.
We can not currently guarantee that the actor executes within its concurrency boundarys.
the only way to do this is to marshall a TaskCompletionSource through the actors mailbox and thus force the completion to be set within the actors message handler.

So for the ask support, this works, we do this in ActorRef.Ask(object message)

However, if we do e.g. async IO or any other async await from within an actor, this will not be guaranteed.

I beleive this is possible to resolve by writing a custom task scheduler or whatever it is called, and I'm pretty sure I saw one in Helios(?) cc. @Aaronontheweb

Thoughts?

DeployerSpec

Port the DeployerSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

Need to make ActorPath behavior consistent with Akka

Couple of examples from integrating Pigeon today:

Absolute paths should implicitly have /user/ appended to the front
Any absolute path lookup made by a user-defined Actor should implicitly have /user/ appended to the front of it.

For instance, System.ActorSelection("/myrootactor/mychildactor/") is a valid absolute path to the user-defined actor at akka://{system}/user/myrootactor/mychildactor, as indicated by the leading slash.

Need to make it add some utilities to make it easy to define paths
In particular, we need to make it easy to define valid relative Actor paths. Probably can do this inside a simple static class (like PathUtils in Akka) and use it help users make sure their ActorPaths are formatted correctly.

Release strategy

We should decide on a release strategy, milestones, versions etc.
@Aaronontheweb ideas?

RoutingSpec

Need to begin porting the routing specs and tests over from Akka

https://github.com/akka/akka/blob/master/akka-actor-tests/src/test/scala/akka/routing/RoutingSpec.scala

Proposal: instead of returning null during missing ActorRef lookups, return Nobody instead

And pipe all messages directly to DeadLetters - Akka returns a reference to a static ActorRef.NoSender instance and this is the same idea. That way, rather than throw an exception, messages just get piped into the undeliverables pile.

Thoughts?

Add RemoteDaemon

The remote daemon is responsible for creatng new actors on request from a remote system.

In real Akka, this is implemented using a VirtualPathContainer.
This means that when a remote system tells the daemon to create a given actor. it will be created with the path that is requested, but placed under the /remote/* path.

so if system1 requests a new instance of system1/user/foo/bar to be created remotely.
it will be created as system2/remote/foo/bar

Thus, the "remote" actor/daemon needs to be able to create children with paths instead of names.
And those paths should be unrelated also.
system2/remote/foo is not the parent of system2/remote/foo/bar
they both are children of remote

Make ActorRef serializable in messages

ActorRef's can currently only be passed to remote systems via sender and recipient.
If a message contains an actorref, it will fail.
ActorRefs needs to be serializable.

Note, each kind of actorref needs to be serializable, LocalActorRef, RemoteActorRef etc.
I guess needs custom code for each kind of serializer (?) since each ref is context bound, it only means something within the context of a system.

DeathWatchSpec

Port the DeathWatchSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

EventStreamSpec

Port the EventStreamSpec

Need to decide on an OSS license for Pigeon

In order to use Pigeon in production, we'll need to settle on an acceptable OSS license.

My personal preference is a permissive license like Apache v2, but I'm open to alternatives.

Add ActorRefProvider functionallity

There is currently only one ActorRefProvider, this should be extended to behave as real Akka with a RemoteActorRefProvider.

Currently, remoting is implemented as an extension. this should be changed.
The actor system should pick the setting from the config and apply the correct actor ref provider using this.

Add descriptive ToString for all built in messages

Add descriptive ToString() impl for both SystemMessage and AutoReceived messages.

More examples

We need more examples.

• Distributed Fractal renderer
• More complete Chat Client/Server
• Port Akka examples - http://doc.akka.io/docs/akka/1.3.1/additional/external-sample-projects.html

SerializationSpec

Port the SerializationSpec to verify that serialization behaves according to the spec.

Add Router pool support

We need to add router pool, e.g. RandomPool, RoundRobinPool

BroadcastRouter

Need to implement both BroadcastPool and BroadcastGroup routers

https://github.com/akka/akka/blob/master/akka-actor/src/main/scala/akka/routing/Broadcast.scala

RemoteDeploy\Shared\Shared.csproj missing

Just ran into the following issue when making a NuGet build:

Build FAILED.

"D:\Repositories\Pigeon\Pigeon.sln" (Clean;Build target) (1) ->
(Clean target) ->
  D:\Repositories\Pigeon\Pigeon.sln.metaproj : error MSB3202: The project file "D:\Repositories\Pigeon\Examples\RemoteD
eploy\Shared\Shared.csproj" was not found. [D:\Repositories\Pigeon\Pigeon.sln]

    0 Warning(s)
    1 Error(s)

Looks like there's a missing .csproj file from the repository - could we add this?

ActorLifeCycleSpec

Port the ActorLifeCycleSpec.

EventStreamLogger

@rogeralsing I'd like to be able to expose the logger directly to user Actors - currently I'm having my actors write directly to the event stream and I'm using a specialized Actor to push all of the log messages onto a debug screen for my team using SignalR.

Roger, was planning on adding a System-wide LoggingAdapter that writes directly to the event stream and make that accessible inside the ActorContext but I'm not entirely sure how you're using Logging adapters currently. Is this something you want to make configurable at the ActorSystem level?

Better remoting support

• Add support for more protocols, Tcp, Udp(?), Http
• Support serialization using protobuff

Routers

Add support for Akka like Routers

LocalActorRef.Stop() and Context.Stop(ActorRef) yield different results for child actors

When attempting to stop a child Actor, there are a couple of different methods of doing it.

Calling LocalActorRef.Stop() on the child's ActorRef doesn't end the parent actor's supervision of the child, but Context.Stop(ActorRef) does - need to implement some messaging to tell the parent to stop watching the child regardless of how it died, so long as it was gracefully terminated.

HotSwapSpec

Port the HotSwapSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

Support full termination flow of actors

• Add full support for termination, use the same messages and sequences of messages as Akka does

Fast polymorphic serializer with support for non public constructors and setters?

It turns out that fastJSON that we use as the default serialzier for remoting does not play well with non public constructors/setters on objects.
We need an alternative to this to enable better message design.
We also need support for polymorphism (for polymorphic messages) and custom type handlers(for serializing ActorRefs)

Any ideas?
cc. @Aaronontheweb

Add Consistent Hashing router support

http://doc.akka.io/api/akka/snapshot/index.html#akka.routing.ConsistentHashingRouter

There is 3 ways to define what data to use for the consistent hash key.

1. You can define hashMapping / withHashMapper of the router to map incoming messages to their consistent hash key. This makes the decision transparent for the sender.
2. The messages may implement akka.routing.ConsistentHashingRouter.ConsistentHashable. The key is part of the message and it's convenient to define it together with the message definition.
3. The messages can be be wrapped in a akka.routing.ConsistentHashingRouter.ConsistentHashableEnvelope to define what data to use for the consistent hash key. The sender knows the key to use.

Slf4NetSpec

Port the slf4jSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

Mono support

We need to ensure that Akka.NET works on mono.

Idea: Actor cluster

@rogeralsing separate from the notion of clustering Akka servers, I had an idea for combining Routing and Broadcast Actors into a suite designed for bursty workloads.

An Actor cluster: essentially it's a router that can have new Actors join and previous Actors leave when doing processing. For instance, during peak loads I might need 100+ database request-handler Actors per machine, but only 5-10 during regular loads.

The Actor cluster is itself an Actor, and it implements a built-in Router. it can receive special messages to create new Actors under its management and if a child actor terminates then it leaves the cluster.

I've built something like this into my own user code - does this seem like something worth including in the framework itself or is it too domain-specific?

Lowest .NET version?

We need to decide what .NET versions we support.
cc. @Aaronontheweb

Rewrite ActorSelection

Actor selection is not implemented correctly.
Akka uses an ActorSelection type with an "Anchor" actorref and a list of string elements describing the navigation/selection.
The resolution is done lazily and not directly.

Better F# API

Scala uses some special syntax for declaring actors.
We should investigate how an idiomatic F# actor would look using the Pigeon/Akka concepts.

LocalActorRefProviderSpec

Port the LocalActorRefProviderSpec.scala to C#
(Download the Scala source code from https://github.com/akka/akka)

PS.
ActorFor is deprecated and thus we should not support those tests

Add custom loggers

The LoggerAdapter should be made abstract.
We should provide a few out of the box loggers for Console, Debug, Trace , whatever.
And some external addons for mainstream logging libs.

Add log/debug functionallity

The ActorSystem.Settings class contains a few settings related to logging in various conditions.
These should be used to trigger logging.
See real Akka code for each of those Settings prop