Merge branch 'tmp'

akka-docs/rst/general/actors.rst

@@ -6,7 +6,7 @@ What is an Actor?
 The previous section about :ref:`actor-systems` explained how actors form
 hierarchies and are the smallest unit when building an application. This
 section looks at one such actor in isolation, explaining the concepts you
-encounter while implementing it. For more an in depth reference with all the
+encounter while implementing it. For a more in depth reference with all the
 details please refer to :ref:`actors-scala` and :ref:`untyped-actors-java`.
 
 An actor is a container for `State`_, `Behavior`_, a `Mailbox`_, `Children`_

akka-docs/rst/general/addressing.rst

@@ -29,11 +29,11 @@ There are several different types of actor references that are supported
 depending on the configuration of the actor system:
 
 - Purely local actor references are used by actor systems which are not
-  configured to support networking functions. These actor references cannot
+  configured to support networking functions. These actor references will not
-  ever be sent across a network connection while retaining their functionality.
+  function if sent across a network connection to a remote JVM.
 - Local actor references when remoting is enabled are used by actor systems
   which support networking functions for those references which represent
-  actors within the same JVM. In order to be recognizable also when sent to
+  actors within the same JVM. In order to also be reachable when sent to
   other network nodes, these references include protocol and remote addressing
   information.
 - There is a subtype of local actor references which is used for routers (i.e.
@@ -42,21 +42,21 @@ depending on the configuration of the actor system:
   them dispatches to one of their children directly instead.
 - Remote actor references represent actors which are reachable using remote
   communication, i.e. sending messages to them will serialize the messages
-  transparently and send them to the other JVM.
+  transparently and send them to the remote JVM.
 - There are several special types of actor references which behave like local
   actor references for all practical purposes:
 
-  - :class:`PromiseActorRef` is the special representation of a :meth:`Promise` for
+  - :class:`PromiseActorRef` is the special representation of a :meth:`Promise`
-    the purpose of being completed by the response from an actor; it is created
+    for the purpose of being completed by the response from an actor.
-    by the :meth:`ActorRef.ask` invocation.
+    :meth:`akka.pattern.ask` creates this actor reference.
   - :class:`DeadLetterActorRef` is the default implementation of the dead
-    letters service, where all messages are re-routed whose routees are shut
+    letters service to which Akka routes all messages whose destinations
-    down or non-existent.
+    are shut down or non-existent.
-  - :class:`EmptyLocalActorRef` is what is returned when looking up a
+  - :class:`EmptyLocalActorRef` is what Akka returns when looking up a
-    non-existing local actor path: it is equivalent to a
+    non-existent local actor path: it is equivalent to a
-    :class:`DeadLetterActorRef`, but it retains its path so that it can be sent
+    :class:`DeadLetterActorRef`, but it retains its path so that Akka can send
-    over the network and compared to other existing actor refs for that path,
+    it over the network and compare it to other existing actor references for
-    some of which might have been obtained before the actor stopped existing.
+    that path, some of which might have been obtained before the actor died.
 
 - And then there are some one-off internal implementations which you should
   never really see:
@@ -103,7 +103,7 @@ actors in the hierarchy from the root up. Examples are::
   "cluster://my-cluster/service-c"                     // clustered (Future Extension)
 
 Here, ``akka`` is the default remote protocol for the 2.0 release, and others
-are pluggable. The interpretation of the host & port part (i.e.
+are pluggable. The interpretation of the host and port part (i.e.
 ``serv.example.com:5678`` in the example) depends on the transport mechanism
 used, but it must abide by the URI structural rules.
 
@@ -174,16 +174,16 @@ Looking up Actors by Concrete Path
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In addition, actor references may be looked up using the
-:meth:`ActorSystem.actorFor` method, which returns an (unverified) local,
+:meth:`ActorSystem.actorFor` method, which returns an (unverified) local, remote
-remote or clustered actor reference. Sending messages to such a reference or
+or clustered actor reference. Sending messages to such a reference or attempting
-attempting to observe its liveness will traverse the actor hierarchy of the
+to observe its liveness will traverse the actor hierarchy of the actor system
-actor system from top to bottom by passing messages from parent to child until
+from top to bottom by passing messages from parent to child until either the
-either the target is reached or failure is certain, i.e. a name in the path
+target is reached or failure is certain, i.e. a name in the path does not exist
-does not exist (in practice this process will be optimized using caches, but it
+(in practice this process will be optimized using caches, but it still has added
-still has added cost compared to using the physical actor path, which can for
+cost compared to using the physical actor path, which can for example be
-example be obtained from the sender reference included in replies from that
+obtained from the sender reference included in replies from that actor). Akka
-actor). The messages passed are handled automatically by Akka, so this process
+handles message passing automatically, so this process is not visible to client
-is not visible to client code.
+code.
 
 Absolute vs. Relative Paths
 ```````````````````````````

akka-docs/rst/general/supervision.rst

@@ -172,12 +172,13 @@ reacts to failure.
 
 Lifecycle monitoring is implemented using a :class:`Terminated` message to be
 received by the monitoring actor, where the default behavior is to throw a
-special :class:`DeathPactException` if not otherwise handled. In order to
+special :class:`DeathPactException` if not otherwise handled. In order to start
-start listening for :class:`Terminated` messages is to use ``ActorContext.watch(targetActorRef)``
+listening for :class:`Terminated` messages, invoke
-and then ``ActorContext.unwatch(targetActorRef)`` to stop listening for that.
+``ActorContext.watch(targetActorRef)``.  To stop listening, invoke
-One important property is that the message will be delivered irrespective of the order in
+``ActorContext.unwatch(targetActorRef)``.  One important property is that the
-which the monitoring request and target’s termination occur, i.e. you still get
+message will be delivered irrespective of the order in which the monitoring
-the message even if at the time of registration the target is already dead.
+request and target’s termination occur, i.e. you still get the message even if
+at the time of registration the target is already dead.
 
 Monitoring is particularly useful if a supervisor cannot simply restart its
 children and has to terminate them, e.g. in case of errors during actor
@@ -210,8 +211,8 @@ to all siblings as well. Normally, you should use the
 explicitly.
 
 The :class:`AllForOneStrategy` is applicable in cases where the ensemble of
-children has so tight dependencies among them, that a failure of one child
+children has such tight dependencies among them, that a failure of one child
-affects the function of the others, i.e. they are intricably linked. Since a
+affects the function of the others, i.e. they are inextricably linked. Since a
 restart does not clear out the mailbox, it often is best to terminate the children
 upon failure and re-create them explicitly from the supervisor (by watching the
 children’s lifecycle); otherwise you have to make sure that it is no problem
@@ -219,7 +220,7 @@ for any of the actors to receive a message which was queued before the restart
 but processed afterwards.
 
 Normally stopping a child (i.e. not in response to a failure) will not
-automatically terminate the other children in an all-for-one strategy, that can
+automatically terminate the other children in an all-for-one strategy; this can
 easily be done by watching their lifecycle: if the :class:`Terminated` message
 is not handled by the supervisor, it will throw a :class:`DeathPactException`
 which (depending on its supervisor) will restart it, and the default