Singleton class and settings based on current Akka Typed implementation

[ismaelhamed]

Fixes #6036

Changes

Since this already exists in Akka Typed and it isn't built on top of anything Akka-Typed specific, I put together a quick port with this functionality:

• If there already is a manager running for the given singletonName on this node, no additional manager is started.
• If there already is a proxy running for the given singletonName on this node, an IActorRef to that is returned.

Usage

var singleton = ClusterSingleton.Get(system);
var settings = ClusterSingletonSettings.Create(system).WithRole("singleton");

var proxy = singleton.Init(SingletonActor.Create(Props.Create<GlobalCounter>(), "GlobalCounter").WithSettings(settings));
proxy.Tell(Counter.Increment);

This will required a complete cluster restart though, since the names for both the ClusterSingletonManager and ClusterSingletonManagerProxy are now automatically constructed (i.e., based on the code above, the new manager will be named singletonManagerGlobalCounter and the proxy singletonProxyGlobalCounter).

Checklist

For significant changes, please ensure that the following have been completed (delete if not relevant):

• This change follows the Akka.NET API Compatibility Guidelines.
• I have reviewed my own pull request.
• Design discussion issue Akka.Cluster.Singleton: should singleton creation match what we do with ShardRegions? #6036
• Changes in public API reviewed, if any.
• I have added website documentation for this feature.

[Aaronontheweb]

This looks great @ismaelhamed - I'll review this shortly.

[ismaelhamed]

The only thing I've found with this implementation is that if the user already have a ClusterSingletonManager that is persistent, due to how the manager's name is now automatically constructed, it probably won't match the existing PersistentId in the journal/snapshot-store tables.

[ismaelhamed]

Added some test and documentation.

[Aaronontheweb]

The only thing I've found with this implementation is that if the user already have a ClusterSingletonManager that is persistent, due to how the manager's name is now automatically constructed, it probably won't match the existing PersistentId in the journal/snapshot-store tables.

What would an end-user need to do to work around that? Is there something we'll have to document or help them migrate with?

[ismaelhamed]

The only thing I've found with this implementation is that if the user already have a ClusterSingletonManager that is persistent, due to how the manager's name is now automatically constructed, it probably won't match the existing PersistentId in the journal/snapshot-store tables.

What would an end-user need to do to work around that? Is there something we'll have to document or help them migrate with?

I would probably only recommend using this newer API for brand new applications since, at the very least, a cluster restart is needed. IMO, if you already have your singletons figured out, this will only save you a few lines of code which may not be worth the effort.

[Aaronontheweb]

it probably won't match the existing PersistentId in the journal/snapshot-store tables.

so this will only affect users who are using the singleton path as the PersistenceId - not the end of the world, but I appreciate the mention here. We'll make sure to include that in the release notes.

[Aaronontheweb]

LGTM - greatly simplifies the API for managing ClusterSingletons. This is a major usability improvement.

[Aaronontheweb]

Generally, we prefer to use DocFx's [code] blocks that reference a runnable source file instead of traditional markdown blocks - see https://getakka.net/community/contributing/documentation-guidelines.html#code-samples-must-use-code-references for examples on how to do this.

Reason why we care: if the sample is updated, the documentation is also automatically updated too.

[Aaronontheweb]

I'm going to merge this in now and we can update those docs to reference your unit tests' code in a separate PR.

[Aaronontheweb]

LGTM

[Aaronontheweb]

LGTM