various documentation patches, found at the bottom of my inbox

akka-actor/src/main/scala/akka/actor/ActorCell.scala

@@ -502,7 +502,7 @@ private[akka] class ActorCell(
       if (success) true
       else {
         val parent: Class[_] = clazz.getSuperclass
-        if (parent eq null) throw new IllegalActorStateException(toString + " is not an Actor since it have not mixed in the 'Actor' trait")
+        if (parent eq null) throw new IllegalActorStateException(actorInstance.getClass + " is not an Actor since it have not mixed in the 'Actor' trait")
         lookupAndSetField(parent, actor, name, value)
       }
     }

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

@@ -48,6 +48,7 @@
         </div>    
         <ul class="nav">
           <li><a href="http://akka.io/docs">Documentation</a></li>
+          <li><a href="http://akka.io/faq">FAQ</a></li>
           <li><a href="http://akka.io/downloads">Download</a></li>
           <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
           <li><a href="http://github.com/akka/akka">Code</a></li>           
@@ -111,15 +112,17 @@
     <ul>
       <li><h5>Akka</h5></li>
       <li><a href="http://akka.io/docs">Documentation</a></li>
+      <li><a href="http://akka.io/faq">FAQ</a></li>
       <li><a href="http://akka.io/downloads">Downloads</a></li>
       <li><a href="http://akka.io/news">News</a></li>
       <li><a href="http://letitcrash.com">Blog</a></li>
     </ul>
     <ul>
       <li><h5>Contribute</h5></li>
+      <li><a href="http://akka.io/community">Community Projects</a></li>
       <li><a href="http://github.com/akka/akka">Source Code</a></li>
       <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>      
-      <li><a href="http://www.assembla.com/spaces/akka/tickets">Report a Bug</a></li>      
+      <li><a href="http://doc.akka.io/docs/akka/current/project/issue-tracking.html">Report a Bug</a></li>      
     </ul>
     <ul>
       <li><h5>Company</h5></li>

akka-docs/general/message-send-semantics.rst

@@ -66,4 +66,51 @@ This means that:
     5) ``A2`` can see messages from ``A1`` interleaved with messages from ``A3``
     6) Since there is no guaranteed delivery, none, some or all of the messages may arrive to ``A2``
 
+.. _deadletters:
+
+Dead Letters
+============
+
+Messages which cannot be delivered (and for which this can be ascertained) will
+be delivered to a synthetic actor called ``/deadLetters``. This delivery
+happens on a best-effort basis; it may fail even within the local JVM (e.g.
+during actor termination). Messages sent via unreliable network transports will
+be lost without turning up as dead letters.
+
+How do I Receive Dead Letters?
+------------------------------
+
+An actor can subscribe to class :class:`akka.actor.DeadLetter` on the event
+stream, see :ref:`event-stream-java` (Java) or :ref:`event-stream-scala`
+(Scala) for how to do that. The subscribed actor will then receive all dead
+letters published in the (local) system from that point onwards. Dead letters
+are not propagated over the network, if you want to collect them in one place
+you will have to subscribe one actor per network node and forward them
+manually. Also consider that dead letters are generated at that node which can
+determine that a send operation is failed, which for a remote send can be the
+local system (if no network connection can be established) or the remote one
+(if the actor you are sending to does not exist at that point in time).
+
+What Should I Use Dead Letters For?
+-----------------------------------
+
+The dead letter service follows the same rules with respect to delivery
+guarantees as all other message sends, hence it cannot be used to implement
+guaranteed delivery. The main use is for debugging, especially if an actor send
+does not arrive consistently (where usually inspecting the dead letters will
+tell you that the sender or recipient was set wrong somewhere along the way).
+
+Dead Letters Which are (Usually) not Worrisome
+----------------------------------------------
+
+Every time an actor does not terminate by its own decision, there is a chance
+that some messages are lost which it sends to itself. There is one which may
+happen in complex shutdown scenarios quite easily which is usually benign:
+seeing a :class:`akka.dispatch.Terminate` message dropped means that two
+termination requests were given, but of course only one can succeed. In the
+same vein, you might see :class:`akka.actor.Terminated` messages from children
+while stopping a hierarchy of actors turning up in dead letters if the parent
+is still watching the child when the parent terminates.
+
 .. _Erlang documentation: http://www.erlang.org/faq/academic.html
+

akka-docs/general/supervision.rst

@@ -141,17 +141,17 @@ re-processed.
 
 The precise sequence of events during a restart is the following:
 
-* suspend the actor
+#. suspend the actor (which means that it will not process normal messages until
-* call the old instance’s :meth:`supervisionStrategy.handleSupervisorFailing`
+   resumed), and recursively suspend all children
-  method (defaults to suspending all children)
+#. call the old instance’s :meth:`preRestart` hook (defaults to sending
-* call the old instance’s :meth:`preRestart` hook (defaults to sending
+   termination requests to all children and calling :meth:`postStop`)
-  termination requests to all children and calling :meth:`postStop`)
+#. wait for all children which were requested to terminate (using
-* wait for all children stopped during :meth:`preRestart` to actually terminate
+   ``context.stop()``) during :meth:`preRestart` to actually terminate
-* call the old instance’s :meth:`supervisionStrategy.handleSupervisorRestarted`
+#. create new actor instance by invoking the originally provided factory again
-  method (defaults to sending restart request to all remaining children)
+#. invoke :meth:`postRestart` on the new instance
-* create new actor instance by invoking the originally provided factory again
+#. send restart request to all children (they will follow the same process
-* invoke :meth:`postRestart` on the new instance
+   recursively, from step 2)
-* resume the actor
+#. resume the actor
 
 What Lifecycle Monitoring Means
 -------------------------------

