Merge pull request #19989 from akka/wip-small-doc-fixes-RK

Wip small doc fixes rk

README.md

@@ -4,7 +4,7 @@ We believe that writing correct concurrent & distributed, resilient and elastic
 
 Akka is here to change that.
 
-Using the Actor Model we raise the abstraction level and provide a better platform to build correct concurrent and scalable applications.
+Using the Actor Model we raise the abstraction level and provide a better platform to build correct concurrent and scalable applications. This model is a perfect match for the principles laid out in the [Reactive Manifesto](http://www.reactivemanifesto.org/).
 
 For resilience we adopt the "Let it crash" model which the telecom industry has used with great success to build applications that self-heal and systems that never stop.
 

akka-docs/_sphinx/themes/akka/layout.html

@@ -25,10 +25,10 @@
 {% block relbar2 %}{% endblock %}
 
 {% block extrahead %}
+  {%- if include_analytics %}
     <!-- Hint to search engines that the "canonical" page is under "current", which will boost it appearing in search results -->
     <link rel="canonical" href="http://akka.io/docs/akka/current/{{ pagename }}.html" />
 
-  {%- if include_analytics %}
     <!--Google Analytics-->
     <script type="text/javascript">
       var _gaq = _gaq || [];

akka-docs/rst/additional/faq.rst

@@ -25,6 +25,28 @@ Akka is also:
 * a town in Morocco
 * a near-earth asteroid
 
+Resources with Explicit Lifecycle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Actors, ActorSystems, ActorMaterializers (for streams), all these types of objects bind
+resources that must be released explicitly. The reason is that Actors are meant to have
+a life of their own, existing independently of whether messages are currently en route
+to them. Therefore you should always make sure that for every creation of such an object
+you have a matching ``stop``, ``terminate``, or ``shutdown`` call implemented.
+
+In particular you typically want to bind such values to immutable references, i.e.
+``final ActorSystem system`` in Java or ``val system: ActorSystem`` in Scala.
+
+JVM application or Scala REPL “hanging”
+---------------------------------------
+
+Due to an ActorSystem’s explicit lifecycle the JVM will not exit until it is stopped.
+Therefore it is necessary to shutdown all ActorSystems within a running application or
+Scala REPL session in order to allow these processes to terminate.
+
+Shutting down an ActorSystem will properly terminate all Actors and ActorMaterializers
+that were created within it.
+
 Actors in General
 ^^^^^^^^^^^^^^^^^
 

akka-docs/rst/dev/building-akka.rst

@@ -47,8 +47,10 @@ want to find out more about sbt and using it for your own projects do read the
 
 .. _sbt documentation: http://www.scala-sbt.org/documentation.html
 
-The Akka sbt build file is ``project/AkkaBuild.scala``.
-
+The main Akka sbt build file is ``project/AkkaBuild.scala``, with a `build.sbt` in
+each subproject’s directory. It is advisable to allocate at least 2GB of heap size
+to the JVM that runs sbt, otherwise you may experience some spurious failures when
+running the tests.
 
 Building Akka
 =============

akka-docs/rst/intro/what-is-akka.rst

@@ -4,9 +4,9 @@
  What is Akka?
 ###############
 
-**Scalable real-time transaction processing**
+**«resilient elastic distributed real-time transaction processing»**
 
-We believe that writing correct concurrent, fault-tolerant and scalable
+We believe that writing correct distributed, concurrent, fault-tolerant and scalable
 applications is too hard. Most of the time it's because we are using the wrong
 tools and the wrong level of abstraction. Akka is here to change that. Using
 the Actor Model we raise the abstraction level and provide a better platform to
@@ -34,8 +34,8 @@ Actors
 
 Actors give you:
 
-- Simple and high-level abstractions for concurrency and parallelism.
-- Asynchronous, non-blocking and highly performant event-driven programming model.
+- Simple and high-level abstractions for distribution, concurrency and parallelism.
+- Asynchronous, non-blocking and highly performant message-driven programming model.
 - Very lightweight event-driven processes (several million actors per GB of heap memory).
 
 See the chapter for :ref:`Scala <actors-scala>` or :ref:`Java <untyped-actors-java>`.
@@ -44,7 +44,7 @@ Fault Tolerance
 ---------------
 
 - Supervisor hierarchies with "let-it-crash" semantics.
-- Supervisor hierarchies can span over multiple JVMs to provide truly fault-tolerant systems.
+- Actor systems can span over multiple JVMs to provide truly fault-tolerant systems.
 - Excellent for writing highly fault-tolerant systems that self-heal and never stop.
 
 See :ref:`Fault Tolerance (Scala) <fault-tolerance-scala>` and :ref:`Fault Tolerance (Java) <fault-tolerance-java>`.
@@ -60,7 +60,7 @@ and :ref:`Scala <cluster_usage_scala>` documentation chapters.
 Persistence
 -----------
 
-Messages received by an actor can optionally be persisted and replayed when the actor is started or
+State changes experience by an actor can optionally be persisted and replayed when the actor is started or
 restarted. This allows actors to recover their state, even after JVM crashes or when being migrated
 to another node.
 
@@ -72,17 +72,21 @@ Scala and Java APIs
 Akka has both a :ref:`scala-api` and a :ref:`java-api`.
 
 
-Akka can be used in two different ways
-======================================
+Akka can be used in different ways
+==================================
 
-Akka can be used and deployed in different ways:
+Akka is a toolkit, not a framework: you integrate it into your build like any other library
+without having to follow a particular source code layout. When expressing your systems as collaborating
+Actors you may feel pushed more towards proper encapsulation of internal state, you may find that
+there is a natural separation between business logic and inter-component communication.
 
-- As a library: used as a regular JAR on the classpath and/or in a web app, to
-  be put into ``WEB-INF/lib``
+Akka applications are typically deployed as follows:
 
-- Package with `sbt-native-packager <https://github.com/sbt/sbt-native-packager>`_
+- as a library: used as a regular JAR on the classpath or in a web app.
 
-- Package and deploy using `Lightbend ConductR <http://www.lightbend.com/products/conductr>`_.
+- packaged with `sbt-native-packager <https://github.com/sbt/sbt-native-packager>`_.
+
+- packaged and deployed using `Lightbend ConductR <http://www.lightbend.com/products/conductr>`_.
 
 Commercial Support
 ==================

akka-docs/rst/java/routing.rst

@@ -263,6 +263,19 @@ BalancingPool
 A Router that will try to redistribute work from busy routees to idle routees.
 All routees share the same mailbox.
 
+.. note::
+
+   The BalancingPool has the property that its routees do not have truly distinct
+   identity: they have different names, but talking to them will not end up at the
+   right actor in most cases. Therefore you cannot use it for workflows that
+   require state to be kept within the routee, you would in this case have to
+   include the whole state in the messages.
+
+   With a `SmallestMailboxPool`_ you can have a vertically scaling service that
+   can interact in a stateful fashion with other services in the back-end before
+   replying to the original client. The other advantage is that it does not place
+   a restriction on the message queue implementation as BalancingPool does.
+
 BalancingPool defined in configuration:
 
 .. includecode:: ../scala/code/docs/routing/RouterDocSpec.scala#config-balancing-pool

akka-docs/rst/scala/routing.rst

@@ -262,6 +262,19 @@ BalancingPool
 A Router that will try to redistribute work from busy routees to idle routees.
 All routees share the same mailbox.
 
+.. note::
+
+   The BalancingPool has the property that its routees do not have truly distinct
+   identity: they have different names, but talking to them will not end up at the
+   right actor in most cases. Therefore you cannot use it for workflows that
+   require state to be kept within the routee, you would in this case have to
+   include the whole state in the messages.
+
+   With a `SmallestMailboxPool`_ you can have a vertically scaling service that
+   can interact in a stateful fashion with other services in the back-end before
+   replying to the original client. The other advantage is that it does not place
+   a restriction on the message queue implementation as BalancingPool does.
+
 BalancingPool defined in configuration:
 
 .. includecode:: code/docs/routing/RouterDocSpec.scala#config-balancing-pool