Akka.NET v1.3.9 Production Release

.gitignore

@@ -206,3 +206,17 @@ build/
 /src/core/Akka.API.Tests/CoreAPISpec.ApproveStreams.received.txt
 launchSettings.json
 .idea/
+
+# GhostDoc is a C# XML comment helper
+*.[Gg]host[Dd]oc.xml
+*.[Gg]host[Dd]oc.user.dic
+
+# CodeRush
+.cr/
+
+# Visual Studio Code
+.vscode/
+
+# NDepend
+*.ndproj
+/[Nn][Dd]epend[Oo]ut

RELEASE_NOTES.md

@@ -1,3 +1,87 @@
+#### 1.3.9 August 22 2018 ####
+**Maintenance Release for Akka.NET 1.3**
+
+Akka.NET v1.3.9 features some major changes to Akka.Cluster.Sharding, additional Akka.Streams stages, and some general bug fixes across the board.
+
+**Akka.Cluster.Sharding Improvements**
+The [Akka.Cluster.Sharding documentation](http://getakka.net/articles/clustering/cluster-sharding.html#quickstart) already describes some of the major changes in Akka.NET v1.3.9, but we figured it would be worth calling special attention to those changes here.
+
+**Props Factory for Entity Actors**
+
+> In some cases, the actor may need to know the `entityId` associated with it. This can be achieved using the `entityPropsFactory` parameter to `ClusterSharding.Start` or `ClusterSharding.StartAsync`. The entity ID will be passed to the factory as a parameter, which can then be used in the creation of the actor.
+
+In addition to the existing APIs we've always had for defining sharded entities via `Props`, Akka.NET v1.3.9 introduces [a new method overload for `Start`](http://getakka.net/api/Akka.Cluster.Sharding.ClusterSharding.html#Akka_Cluster_Sharding_ClusterSharding_Start_System_String_System_Func_System_String_Akka_Actor_Props__Akka_Cluster_Sharding_ClusterShardingSettings_Akka_Cluster_Sharding_ExtractEntityId_Akka_Cluster_Sharding_ExtractShardId_) and [`StartAsync`](http://getakka.net/api/Akka.Cluster.Sharding.ClusterSharding.html#Akka_Cluster_Sharding_ClusterSharding_StartAsync_System_String_System_Func_System_String_Akka_Actor_Props__Akka_Cluster_Sharding_ClusterShardingSettings_Akka_Cluster_Sharding_ExtractEntityId_Akka_Cluster_Sharding_ExtractShardId_) which allows users to pass in the `entityId` of each entity actor as a constructor argument to those entities when they start.
+
+For example:
+
+```
+var anotherCounterShard = ClusterSharding.Get(Sys).Start(
+	                        typeName: "AnotherCounter",
+	                        entityProps: Props.Create<AnotherCounter>(),
+	                        typeName: AnotherCounter.ShardingTypeName,
+	                        entityPropsFactory: entityId => AnotherCounter.Props(entityId),
+	                        settings: ClusterShardingSettings.Create(Sys),
+	                        extractEntityId: Counter.ExtractEntityId,
+	                        extractShardId: Counter.ExtractShardId);
+```
+
+This will give you the opportunity to pass in the `entityId` for each actor as a constructor argument into the `Props` of your entity actor and possibly other use cases too. 
+
+**Improvements to Starting and Querying Existing Shard Entity Types**
+Two additional major usability improvements to Cluster.Sharding come from some API additions and changes.
+
+The first is that it's now possible to look up all of the currently registered shard types via the [`ClusterSharding.ShardTypeNames` property](http://getakka.net/api/Akka.Cluster.Sharding.ClusterSharding.html#Akka_Cluster_Sharding_ClusterSharding_ShardTypeNames). So long as a `ShardRegion` of that type has been started in the cluster, that entity type name will be added to the collection exposed by this property.
+
+The other major usability improvement is a change to the `ClusterSharding.Start` property itself. Historically, you used to have to know whether or not the node you wanted to use sharding on was going to be hosting shards (call `ClusterSharding.Start`) or simply communicated with shards hosted on a different cluster role type (call `ClusterSharding.StartProxy`). Going forward, it's safe to call `ClusterSharding.Start` on any node and you will either receive an `IActorRef` to active `ShardRegion` or a `ShardRegion` running in "proxy only" mode; this is determined by looking at the `ClusterShardingSettings` and determining if the current node is in a role that is allowed to host shards of this type.
+
+* [Akka.Cluster.Sharding: Sharding API Updates](https://github.com/akkadotnet/akka.net/pull/3524)
+* [Akka.Cluster.Sharding: sharding rebalance fix](https://github.com/akkadotnet/akka.net/pull/3518)
+* [Akka.Cluster.Sharding: log formatting fix](https://github.com/akkadotnet/akka.net/pull/3554)
+* [Akka.Cluster.Sharding: `RestartShard` escapes into userspace](https://github.com/akkadotnet/akka.net/pull/3509)
+
+**Akka.Streams Additions and Changes**
+In Akka.NET v1.3.9 we've added some new built-in stream stages and API methods designed to help improve developer productivity and ease of use.
+
+* [Akka.Streams: add CombineMaterialized method to Source](https://github.com/akkadotnet/akka.net/pull/3489)
+* [Akka.Streams: 
+KillSwitches: flow stage from CancellationToken](https://github.com/akkadotnet/akka.net/pull/3568)
+* [Akka.Streams: Port KeepAliveConcat and UnfoldFlow](https://github.com/akkadotnet/akka.net/pull/3560)
+* [Akka.Streams: Port PagedSource & IntervalBasedRateLimiter](https://github.com/akkadotnet/akka.net/pull/3570)
+
+**Other Updates, Additions, and Bugfixes**
+* [Akka.Cluster: cluster coordinated leave fix for empty cluster](https://github.com/akkadotnet/akka.net/pull/3516)
+* [Akka.Cluster.Tools: bumped ClusterClient message drop log messages from DEBUG to WARNING](https://github.com/akkadotnet/akka.net/pull/3513)
+* [Akka.Cluster.Tools: Singleton - confirm TakeOverFromMe when singleton already in oldest state](https://github.com/akkadotnet/akka.net/pull/3553)
+* [Akka.Remote: RemoteWatcher race-condition fix](https://github.com/akkadotnet/akka.net/pull/3519)
+* [Akka: fix concurrency bug in CircuitBreaker](https://github.com/akkadotnet/akka.net/pull/3505)
+* [Akka: Fixed ReceiveTimeout not triggered in some case when combined with NotInfluenceReceiveTimeout messages](https://github.com/akkadotnet/akka.net/pull/3555)
+* [Akka.Persistence: Optimized recovery](https://github.com/akkadotnet/akka.net/pull/3549)
+* [Akka.Persistence: Allow persisting events when recovery has completed](https://github.com/akkadotnet/akka.net/pull/3366)
+
+To [see the full set of changes for Akka.NET v1.3.9, click here](https://github.com/akkadotnet/akka.net/milestone/27).
+
+| COMMITS | LOC+ | LOC- | AUTHOR |
+| --- | --- | --- | --- |
+| 28 | 2448 | 5691 | Aaron Stannard |
+| 11 | 1373 | 230 | zbynek001 |
+| 8 | 4590 | 577 | Bartosz Sypytkowski |
+| 4 | 438 | 99 | Ismael Hamed |
+| 4 | 230 | 240 | Sean Gilliam |
+| 2 | 1438 | 0 | Oleksandr Bogomaz |
+| 1 | 86 | 79 | Nick Polideropoulos |
+| 1 | 78 | 0 | v1rusw0rm |
+| 1 | 4 | 4 | Joshua Garnett |
+| 1 | 32 | 17 | Jarl Sveinung Flø Rasmussen |
+| 1 | 27 | 1 | Sam13 |
+| 1 | 250 | 220 | Maxim Cherednik |
+| 1 | 184 | 124 | Josh Taylor |
+| 1 | 14 | 0 | Peter Shrosbree |
+| 1 | 1278 | 42 | Marc Piechura |
+| 1 | 1 | 1 | Vasily Kirichenko |
+| 1 | 1 | 1 | Samuel Kelemen |
+| 1 | 1 | 1 | Nyola Mike |
+| 1 | 1 | 1 | Fábio Beirão |
+
 #### 1.3.8 June 04 2018 ####
 **Maintenance Release for Akka.NET 1.3**
 

docs/articles/actors/dependency-injection.md

@@ -45,7 +45,7 @@ protected override void PreStart()
 }
 ```
 
-> [!INFO]
+> [!NOTE]
 > There is currently still an extension method available for the actor Context. `Context.DI().ActorOf<>`. However this has been officially **deprecated** and will be removed in future versions.
 
 ## Notes
@@ -77,7 +77,7 @@ guideline.
 
 Currently the following Akka.NET Dependency Injection plugins are available:
 
-## AutoFac
+### AutoFac
 
 In order to use this plugin, install the Nuget package with
 `Install-Package Akka.DI.AutoFac`, then follow the instructions:
@@ -94,7 +94,7 @@ var system = ActorSystem.Create("MySystem");
 var propsResolver = new AutoFacDependencyResolver(container, system);
 ```
 
-## CastleWindsor
+### CastleWindsor
 
 In order to use this plugin, install the Nuget package with
 `Install-Package Akka.DI.CastleWindsor`, then follow the instructions:
@@ -110,7 +110,7 @@ var system = ActorSystem.Create("MySystem");
 var propsResolver = new WindsorDependencyResolver(container, system);
 ```
 
-## Ninject
+### Ninject
 
 In order to use this plugin, install the Nuget package with
 `Install-Package Akka.DI.Ninject`, then follow the instructions:
@@ -126,14 +126,8 @@ var system = ActorSystem.Create("MySystem");
 var propsResolver = new NinjectDependencyResolver(container,system);
 ```
 
-## Other frameworks
+### Other frameworks
 
 Support for additional dependency injection frameworks may be added in the
 future, but you can easily implement your own by implementing an
-[Actor Producer Extension](DI Core).
-
-
-
-
-
-
+[Actor Producer Extension](xref:di-core).

docs/articles/actors/dispatchers.md

@@ -69,100 +69,100 @@ system.ActorOf(Props.Create<MyActor>().WithDispatcher("my-dispatcher"), "my-acto
 
 Some dispatcher configurations are available out-of-the-box for convenience. You can use them during actor deployment, [as described above](#configuring-dispatchers).
 
-* **default-dispatcher** - A configuration that uses the [ThreadPoolDispatcher](#ThreadPoolDispatcher). As the name says, this is the default dispatcher configuration used by the global dispatcher, and you don't need to define anything during deployment to use it.
-* **task-dispatcher** - A configuration that uses the [TaskDispatcher](#TaskDispatcher).
-* **default-fork-join-dispatcher** - A configuration that uses the [ForkJoinDispatcher].
-* **synchronized-dispatcher** - A configuration that uses the [SynchronizedDispatcher](#SynchronizedDispatcher).
+* **default-dispatcher** - A configuration that uses the [ThreadPoolDispatcher](#threadpooldispatcher). As the name says, this is the default dispatcher configuration used by the global dispatcher, and you don't need to define anything during deployment to use it.
+* **task-dispatcher** - A configuration that uses the [TaskDispatcher](#taskdispatcher).
+* **default-fork-join-dispatcher** - A configuration that uses the [ForkJoinDispatcher](#forkjoindispatcher).
+* **synchronized-dispatcher** - A configuration that uses the [SynchronizedDispatcher](#synchronizeddispatcher).
 
 ## Built-in Dispatchers
 
 These are the underlying dispatchers built-in to Akka.NET:
 
-* ### ThreadPoolDispatcher
+### ThreadPoolDispatcher
 
-  It schedules code to run in the [.NET Thread Pool](https://msdn.microsoft.com/en-us/library/System.Threading.ThreadPool.aspx), which is ***good enough* for most cases.**
+It schedules code to run in the [.NET Thread Pool](https://msdn.microsoft.com/en-us/library/System.Threading.ThreadPool.aspx), which is ***good enough* for most cases.**
 
-  The `type` used in the HOCON configuration for this dispatcher is just `Dispatcher`.
+The `type` used in the HOCON configuration for this dispatcher is just `Dispatcher`.
 
-  ```hocon
-  custom-dispatcher {
-    type = Dispatcher
-    throughput = 100
-  }
-  ```
+```hocon
+custom-dispatcher {
+type = Dispatcher
+throughput = 100
+}
+```
 
 > [!NOTE]
 > While each configuration can have it's own throughput settings, all dispatchers using this type will run in the same default .NET Thread Pool.
 
-* ### TaskDispatcher
+### TaskDispatcher
 
-  The TaskDispatcher uses the [TPL](https://msdn.microsoft.com/en-us/library/dd460717.aspx) infrastructure to schedule code execution. This dispatcher is very similar to the Thread PoolDispatcher, but may be used in some rare scenarios where the thread pool isn't available.
+The TaskDispatcher uses the [TPL](https://msdn.microsoft.com/en-us/library/dd460717.aspx) infrastructure to schedule code execution. This dispatcher is very similar to the Thread PoolDispatcher, but may be used in some rare scenarios where the thread pool isn't available.
 
-  ```hocon
-  custom-task-dispatcher {
-      type = TaskDispatcher
-      throughput = 100
-  }
-  ```
+```hocon
+custom-task-dispatcher {
+  type = TaskDispatcher
+  throughput = 100
+}
+```
 
-* ### PinnedDispatcher
+### PinnedDispatcher
 
-  The `PinnedDispatcher` uses a single dedicated thread to schedule code executions. Ideally, this dispatcher should be using sparingly.
+The `PinnedDispatcher` uses a single dedicated thread to schedule code executions. Ideally, this dispatcher should be using sparingly.
 
-  ```hocon
-  custom-dedicated-dispatcher {
-      type = PinnedDispatcher
-  }
-  ```
+```hocon
+custom-dedicated-dispatcher {
+  type = PinnedDispatcher
+}
+```
 
-* ### ForkJoinDispatcher
+### ForkJoinDispatcher
 
-  The ForkJoinDispatcher uses a dedicated threadpool to schedule code execution. You can use this scheduler isolate some actors from the rest of the system. Each dispatcher configuration will have it's own thread pool.
+The ForkJoinDispatcher uses a dedicated threadpool to schedule code execution. You can use this scheduler isolate some actors from the rest of the system. Each dispatcher configuration will have it's own thread pool.
 
-  This is the configuration for the [*default-fork-join-dispatcher*](#built-in-dispatcher-configurations).  You may use this as example for custom fork-join dispatchers.
+This is the configuration for the [*default-fork-join-dispatcher*](#built-in-dispatcher-configurations).  You may use this as example for custom fork-join dispatchers.
 
-  ```hocon
-  default-fork-join-dispatcher {
-      type = ForkJoinDispatcher
-      throughput = 100
-      dedicated-thread-pool {
-          thread-count = 3
-          deadlock-timeout = 3s
-          threadtype = background
-      }
+```hocon
+default-fork-join-dispatcher {
+  type = ForkJoinDispatcher
+  throughput = 100
+  dedicated-thread-pool {
+	  thread-count = 3
+	  deadlock-timeout = 3s
+	  threadtype = background
   }
-  ```
+}
+```
 
-  * `thread-count` - The number of threads dedicated to this dispatcher.
-  * `deadlock-timeout` - The amount of time to wait before considering the thread as deadlocked. By default no timeout is set, meaning code can run in the threads for as long as they need. If you set a value, once the timeout is reached the thread will be aborted and a new threads will take it's place. Set this value carefully, as very low values may cause loss of work.
-  * `threadtype` - Must be `background` or `foreground`. This setting helps define [how .NET handles](https://msdn.microsoft.com/en-us/library/system.threading.thread.isbackground.aspx) the thread.
+* `thread-count` - The number of threads dedicated to this dispatcher.
+* `deadlock-timeout` - The amount of time to wait before considering the thread as deadlocked. By default no timeout is set, meaning code can run in the threads for as long as they need. If you set a value, once the timeout is reached the thread will be aborted and a new threads will take it's place. Set this value carefully, as very low values may cause loss of work.
+* `threadtype` - Must be `background` or `foreground`. This setting helps define [how .NET handles](https://msdn.microsoft.com/en-us/library/system.threading.thread.isbackground.aspx) the thread.
 
-* ### SynchronizedDispatcher
+### SynchronizedDispatcher
 
-  The `SynchronizedDispatcher` uses the *current* [SynchronizationContext](https://msdn.microsoft.com/en-us/magazine/gg598924.aspx) to schedule executions.
+The `SynchronizedDispatcher` uses the *current* [SynchronizationContext](https://msdn.microsoft.com/en-us/magazine/gg598924.aspx) to schedule executions.
 
-  You may use this dispatcher to create actors that update UIs in a reactive manner. An application that displays real-time updates of stock prices may have a dedicated actor to update the UI controls directly for example.
+You may use this dispatcher to create actors that update UIs in a reactive manner. An application that displays real-time updates of stock prices may have a dedicated actor to update the UI controls directly for example.
 
 > [!NOTE]
 > As a general rule, actors running in this dispatcher shouldn't do much work. Avoid doing any extra work that may be done by actors running in other pools.
 
-  This is the configuration for the [*synchronized-dispatcher*](#built-in-dispatcher-configurations).  You may use this as example for custom fork-join dispatchers.
+This is the configuration for the [*synchronized-dispatcher*](#built-in-dispatcher-configurations).  You may use this as example for custom fork-join dispatchers.
 
-  ```hocon
-  synchronized-dispatcher {
-      type = "SynchronizedDispatcher"
-      throughput = 10
-  }
-  ```
+```hocon
+synchronized-dispatcher {
+  type = "SynchronizedDispatcher"
+  throughput = 10
+}
+```
 
-  In order to use this dispatcher, you must create the actor from the syncrhonization context you want to run-it. For example:
+In order to use this dispatcher, you must create the actor from the synchronization context you want to run-it. For example:
 
-  ```cs
-  private void Form1_Load(object sender, System.EventArgs e)
-  {
-      system.ActorOf(Props.Create<UIWorker>().WithDispatcher("synchronized-dispatcher"), "ui-worker");
-  }
-  ```
+```csharp
+private void Form1_Load(object sender, System.EventArgs e)
+{
+  system.ActorOf(Props.Create<UIWorker>().WithDispatcher("synchronized-dispatcher"), "ui-worker");
+}
+```
 
 #### Common Dispatcher Configuration