Receptionist docs and examples
This commit is contained in:
Christopher Batey
Konrad `ktoso` Malawski
parent
cf455f3c11
commit
f17dc5c7f7
24 changed files with 758 additions and 168 deletions
56
akka-docs/src/main/paradox/actor-discovery-typed.md
Normal file
56
akka-docs/src/main/paradox/actor-discovery-typed.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
# Actor discovery
|
||||
|
||||
With @ref:[untyped actors](general/addressing.md) you would use `ActorSelection` to "lookup" actors. Given an actor path with
|
||||
address information you can get hold of an `ActorRef` to any actor. `ActorSelection` does not exist in Akka Typed,
|
||||
so how do you get the actor references? You can send refs in messages but you need something to bootstrap the interaction.
|
||||
|
||||
## Receptionist
|
||||
|
||||
For this purpose there is an actor called the `Receptionist`. You register the specific actors that should be discoverable
|
||||
from other nodes in the local `Receptionist` instance. The API of the receptionist is also based on actor messages.
|
||||
This registry of actor references is then automatically distributed to all other nodes in the cluster.
|
||||
You can lookup such actors with the key that was used when they were registered. The reply to such a `Find` request is
|
||||
a `Listing`, which contains a `Set` of actor references that are registered for the key. Note that several actors can be
|
||||
registered to the same key.
|
||||
|
||||
The registry is dynamic. New actors can be registered during the lifecycle of the system. Entries are removed when
|
||||
registered actors are stopped or a node is removed from the cluster. To facilitate this dynamic aspect you can also subscribe
|
||||
to changes with the `Receptionist.Subscribe` message. It will send `Listing` messages to the subscriber when entries for a key are changed.
|
||||
|
||||
The first scenario is an actor running that needs to be discovered by another actor but you are unable
|
||||
to put a reference to it in an incoming message.
|
||||
|
||||
First we create a `PingService` actor and register it with the `Receptionist` against a
|
||||
`ServiceKey` that will later be used to lookup the reference:
|
||||
|
||||
Scala
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/ReceptionistExampleSpec.scala) { #ping-service }
|
||||
|
||||
Java
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/java/jdocs/akka/cluster/typed/ReceptionistExampleTest.java) { #ping-service }
|
||||
|
||||
Then we have another actor that requires a `PingService` to be constructed:
|
||||
|
||||
Scala
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/ReceptionistExampleSpec.scala) { #pinger }
|
||||
|
||||
Java
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/java/jdocs/akka/cluster/typed/ReceptionistExampleTest.java) { #pinger }
|
||||
|
||||
Finally in the guardian actor we spawn the service as well as subscribing to any actors registering
|
||||
against the `ServiceKey`. Subscribing means that the guardian actor will be informed of any
|
||||
new registrations via a `Listing` message:
|
||||
|
||||
Scala
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/ReceptionistExampleSpec.scala) { #pinger-guardian }
|
||||
|
||||
Java
|
||||
: @@snip [ReceptionistExample]($akka$/akka-cluster-typed/src/test/java/jdocs/akka/cluster/typed/ReceptionistExampleTest.java) { #pinger-guardian }
|
||||
|
||||
Each time a new (which is just a single time in this example) `PingService` is registered the
|
||||
guardian actor spawns a pinger to ping it.
|
||||
|
||||
## Cluster Receptionist
|
||||
|
||||
The `Receptionist` also works in a cluster, the state for the receptionist is propagated via @ref:[distributed data](distributed-data.md).
|
||||
The only difference is the serialisation concerns, see @ref:[clustering](cluster-typed.md).
|
||||
|
|
@ -20,7 +20,7 @@ To use Akka Typed add the following dependency:
|
|||
@@dependency [sbt,Maven,Gradle] {
|
||||
group=com.typesafe.akka
|
||||
artifact=akka-actor-typed_2.12
|
||||
version=$version$
|
||||
version=$akka.version$
|
||||
}
|
||||
|
||||
## Introduction
|
||||
|
|
|
|||
|
|
@ -1,9 +1,21 @@
|
|||
# Sharding
|
||||
|
||||
@@@ warning
|
||||
|
||||
This module is currently marked as @ref:[may change](common/may-change.md) in the sense
|
||||
of being the subject of active research. This means that API or semantics can
|
||||
change without warning or deprecation period and it is not recommended to use
|
||||
this module in production just yet—you have been warned.
|
||||
|
||||
@@@
|
||||
|
||||
To use the testkit add the following dependency:
|
||||
|
||||
@@dependency [sbt,Maven,Gradle] {
|
||||
group=com.typesafe.akka
|
||||
artifact=akka-cluster-sharding-typed_2.12
|
||||
version=$version$
|
||||
version=$akka.version$
|
||||
}
|
||||
|
||||
TODO
|
||||
For an introduction to Akka Cluster concepts see [Cluster Specification]. This documentation shows how to use the typed
|
||||
Cluster API.
|
||||
|
|
@ -1,30 +1,88 @@
|
|||
# Cluster
|
||||
|
||||
sbt
|
||||
: @@@vars
|
||||
```
|
||||
"com.typesafe.akka" %% "akka-cluster-typed" % "$akka.version$"
|
||||
```
|
||||
@@@
|
||||
@@@ warning
|
||||
|
||||
Gradle
|
||||
: @@@vars
|
||||
```
|
||||
dependencies {
|
||||
compile group: 'com.typesafe.akka', name: 'akka-cluster-typed_2.11', version: '$akka.version$'
|
||||
}
|
||||
```
|
||||
@@@
|
||||
This module is currently marked as @ref:[may change](common/may-change.md) in the sense
|
||||
of being the subject of active research. This means that API or semantics can
|
||||
change without warning or deprecation period and it is not recommended to use
|
||||
this module in production just yet—you have been warned.
|
||||
|
||||
@@@
|
||||
|
||||
To use the testkit add the following dependency:
|
||||
|
||||
@@dependency [sbt,Maven,Gradle] {
|
||||
group=com.typesafe.akka
|
||||
artifact=akka-cluster-typed_2.12
|
||||
version=$akka.version$
|
||||
}
|
||||
|
||||
For an introduction to Akka Cluster concepts see @ref:[Cluster Specification](common/cluster.md). This documentation shows how to use the typed
|
||||
Cluster API. All of the examples below assume the following imports:
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-imports }
|
||||
|
||||
And the minimum configuration required is to set a host/port for remoting and the `cluster`
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #config }
|
||||
|
||||
## Cluster API extension
|
||||
|
||||
The typed Cluster extension gives access to management tasks (Joining, Leaving, Downing, …) and subscription of
|
||||
cluster membership events (MemberUp, MemberRemoved, UnreachableMember, etc). Those are exposed as two different actor
|
||||
references, i.e. it’s a message based API.
|
||||
|
||||
The references are on the `Cluster` extension:
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-create }
|
||||
|
||||
|
||||
The Cluster extensions gives you access to:
|
||||
|
||||
* manager: An `ActorRef[ClusterCommand]` where a `ClusterCommand` is a command such as: `Join`, `Leave` and `Down`
|
||||
* subscriptions: An `ActorRef[ClusterStateSubscription]` where a `ClusterStateSubscription` is one of `GetCurrentState` or `Subscribe` and `Unsubscribe` to cluster events like `MemberRemoved`
|
||||
* state: The current `CurrentClusterState`
|
||||
|
||||
|
||||
### Cluster Management
|
||||
|
||||
If not using configuration to specify seeds joining the cluster can be done programmatically via the `manager`.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-join }
|
||||
|
||||
Leaving and downing are similar e.g.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-leave }
|
||||
|
||||
### Cluster subscriptions
|
||||
|
||||
Cluster `subscriptions` can be used to receive messages when cluster state changes. For example, registering
|
||||
for all `MemberEvent`s, then using the `manager` to have a node leave the cluster will result in events
|
||||
for the node going through the lifecycle described in @ref:[Cluster Specification](common/cluster.md).
|
||||
|
||||
This example subscribes with a `TestProbe` but in a real application it would be an Actor:
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-subscribe }
|
||||
|
||||
Then asking a node to leave:
|
||||
|
||||
Scala
|
||||
: @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-leave-example }
|
||||
|
||||
## Serialization
|
||||
|
||||
See [serialization](https://doc.akka.io/docs/akka/current/scala/serialization.html) for how messages are sent between
|
||||
ActorSystems. Actor references are typically included in the messages,
|
||||
since there is no `sender`. To serialize actor references to/from string representation you will use the `ActorRefResolver`.
|
||||
For example here's how a serializer could look for the `Ping` and `Pong` messages above:
|
||||
|
||||
Scala
|
||||
: @@snip [PingSerializer.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/PingSerializer.scala) { #serializer }
|
||||
|
||||
Maven
|
||||
: @@@vars
|
||||
```
|
||||
<dependency>
|
||||
<groupId>com.typesafe.akka</groupId>
|
||||
<artifactId>akka-cluster-typed_$scala.binary_version$</artifactId>
|
||||
<version>$akka.version$</version>
|
||||
</dependency>
|
||||
```
|
||||
@@@
|
||||
|
||||
TODO
|
||||
|
|
|
|||
|
|
@ -5,8 +5,9 @@
|
|||
@@@ index
|
||||
|
||||
* [actors](actors-typed.md)
|
||||
* [fault-tolerance-typed.md](fault-tolerance-typed.md)
|
||||
* [coexisting](coexisting.md)
|
||||
* [fault-tolerance](fault-tolerance-typed.md)
|
||||
* [actor-discovery](actor-discovery-typed.md)
|
||||
* [cluster](cluster-typed.md)
|
||||
* [cluster-sharding](cluster-sharding-typed.md)
|
||||
* [persistence](persistence-typed.md)
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ To use the testkit add the following dependency:
|
|||
@@dependency [sbt,Maven,Gradle] {
|
||||
group=com.typesafe.akka
|
||||
artifact=akka-testkit-typed_2.12
|
||||
version=$version$
|
||||
version=$akka.version$
|
||||
scope=test
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue