From 3a683bb9b455248055854bc65ec2fb261bc46f83 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Mon, 10 Feb 2014 11:22:11 +0100 Subject: [PATCH] =doc #3685 Add FAQ to documentation * The links at http://akka.io will changed to point at this faq * Some rewording of guarantees/reliability --- .../rst/additional/code/docs/faq/Faq.scala | 27 +++ .../code/{ => docs}/osgi/Activator.scala | 0 .../code/{ => docs}/osgi/blueprint.xml | 0 akka-docs/rst/additional/faq.rst | 160 ++++++++++++++++++ akka-docs/rst/additional/index.rst | 1 + akka-docs/rst/additional/osgi.rst | 2 +- akka-docs/rst/general/index.rst | 2 +- ...s.rst => message-delivery-reliability.rst} | 20 +-- akka-docs/rst/general/terminology.rst | 2 +- akka-docs/rst/java/logging.rst | 2 + .../RemoteConsistentHashingRouterSpec.scala | 4 +- 11 files changed, 205 insertions(+), 15 deletions(-) create mode 100644 akka-docs/rst/additional/code/docs/faq/Faq.scala rename akka-docs/rst/additional/code/{ => docs}/osgi/Activator.scala (100%) rename akka-docs/rst/additional/code/{ => docs}/osgi/blueprint.xml (100%) create mode 100644 akka-docs/rst/additional/faq.rst rename akka-docs/rst/general/{message-delivery-guarantees.rst => message-delivery-reliability.rst} (97%) diff --git a/akka-docs/rst/additional/code/docs/faq/Faq.scala b/akka-docs/rst/additional/code/docs/faq/Faq.scala new file mode 100644 index 0000000000..ae12c72170 --- /dev/null +++ b/akka-docs/rst/additional/code/docs/faq/Faq.scala @@ -0,0 +1,27 @@ +package docs.faq + +import akka.actor.Actor + +//#exhaustiveness-check +object MyActor { + // these are the messages we accept + sealed abstract trait Message + case class FooMessage(foo: String) extends Message + case class BarMessage(bar: Int) extends Message + + // these are the replies we send + sealed abstract trait Reply + case class BazMessage(baz: String) extends Reply +} + +class MyActor extends Actor { + import MyActor._ + def receive = { + case message: Message ⇒ message match { + case BarMessage(bar) => sender ! BazMessage("Got " + bar) + // warning here: + // "match may not be exhaustive. It would fail on the following input: FooMessage(_)" + } + } +} +//#exhaustiveness-check \ No newline at end of file diff --git a/akka-docs/rst/additional/code/osgi/Activator.scala b/akka-docs/rst/additional/code/docs/osgi/Activator.scala similarity index 100% rename from akka-docs/rst/additional/code/osgi/Activator.scala rename to akka-docs/rst/additional/code/docs/osgi/Activator.scala diff --git a/akka-docs/rst/additional/code/osgi/blueprint.xml b/akka-docs/rst/additional/code/docs/osgi/blueprint.xml similarity index 100% rename from akka-docs/rst/additional/code/osgi/blueprint.xml rename to akka-docs/rst/additional/code/docs/osgi/blueprint.xml diff --git a/akka-docs/rst/additional/faq.rst b/akka-docs/rst/additional/faq.rst new file mode 100644 index 0000000000..33e5e0e69d --- /dev/null +++ b/akka-docs/rst/additional/faq.rst @@ -0,0 +1,160 @@ +Frequently Asked Questions +========================== + +Akka Project +^^^^^^^^^^^^ + +Where does the name Akka come from? +----------------------------------- + +It is the name of a beautiful Swedish `mountain `_ +up in the northern part of Sweden called Laponia. The mountain is also sometimes +called 'The Queen of Laponia'. + +Akka is also the name of a goddess in the Sámi (the native Swedish population) +mythology. She is the goddess that stands for all the beauty and good in the +world. The mountain can be seen as the symbol of this goddess. + +Also, the name AKKA is the a palindrome of letters A and K as in Actor Kernel. + +Akka is also: + +* the name of the goose that Nils traveled across Sweden on in `The Wonderful Adventures of Nils `_ by the Swedish writer Selma Lagerlöf. +* the Finnish word for 'nasty elderly woman' and the word for 'elder sister' in the Indian languages Tamil, Telugu, Kannada and Marathi. +* a `font `_ +* a town in Morocco +* a near-earth asteroid + +Actors in General +^^^^^^^^^^^^^^^^^ + +sender()/getSender() disappears when I use Future in my Actor, why? +------------------------------------------------------------------- + +When using future callbacks, inside actors you need to carefully avoid closing over +the containing actor’s reference, i.e. do not call methods or access mutable state +on the enclosing actor from within the callback. This breaks the actor encapsulation +and may introduce synchronization bugs and race conditions because the callback will +be scheduled concurrently to the enclosing actor. Unfortunately there is not yet a way +to detect these illegal accesses at compile time. + +Read more about it in the docs for :ref:`jmm-shared-state`. + +Why OutOfMemoryError? +--------------------- + +It can be many reasons for OutOfMemoryError. For example, in a pure push based system with +message consumers that are potentially slower than corresponding message producers you must +add some kind of message flow control. Otherwise messages will be queued in the consumers' +mailboxes and thereby filling up the heap memory. + +Some articles for inspiration: + +* `Balancing Workload across Nodes with Akka 2 `_. +* `Work Pulling Pattern to prevent mailbox overflow, throttle and distribute work `_ + +Actors Scala API +^^^^^^^^^^^^^^^^ + +How can I get compile time errors for missing messages in `receive`? +-------------------------------------------------------------------- + +One solution to help you get a compile time warning for not handling a message +that you should be handling is to define your actors input and output messages +implementing base traits, and then do a match that the will be checked for +exhaustiveness. + +Here is an example where the compiler will warn you that the match in +receive isn't exhaustive: + +.. includecode:: code/docs/faq/Faq.scala#exhaustiveness-check + +Remoting +^^^^^^^^ + +I want to send to a remote system but it does not do anything +------------------------------------------------------------- + +Make sure that you have remoting enabled on both ends: client and server. Both +do need hostname and port configured, and you will need to know the port of the +server; the client can use an automatic port in most cases (i.e. configure port +zero). If both systems are running on the same network host, their ports must +be different + +If you still do not see anything, look at what the logging of remote +life-cycle events tells you (normally logged at INFO level) or switch on +:ref:`logging-remote-java` +to see all sent and received messages (logged at DEBUG level). + +Which options shall I enable when debugging remoting issues? +------------------------------------------------------------ + +Have a look at the :ref:`remote-configuration-java`, the typical candidates are: + +* `akka.remote.log-sent-messages` +* `akka.remote.log-received-messages` +* `akka.remote.log-remote-lifecycle-events` (this also includes deserialization errors) + +What is the name of a remote actor? +----------------------------------- + +When you want to send messages to an actor on a remote host, you need to know +its :ref:`full path `, which is of the form:: + + akka.protocol://system@host:1234/user/my/actor/hierarchy/path + +Observe all the parts you need here: + +* ``protocol`` is the protocol to be used to communicate with the remote system. + Most of the cases this is `tcp`. + +* ``system`` is the remote system’s name (must match exactly, case-sensitive!) + +* ``host`` is the remote system’s IP address or DNS name, and it must match that + system’s configuration (i.e. `akka.remote.netty.hostname`) + +* ``1234`` is the port number on which the remote system is listening for + connections and receiving messages + +* ``/user/my/actor/hierarchy/path`` is the absolute path of the remote actor in + the remote system’s supervision hierarchy, including the system’s guardian + (i.e. ``/user``, there are others e.g. ``/system`` which hosts loggers, ``/temp`` + which keeps temporary actor refs used with `ask()`, `/remote` which enables + remote deployment, etc.); this matches how the actor prints its own ``self`` + reference on the remote host, e.g. in log output. + +Why are replies not received from a remote actor? +------------------------------------------------- + +The most common reason is that the local system’s name (i.e. the +``system@host:1234`` part in the answer above) is not reachable from the remote +system’s network location, e.g. because ``host`` was configured to be ``0.0.0.0``, +``localhost`` or a NAT’ed IP address. + +How reliable is the message delivery? +------------------------------------- + +The general rule is **at-most-once delivery**, i.e. no guaranteed delivery. +Stronger reliability can be built on top, and Akka provides tools to do so. + +Read more in :ref:`message-delivery-reliability`. + +Debugging +^^^^^^^^^ + +How do I turn on debug logging? +------------------------------- + +To turn on debug logging in your actor system add the following to your configuration:: + + akka.loglevel = DEBUG + +To enable different types of debug logging add the following to your configuration: + +* ``akka.actor.debug.receive`` will log all messages sent to an actor if that actors `receive` method is a ``LoggingReceive`` + +* ``akka.actor.debug.autoreceive`` will log all *special* messages like ``Kill``, ``PoisonPill`` e.t.c. sent to all actors + +* ``akka.actor.debug.lifecycle`` will log all actor lifecycle events of all actors + +Read more about it in the docs for :ref:`logging-java` and :ref:`actor.logging-scala`. diff --git a/akka-docs/rst/additional/index.rst b/akka-docs/rst/additional/index.rst index 74880955fb..3f80d5e0c4 100644 --- a/akka-docs/rst/additional/index.rst +++ b/akka-docs/rst/additional/index.rst @@ -4,6 +4,7 @@ Additional Information .. toctree:: :maxdepth: 2 + faq books recipes language-bindings diff --git a/akka-docs/rst/additional/osgi.rst b/akka-docs/rst/additional/osgi.rst index 63b903f35e..8cdc5d1acf 100644 --- a/akka-docs/rst/additional/osgi.rst +++ b/akka-docs/rst/additional/osgi.rst @@ -14,7 +14,7 @@ Activator To bootstrap Akka inside an OSGi environment, you can use the ``akka.osgi.ActorSystemActivator`` class to conveniently set up the ActorSystem. -.. includecode:: code/osgi/Activator.scala#Activator +.. includecode:: code/docs/osgi/Activator.scala#Activator The ``ActorSystemActivator`` creates the actor system with a class loader that finds resources diff --git a/akka-docs/rst/general/index.rst b/akka-docs/rst/general/index.rst index 3d9c421cb4..ceda05f75f 100644 --- a/akka-docs/rst/general/index.rst +++ b/akka-docs/rst/general/index.rst @@ -11,5 +11,5 @@ General addressing remoting jmm - message-delivery-guarantees + message-delivery-reliability configuration diff --git a/akka-docs/rst/general/message-delivery-guarantees.rst b/akka-docs/rst/general/message-delivery-reliability.rst similarity index 97% rename from akka-docs/rst/general/message-delivery-guarantees.rst rename to akka-docs/rst/general/message-delivery-reliability.rst index 9ee9a1f153..fafb4dafcd 100644 --- a/akka-docs/rst/general/message-delivery-guarantees.rst +++ b/akka-docs/rst/general/message-delivery-reliability.rst @@ -1,8 +1,8 @@ -.. _message-delivery-guarantees: +.. _message-delivery-reliability: -########################### -Message Delivery Guarantees -########################### +############################ +Message Delivery Reliability +############################ Akka helps you build reliable applications which make use of multiple processor cores in one machine (“scaling up”) or distributed across a computer network @@ -31,7 +31,7 @@ actors—you can place them always on the same JVM and enjoy stricter guarantees on message delivery. The details of this trade-off are discussed further below. As a supplementary part we give a few pointers at how to build stronger -guarantees on top of the built-in ones. The chapter closes by discussing the +reliability on top of the built-in ones. The chapter closes by discussing the role of the “Dead Letter Office”. The General Rules @@ -106,9 +106,9 @@ read more about this approach in the `Erlang documentation`_ (section 10.9 and 10.10), Akka follows it closely. Another angle on this issue is that by providing only basic guarantees those -use cases which do not need stricter guarantees do not pay the cost of their -implementation; it is always possible to add stricter guarantees on top of -basic ones, but it is not possible to retro-actively remove guarantees in order +use cases which do not need stronger reliability do not pay the cost of their +implementation; it is always possible to add stronger reliability on top of +basic ones, but it is not possible to retro-actively remove reliability in order to gain more performance. .. _message-ordering: @@ -188,7 +188,7 @@ The Rules for In-JVM (Local) Message Sends Be careful what you do with this section! ----------------------------------------- -Relying on the stronger guarantees in this section is not recommended since it +Relying on the stronger reliability in this section is not recommended since it will bind your application to local-only deployment: an application may have to be designed differently (as opposed to just employing some message exchange patterns local to some actors) in order to be fit for running on a cluster of @@ -277,7 +277,7 @@ powerful, higher-level abstractions on top it. Messaging Patterns ------------------ -As discussed above a straight-forward answer to the requirement of guaranteed +As discussed above a straight-forward answer to the requirement of reliable delivery is an explicit ACK–RETRY protocol. In its simplest form this requires - a way to identify individual messages to correlate message with diff --git a/akka-docs/rst/general/terminology.rst b/akka-docs/rst/general/terminology.rst index 0807b613f8..81593649a0 100644 --- a/akka-docs/rst/general/terminology.rst +++ b/akka-docs/rst/general/terminology.rst @@ -73,7 +73,7 @@ this can cause race conditions. .. note:: The only guarantee that Akka provides about messages sent between a given pair of actors is that their order is - always preserved. see :ref:`message-delivery-guarantees` + always preserved. see :ref:`message-delivery-reliability` Non-blocking Guarantees (Progress Conditions) --------------------------------------------- diff --git a/akka-docs/rst/java/logging.rst b/akka-docs/rst/java/logging.rst index 83e40da63a..034ea962e3 100644 --- a/akka-docs/rst/java/logging.rst +++ b/akka-docs/rst/java/logging.rst @@ -149,6 +149,8 @@ If you want to monitor subscriptions (subscribe/unsubscribe) on the ActorSystem. } } +.. _logging-remote-java: + Auxiliary remote logging options -------------------------------- diff --git a/akka-remote/src/test/scala/akka/remote/RemoteConsistentHashingRouterSpec.scala b/akka-remote/src/test/scala/akka/remote/RemoteConsistentHashingRouterSpec.scala index f844403951..e1ec1450ac 100644 --- a/akka-remote/src/test/scala/akka/remote/RemoteConsistentHashingRouterSpec.scala +++ b/akka-remote/src/test/scala/akka/remote/RemoteConsistentHashingRouterSpec.scala @@ -27,8 +27,8 @@ class RemoteConsistentHashingRouterSpec extends AkkaSpec(""" val consistentHash1 = ConsistentHash(nodes1, 10) val consistentHash2 = ConsistentHash(nodes2, 10) val keys = List("A", "B", "C", "D", "E", "F", "G") - val result1 = keys collect { case k => consistentHash1.nodeFor(k).routee } - val result2 = keys collect { case k => consistentHash2.nodeFor(k).routee } + val result1 = keys collect { case k ⇒ consistentHash1.nodeFor(k).routee } + val result2 = keys collect { case k ⇒ consistentHash2.nodeFor(k).routee } result1 should be(result2) }