akka-docs/java/remoting.rst

@@ -116,6 +116,16 @@ As you can see from the example above the following pattern is used to find an `
   object, which in most cases is not serializable. It is best to make a static
   inner class which implements :class:`UntypedActorFactory`.
 
+.. warning::
+
+  *Caveat:* Remote deployment ties both systems together in a tight fashion,
+  where it may become impossible to shut down one system after the other has
+  become unreachable. This is due to a missing feature—which will be part of
+  the clustering support—that hooks up network failure detection with
+  DeathWatch. If you want to avoid this strong coupling, do not remote-deploy
+  but send ``Props`` to a remotely looked-up actor and have that create a
+  child, returning the resulting actor reference.
+
 Programmatic Remote Deployment
 ------------------------------
 

akka-docs/java/testing.rst

@@ -46,8 +46,8 @@ The tools offered are described in detail in the following sections.
 
    Be sure to add the module :mod:`akka-testkit` to your dependencies.
 
-Unit Testing with :class:`TestActorRef`
+Synchronous Unit Testing with :class:`TestActorRef`
-=======================================
+===================================================
 
 Testing the business logic inside :class:`Actor` classes can be divided into
 two parts: first, each atomic operation must work in isolation, then sequences
@@ -141,8 +141,8 @@ Feel free to experiment with the possibilities, and if you find useful
 patterns, don't hesitate to let the Akka forums know about them! Who knows,
 common operations might even be worked into nice DSLs.
 
-Integration Testing with :class:`JavaTestKit`
+Asynchronous Integration Testing with :class:`JavaTestKit`
-=============================================
+==========================================================
 
 When you are reasonably sure that your actor's business logic is correct, the
 next step is verifying that it works correctly within its intended environment.
@@ -489,6 +489,15 @@ queued invocations from all threads into its own queue and process them.
 Limitations
 -----------
 
+.. warning::
+
+   In case the CallingThreadDispatcher is used for top-level actors, but
+   without going through TestActorRef, then there is a time window during which
+   the actor is awaiting construction by the user guardian actor. Sending
+   messages to the actor during this time period will result in them being
+   enqueued and then executed on the guardian’s thread instead of the caller’s
+   thread. To avoid this, use TestActorRef.
+
 If an actor's behavior blocks on a something which would normally be affected
 by the calling actor after having sent the message, this will obviously
 dead-lock when using this dispatcher. This is a common scenario in actor tests

akka-docs/scala/remoting.rst

@@ -125,6 +125,16 @@ actor systems has to have a JAR containing the class.
   most cases is not serializable. It is best to create a factory method in the
   companion object of the actor’s class.
 
+.. warning::
+
+  *Caveat:* Remote deployment ties both systems together in a tight fashion,
+  where it may become impossible to shut down one system after the other has
+  become unreachable. This is due to a missing feature—which will be part of
+  the clustering support—that hooks up network failure detection with
+  DeathWatch. If you want to avoid this strong coupling, do not remote-deploy
+  but send ``Props`` to a remotely looked-up actor and have that create a
+  child, returning the resulting actor reference.
+
 Programmatic Remote Deployment
 ------------------------------
 

akka-docs/scala/testing.rst

@@ -35,8 +35,8 @@ The tools offered are described in detail in the following sections.
 
    Be sure to add the module :mod:`akka-testkit` to your dependencies.
 
-Unit Testing with :class:`TestActorRef`
+Synchronous Unit Testing with :class:`TestActorRef`
-=======================================
+===================================================
 
 Testing the business logic inside :class:`Actor` classes can be divided into
 two parts: first, each atomic operation must work in isolation, then sequences
@@ -151,8 +151,8 @@ Feel free to experiment with the possibilities, and if you find useful
 patterns, don't hesitate to let the Akka forums know about them! Who knows,
 common operations might even be worked into nice DSLs.
 
-Integration Testing with :class:`TestKit`
+Asynchronous Integration Testing with :class:`TestKit`
-=========================================
+======================================================
 
 When you are reasonably sure that your actor's business logic is correct, the
 next step is verifying that it works correctly within its intended environment
@@ -548,6 +548,15 @@ queued invocations from all threads into its own queue and process them.
 Limitations
 -----------
 
+.. warning::
+
+   In case the CallingThreadDispatcher is used for top-level actors, but
+   without going through TestActorRef, then there is a time window during which
+   the actor is awaiting construction by the user guardian actor. Sending
+   messages to the actor during this time period will result in them being
+   enqueued and then executed on the guardian’s thread instead of the caller’s
+   thread. To avoid this, use TestActorRef.
+
 If an actor's behavior blocks on a something which would normally be affected
 by the calling actor after having sent the message, this will obviously
 dead-lock when using this dispatcher. This is a common scenario in actor tests