Remove samples (#22288)
Add code, that was used for documentation to the appropriate projects or akka-docs.
This commit is contained in:
Martynas Mickevičius
Johan Andrén
parent
b8cdcf3439
commit
958de6a916
373 changed files with 1201 additions and 17259 deletions
|
|
@ -22,7 +22,41 @@ It joins the cluster and an actor subscribes to cluster membership events and lo
|
|||
|
||||
The ``application.conf`` configuration looks like this:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/resources/application.conf#snippet
|
||||
::
|
||||
|
||||
akka {
|
||||
actor {
|
||||
provider = "cluster"
|
||||
}
|
||||
remote {
|
||||
log-remote-lifecycle-events = off
|
||||
netty.tcp {
|
||||
hostname = "127.0.0.1"
|
||||
port = 0
|
||||
}
|
||||
}
|
||||
|
||||
cluster {
|
||||
seed-nodes = [
|
||||
"akka.tcp://ClusterSystem@127.0.0.1:2551",
|
||||
"akka.tcp://ClusterSystem@127.0.0.1:2552"]
|
||||
|
||||
# auto downing is NOT safe for production deployments.
|
||||
# you may want to use it during development, read more about it in the docs.
|
||||
#
|
||||
# auto-down-unreachable-after = 10s
|
||||
}
|
||||
}
|
||||
|
||||
# Disable legacy metrics in akka-cluster.
|
||||
akka.cluster.metrics.enabled=off
|
||||
|
||||
# Enable metrics extension in akka-cluster-metrics.
|
||||
akka.extensions=["akka.cluster.metrics.ClusterMetricsExtension"]
|
||||
|
||||
# Sigar native library extract location during tests.
|
||||
# Note: use per-jvm-instance folder when running multiple jvm on one host.
|
||||
akka.cluster.metrics.native-library-extract-folder=${user.dir}/target/native
|
||||
|
||||
To enable cluster capabilities in your Akka project you should, at a minimum, add the :ref:`remoting-scala`
|
||||
settings, but with ``cluster``.
|
||||
|
|
@ -39,7 +73,7 @@ ip-addresses or host names of the machines in ``application.conf`` instead of ``
|
|||
|
||||
An actor that uses the cluster extension may look like this:
|
||||
|
||||
.. literalinclude:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/simple/SimpleClusterListener.scala
|
||||
.. literalinclude:: code/docs/cluster/SimpleClusterListener.scala
|
||||
:language: scala
|
||||
|
||||
The actor registers itself as subscriber of certain cluster events. It receives events corresponding to the current state
|
||||
|
|
@ -224,7 +258,7 @@ Subscribe to Cluster Events
|
|||
You can subscribe to change notifications of the cluster membership by using
|
||||
``Cluster(system).subscribe``.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/simple/SimpleClusterListener2.scala#subscribe
|
||||
.. includecode:: code/docs/cluster/SimpleClusterListener2.scala
|
||||
|
||||
A snapshot of the full state, ``akka.cluster.ClusterEvent.CurrentClusterState``, is sent to the subscriber
|
||||
as the first message, followed by events for incremental updates.
|
||||
|
|
@ -241,7 +275,7 @@ the events corresponding to the current state to mimic what you would have seen
|
|||
listening to the events when they occurred in the past. Note that those initial events only correspond
|
||||
to the current state and it is not the full history of all changes that actually has occurred in the cluster.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/simple/SimpleClusterListener.scala#subscribe
|
||||
.. includecode:: code/docs/cluster/SimpleClusterListener.scala#subscribe
|
||||
|
||||
The events to track the life-cycle of members are:
|
||||
|
||||
|
|
@ -277,11 +311,11 @@ added or removed to the cluster dynamically.
|
|||
|
||||
Messages:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/transformation/TransformationMessages.scala#messages
|
||||
.. includecode:: code/docs/cluster/TransformationMessages.scala#messages
|
||||
|
||||
The backend worker that performs the transformation job:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/transformation/TransformationBackend.scala#backend
|
||||
.. includecode:: code/docs/cluster/TransformationBackend.scala#backend
|
||||
|
||||
Note that the ``TransformationBackend`` actor subscribes to cluster events to detect new,
|
||||
potential, frontend nodes, and send them a registration message so that they know
|
||||
|
|
@ -289,7 +323,7 @@ that they can use the backend worker.
|
|||
|
||||
The frontend that receives user jobs and delegates to one of the registered backend workers:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/transformation/TransformationFrontend.scala#frontend
|
||||
.. includecode:: code/docs/cluster/TransformationFrontend.scala#frontend
|
||||
|
||||
Note that the ``TransformationFrontend`` actor watch the registered backend
|
||||
to be able to remove it from its list of available backend workers.
|
||||
|
|
@ -323,20 +357,23 @@ A common use case is to start actors after the cluster has been initialized,
|
|||
members have joined, and the cluster has reached a certain size.
|
||||
|
||||
With a configuration option you can define required number of members
|
||||
before the leader changes member status of 'Joining' members to 'Up'.
|
||||
before the leader changes member status of 'Joining' members to 'Up'.::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/resources/factorial.conf#min-nr-of-members
|
||||
akka.cluster.min-nr-of-members = 3
|
||||
|
||||
In a similar way you can define required number of members of a certain role
|
||||
before the leader changes member status of 'Joining' members to 'Up'.
|
||||
before the leader changes member status of 'Joining' members to 'Up'.::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/resources/factorial.conf#role-min-nr-of-members
|
||||
akka.cluster.role {
|
||||
frontend.min-nr-of-members = 1
|
||||
backend.min-nr-of-members = 2
|
||||
}
|
||||
|
||||
You can start the actors in a ``registerOnMemberUp`` callback, which will
|
||||
be invoked when the current member status is changed to 'Up', i.e. the cluster
|
||||
has at least the defined number of members.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/factorial/FactorialFrontend.scala#registerOnUp
|
||||
.. includecode:: code/docs/cluster/FactorialFrontend.scala#registerOnUp
|
||||
|
||||
This callback can be used for other things than starting actors.
|
||||
|
||||
|
|
@ -509,9 +546,19 @@ Router with Group of Routees
|
|||
----------------------------
|
||||
|
||||
When using a ``Group`` you must start the routee actors on the cluster member nodes.
|
||||
That is not done by the router. The configuration for a group looks like this:
|
||||
That is not done by the router. The configuration for a group looks like this:::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#router-lookup-config
|
||||
akka.actor.deployment {
|
||||
/statsService/workerRouter {
|
||||
router = consistent-hashing-group
|
||||
routees.paths = ["/user/statsWorker"]
|
||||
cluster {
|
||||
enabled = on
|
||||
allow-local-routees = on
|
||||
use-role = compute
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.. note::
|
||||
The routee actors should be started as early as possible when starting the actor system, because
|
||||
|
|
@ -528,7 +575,7 @@ Set it to a lower value if you want to limit total number of routees.
|
|||
|
||||
The same type of router could also have been defined in code:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/Extra.scala#router-lookup-in-code
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsService.scala#router-lookup-in-code
|
||||
|
||||
See :ref:`cluster_configuration_scala` section for further descriptions of the settings.
|
||||
|
||||
|
|
@ -546,23 +593,33 @@ the average number of characters per word when all results have been collected.
|
|||
|
||||
Messages:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/StatsMessages.scala#messages
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsMessages.scala#messages
|
||||
|
||||
The worker that counts number of characters in each word:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/StatsWorker.scala#worker
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsWorker.scala#worker
|
||||
|
||||
The service that receives text from users and splits it up into words, delegates to workers and aggregates:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/StatsService.scala#service
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsService.scala#service
|
||||
|
||||
|
||||
Note, nothing cluster specific so far, just plain actors.
|
||||
|
||||
All nodes start ``StatsService`` and ``StatsWorker`` actors. Remember, routees are the workers in this case.
|
||||
The router is configured with ``routees.paths``:
|
||||
The router is configured with ``routees.paths``:::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/resources/stats1.conf#config-router-lookup
|
||||
akka.actor.deployment {
|
||||
/statsService/workerRouter {
|
||||
router = consistent-hashing-group
|
||||
routees.paths = ["/user/statsWorker"]
|
||||
cluster {
|
||||
enabled = on
|
||||
allow-local-routees = on
|
||||
use-role = compute
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
This means that user requests can be sent to ``StatsService`` on any node and it will use
|
||||
``StatsWorker`` on all nodes.
|
||||
|
|
@ -575,9 +632,19 @@ Router with Pool of Remote Deployed Routees
|
|||
-------------------------------------------
|
||||
|
||||
When using a ``Pool`` with routees created and deployed on the cluster member nodes
|
||||
the configuration for a router looks like this:
|
||||
the configuration for a router looks like this:::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSingleMasterSpec.scala#router-deploy-config
|
||||
akka.actor.deployment {
|
||||
/statsService/singleton/workerRouter {
|
||||
router = consistent-hashing-pool
|
||||
cluster {
|
||||
enabled = on
|
||||
max-nr-of-instances-per-node = 3
|
||||
allow-local-routees = on
|
||||
use-role = compute
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
It is possible to limit the deployment of routees to member nodes tagged with a certain role by
|
||||
specifying ``use-role``.
|
||||
|
|
@ -589,7 +656,7 @@ Set it to a lower value if you want to limit total number of routees.
|
|||
|
||||
The same type of router could also have been defined in code:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/Extra.scala#router-deploy-in-code
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsService.scala#router-deploy-in-code
|
||||
|
||||
See :ref:`cluster_configuration_scala` section for further descriptions of the settings.
|
||||
|
||||
|
|
@ -598,21 +665,40 @@ Router Example with Pool of Remote Deployed Routees
|
|||
|
||||
Let's take a look at how to use a cluster aware router on single master node that creates
|
||||
and deploys workers. To keep track of a single master we use the :ref:`cluster-singleton-scala`
|
||||
in the cluster-tools module. The ``ClusterSingletonManager`` is started on each node.
|
||||
in the cluster-tools module. The ``ClusterSingletonManager`` is started on each node.::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/StatsSampleOneMaster.scala#create-singleton-manager
|
||||
system.actorOf(
|
||||
ClusterSingletonManager.props(
|
||||
singletonProps = Props[StatsService],
|
||||
terminationMessage = PoisonPill,
|
||||
settings = ClusterSingletonManagerSettings(system).withRole("compute")),
|
||||
name = "statsService")
|
||||
|
||||
We also need an actor on each node that keeps track of where current single master exists and
|
||||
delegates jobs to the ``StatsService``. That is provided by the ``ClusterSingletonProxy``.
|
||||
delegates jobs to the ``StatsService``. That is provided by the ``ClusterSingletonProxy``.::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/scala/sample/cluster/stats/StatsSampleOneMaster.scala#singleton-proxy
|
||||
system.actorOf(
|
||||
ClusterSingletonProxy.props(
|
||||
singletonManagerPath = "/user/statsService",
|
||||
settings = ClusterSingletonProxySettings(system).withRole("compute")),
|
||||
name = "statsServiceProxy")
|
||||
|
||||
The ``ClusterSingletonProxy`` receives text from users and delegates to the current ``StatsService``, the single
|
||||
master. It listens to cluster events to lookup the ``StatsService`` on the oldest node.
|
||||
|
||||
All nodes start ``ClusterSingletonProxy`` and the ``ClusterSingletonManager``. The router is now configured like this:
|
||||
All nodes start ``ClusterSingletonProxy`` and the ``ClusterSingletonManager``. The router is now configured like this:::
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/main/resources/stats2.conf#config-router-deploy
|
||||
akka.actor.deployment {
|
||||
/statsService/singleton/workerRouter {
|
||||
router = consistent-hashing-pool
|
||||
cluster {
|
||||
enabled = on
|
||||
max-nr-of-instances-per-node = 3
|
||||
allow-local-routees = on
|
||||
use-role = compute
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
The `Lightbend Activator <http://www.lightbend.com/platform/getstarted>`_ tutorial named
|
||||
`Akka Cluster Samples with Scala <http://www.lightbend.com/activator/template/akka-sample-cluster-scala>`_.
|
||||
|
|
@ -636,14 +722,14 @@ add the ``sbt-multi-jvm`` plugin and the dependency to ``akka-multi-node-testkit
|
|||
First, as described in :ref:`multi-node-testing`, we need some scaffolding to configure the ``MultiNodeSpec``.
|
||||
Define the participating roles and their :ref:`cluster_configuration_scala` in an object extending ``MultiNodeConfig``:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala
|
||||
:include: MultiNodeConfig
|
||||
:exclude: router-lookup-config
|
||||
|
||||
Define one concrete test class for each role/node. These will be instantiated on the different nodes (JVMs). They can be
|
||||
implemented differently, but often they are the same and extend an abstract test class, as illustrated here.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#concrete-tests
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#concrete-tests
|
||||
|
||||
Note the naming convention of these classes. The name of the classes must end with ``MultiJvmNode1``, ``MultiJvmNode2``
|
||||
and so on. It is possible to define another suffix to be used by the ``sbt-multi-jvm``, but the default should be
|
||||
|
|
@ -651,18 +737,18 @@ fine in most cases.
|
|||
|
||||
Then the abstract ``MultiNodeSpec``, which takes the ``MultiNodeConfig`` as constructor parameter.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#abstract-test
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#abstract-test
|
||||
|
||||
Most of this can of course be extracted to a separate trait to avoid repeating this in all your tests.
|
||||
|
||||
Typically you begin your test by starting up the cluster and let the members join, and create some actors.
|
||||
That can be done like this:
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#startup-cluster
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#startup-cluster
|
||||
|
||||
From the test you interact with the cluster using the ``Cluster`` extension, e.g. ``join``.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#join
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#join
|
||||
|
||||
Notice how the `testActor` from :ref:`testkit <akka-testkit>` is added as :ref:`subscriber <cluster_subscriber_scala>`
|
||||
to cluster changes and then waiting for certain events, such as in this case all members becoming 'Up'.
|
||||
|
|
@ -670,7 +756,7 @@ to cluster changes and then waiting for certain events, such as in this case all
|
|||
The above code was running for all roles (JVMs). ``runOn`` is a convenient utility to declare that a certain block
|
||||
of code should only run for a specific role.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#test-statsService
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#test-statsService
|
||||
|
||||
Once again we take advantage of the facilities in :ref:`testkit <akka-testkit>` to verify expected behavior.
|
||||
Here using ``testActor`` as sender (via ``ImplicitSender``) and verifying the reply with ``expectMsgPF``.
|
||||
|
|
@ -678,7 +764,7 @@ Here using ``testActor`` as sender (via ``ImplicitSender``) and verifying the re
|
|||
In the above code you can see ``node(third)``, which is useful facility to get the root actor reference of
|
||||
the actor system for a specific role. This can also be used to grab the ``akka.actor.Address`` of that node.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#addresses
|
||||
.. includecode:: ../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala#addresses
|
||||
|
||||
|
||||
Management
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue