Akka.net v1.0.0 Release Notes
Release Date: 2015-04-09 // about 9 years ago-
Akka.NET is officially no longer in beta status. The APIs introduced in Akka.NET v1.0 will enjoy long-term support from the Akka.NET development team and all of its professional support partners.
๐ Many breaking changes were introduced between v0.8 and v1.0 in order to provide better future extensibility and flexibility for Akka.NET, and we will outline the major changes in detail in these release notes.
๐ However, if you want full API documentation we recommend going to the following:
๐ Updated Packages with 1.0 Stable Release
๐ All of the following NuGet packages have been upgraded to 1.0 for stable release:
- Akka.NET Core
- Akka.FSharp
- Akka.Remote
- โ Akka.TestKit
- Akka.DI (dependency injection)
- ๐ฒ Akka.Loggers (logging)
๐ The following packages (and modules dependent on them) are still in pre-release status:
- Akka.Cluster
- Akka.Persistence
๐ Introducing Full Mono Support for Akka.NET
๐ป One of the biggest changes in Akka.NET v1.0 is the introduction of full Mono support across all modules; we even have Raspberry PI machines talking to laptops over Akka.Remote!
โ We've tested everything using Mono v3.12.1 across OS X and Ubuntu.
Please let us know how well Akka.NET + Mono runs on your environment!
API Changes in v1.0
All methods returning an
ActorRef
now returnIActorRef
This is the most significant breaking change introduced in AKka.NET v1.0. Rather than returning theActorRef
abstract base class from all of theActorOf
,Sender
and other methods we now return an instance of theIActorRef
interface instead.๐ This was done in order to guarantee greater future extensibility without additional breaking changes, so we decided to pay off that technical debt now that we're supporting these APIs long-term.
Here's the set of breaking changes you need to be aware of:
- ๐ Renamed:
ActorRef
-->IActorRef
ActorRef.Nobody
-->ActorRefs.Nobody
ActorRef.NoSender
-->ActorRefs.NoSender
- ๐
ActorRef
's operators==
and!=
has been removed. This means all expressions likeactorRef1 == actorRef2
must be replaced withEquals(actorRef1, actorRef2)
- ๐
Tell(object message)
, i.e. the implicit sender overload, has been moved to an extension method, and requiresusing Akka.Actor;
to be accessible. - Implicit cast from
ActorRef
toRoutee
has been replaced withRoutee.FromActorRef(actorRef)
๐
async
/await
Support๐
ReceiveActor
s now support Async/Await out of the box.public class MyActor : ReceiveActor { public MyActor() { Receive<SomeMessage>(async some => { //we can now safely use await inside this receive handler await SomeAsyncIO(some.Data); Sender.Tell(new EverythingIsAllOK()); }); } }
It is also possible to specify the behavior for the async handler, using
AsyncBehavior.Suspend
andAsyncBehavior.Reentrant
as the first argument. When usingSuspend
the normal actor semantics will be preserved, the actor will not be able to process any new messages until the current async operation is completed. While usingReentrant
will allow the actor to multiplex messages during theawait
period. This does not mean that messages are processed in parallel, we still stay true to "one message at a time", but each await continuation will be piped back to the actor as a message and continue under the actors concurrency constraint.However,
PipeTo
pattern is still the preferred way to perform async operations inside an actor, as it is more explicit and clearly states what is going on.Switchable Behaviors โก๏ธ In order to make the switchable behavior APIs more understandable for both
UntypedActor
andReceiveActor
we've updated the methods to the following:Become(newHandler); // become newHandler, without adding previous behavior to the stack (default) BecomeStacked(newHandler); // become newHandler, without adding previous behavior to the stack (default) UnbecomeStacked(); //revert to the previous behavior in the stack
The underlying behavior-switching implementation hasn't changed at all - only the names of the methods.
โฑ Scheduler APIs โฑ The
Context.System.Scheduler
API has been overhauled to be both more extensible and understandable going forward. All of the previous capabilities for theScheduler
are still available, only in different packaging than they were before.Here are the new APIs:
Context.System.Scheduler .ScheduleTellOnce(TimeSpan delay, ICanTell receiver, object message, ActorRef sender); .ScheduleTellOnce(TimeSpan delay, ICanTell receiver, object message, ActorRef sender, ICancelable cancelable); .ScheduleTellRepeatedly(TimeSpan initialDelay, TimeSpan interval, ICanTell receiver, object message, ActorRef sender); .ScheduleTellRepeatedly(TimeSpan initialDelay, TimeSpan interval, ICanTell receiver, object message, ActorRef sender, ICancelable cancelable); Context.System.Scheduler.Advanced .ScheduleOnce(TimeSpan delay, Action action); .ScheduleOnce(TimeSpan delay, Action action, ICancelable cancelable); .ScheduleRepeatedly(TimeSpan initialDelay, TimeSpan interval, Action action); .ScheduleRepeatedly(TimeSpan initialDelay, TimeSpan interval, Action action, ICancelable cancelable);
โฑ There's also a set of extension methods for specifying delays and intervals in milliseconds as well as methods for all four variants (
ScheduleTellOnceCancelable
,ScheduleTellRepeatedlyCancelable
,ScheduleOnceCancelable
,ScheduleRepeatedlyCancelable
) that creates a cancelable, schedules, and returns the cancelable.๐ Akka.NET
Config
now loaded automatically from App.config and Web.config ๐ง In previous versions Akka.NET users had to do the following to load Akka.NET HOCON configuration sections from App.config or Web.config:var section = (AkkaConfigurationSection)ConfigurationManager.GetSection("akka"); var config = section.AkkaConfig; var actorSystem = ActorSystem.Create("MySystem", config);
As of Akka.NET v1.0 this is now done for you automatically:
var actorSystem = ActorSystem.Create("MySystem"); //automatically loads App/Web.config, if any
Dispatchers Akka.NET v1.0 introduces the
ForkJoinDispatcher
as well as general purpose dispatcher re-use.Using ForkJoinDispatcher ๐ง ForkJoinDispatcher is special - it uses
Helios.Concurrency.DedicatedThreadPool
to create a dedicated set of threads for the exclusive use of the actors configured to use a particularForkJoinDispatcher
instance. All of the remoting actors depend on thedefault-remote-dispatcher
for instance.Here's how you can create your own ForkJoinDispatcher instances via Config:
myapp{ my-forkjoin-dispatcher{ type = ForkJoinDispatcher throughput = 100 dedicated-thread-pool{ #settings for Helios.DedicatedThreadPool thread-count = 3 #number of threads #deadlock-timeout = 3s #optional timeout for deadlock detection threadtype = background #values can be "background" or "foreground" } } } }
๐ง You can then use this specific
ForkJoinDispatcher
instance by configuring specific actors to use it, whether it's via config or the fluent interface onProps
:Config
akka.actor.deploy{ /myActor1{ dispatcher = myapp.my-forkjoin-dispatcher } }
Props
var actor = Sys.ActorOf(Props.Create<Foo>().WithDispatcher("myapp.my-forkjoin-dispatcher"));
๐ FluentConfiguration [REMOVED] ๐ง
FluentConfig
has been removed as we've decided to standardize on HOCON configuration, but if you still want to use the old FluentConfig bits you can find them here: https://github.com/rogeralsing/Akka.FluentConfigF# API The F# API has changed to reflect the other C# interface changes, as well as unique additions specific to F#.
โก๏ธ In addition to updating the F# API, we've also fixed a long-standing bug with being able to serialize discriminated unions over the wire. This has been resolved.
Interface Renames In order to comply with .NET naming conventions and standards, all of the following interfaces have been renamed with the
I{InterfaceName}
prefix.The following interfaces have all been renamed to include the
I
prefix:- [X]
Akka.Actor.ActorRefProvider, Akka
(Public) - [X]
Akka.Actor.ActorRefScope, Akka
(Public) - [X]
Akka.Actor.AutoReceivedMessage, Akka
(Public) - [X]
Akka.Actor.Cell, Akka
(Public) - [X]
Akka.Actor.Inboxable, Akka
(Public) - [X]
Akka.Actor.IndirectActorProducer, Akka
(Public) - [X]
Akka.Actor.Internal.ChildrenContainer, Akka
(Public) - [X]
Akka.Actor.Internal.ChildStats, Akka
(Public) - โ
[X]
Akka.Actor.Internal.InternalSupportsTestFSMRef
2, Akka` (Public) - [X]
Akka.Actor.Internal.SuspendReason+WaitingForChildren, Akka
- [X]
Akka.Actor.Internals.InitializableActor, Akka
(Public) - [X]
Akka.Actor.LocalRef, Akka
- [X]
Akka.Actor.LoggingFSM, Akka
(Public) - [X]
Akka.Actor.NoSerializationVerificationNeeded, Akka
(Public) - [X]
Akka.Actor.PossiblyHarmful, Akka
(Public) - [X]
Akka.Actor.RepointableRef, Akka
(Public) - [X]
Akka.Actor.WithBoundedStash, Akka
(Public) - [X]
Akka.Actor.WithUnboundedStash, Akka
(Public) - [X]
Akka.Dispatch.BlockingMessageQueueSemantics, Akka
(Public) - [X]
Akka.Dispatch.BoundedDequeBasedMessageQueueSemantics, Akka
(Public) - [X]
Akka.Dispatch.BoundedMessageQueueSemantics, Akka
(Public) - [X]
Akka.Dispatch.DequeBasedMailbox, Akka
(Public) - [X]
Akka.Dispatch.DequeBasedMessageQueueSemantics, Akka
(Public) - [X]
Akka.Dispatch.MessageQueues.MessageQueue, Akka
(Public) - [X]
Akka.Dispatch.MultipleConsumerSemantics, Akka
(Public) - [X]
Akka.Dispatch.RequiresMessageQueue
1, Akka` (Public) - [X]
Akka.Dispatch.Semantics, Akka
(Public) - [X]
Akka.Dispatch.SysMsg.SystemMessage, Akka
(Public) - [X]
Akka.Dispatch.UnboundedDequeBasedMessageQueueSemantics, Akka
(Public) - [X]
Akka.Dispatch.UnboundedMessageQueueSemantics, Akka
(Public) - [X]
Akka.Event.LoggingAdapter, Akka
(Public) - [X]
Akka.FluentConfigInternals, Akka
(Public) - [X]
Akka.Remote.InboundMessageDispatcher, Akka.Remote
- [X]
Akka.Remote.RemoteRef, Akka.Remote
- [X]
Akka.Routing.ConsistentHashable, Akka
(Public)
ConsistentHashRouter
andIConsistentHashable
๐ง Akka.NET v1.0 introduces the idea of virtual nodes to theConsistentHashRouter
, which are designed to provide more even distributions of hash ranges across a relatively small number of routees. You can take advantage of virtual nodes via configuration:akka.actor.deployment { /router1 { router = consistent-hashing-pool nr-of-instances = 3 virtual-nodes-factor = 17 } }
Or via code:
var router4 = Sys.ActorOf(Props.Empty.WithRouter( new ConsistentHashingGroup(new[]{c},hashMapping: hashMapping) .WithVirtualNodesFactor(5)), "router4");
ConsistentHashMapping
Delegate There are three ways to instruct a router to hash a message:- Wrap the message in a
ConsistentHashableEnvelope
; - Implement the
IConsistentHashable
interface on your message types; or - Or, write a
ConsistentHashMapper
delegate and pass it to aConsistentHashingGroup
or aConsistentHashingPool
programmatically at create time.
Here's an example, taken from the
ConsistentHashSpecs
:ConsistentHashMapping hashMapping = msg => { if (msg is Msg2) { var m2 = msg as Msg2; return m2.Key; } return null; }; var router2 = Sys.ActorOf(new ConsistentHashingPool(1, null, null, null, hashMapping: hashMapping) .Props(Props.Create<Echo>()), "router2");
Alternatively, you don't have to pass the
ConsistentHashMapping
into the constructor - you can use theWithHashMapping
fluent interface built on top of bothConsistentHashingGroup
andConsistentHashingPool
:var router2 = Sys.ActorOf(new ConsistentHashingPool(1).WithHashMapping(hashMapping) .Props(Props.Create<Echo>()), "router2");
ConsistentHashable
renamed toIConsistentHashable
Any objects you may have decorated with theConsistentHashable
interface to work withConsistentHashRouter
instances will need to implementIConsistentHashable
going forward, as all interfaces have been renamed with theI-
prefix per .NET naming conventions.๐ฆ Akka.DI.Unity NuGet Package ๐ Akka.NET now ships with dependency injection support for Unity.
๐ฆ You can install our Unity package via the following command in the NuGet package manager console:
PM> Install-Package Akka.DI.Unity