document blocking nature of system.actorOf, see #2007

akka-docs/general/actor-systems.rst

@@ -101,6 +101,12 @@ Actor Best Practices
    breaks all the properties which make programming in actors such a nice
    experience.
 
+#. Top-level actors are the innermost part of your Error Kernel, so create them
+   sparingly and prefer truly hierarchical systems. This has benefits wrt.
+   fault-handling (both considering the granularity of configuration and the
+   performance) and it also reduces the number of blocking calls made, since
+   the creation of top-level actors involves synchronous messaging.
+
 What you should not concern yourself with
 -----------------------------------------
 

akka-docs/java/untyped-actors.rst

@@ -82,6 +82,13 @@ that is used in log messages and for identifying actors. The name must not be em
 or start with ``$``. If the given name is already in use by another child to the
 same parent actor an `InvalidActorNameException` is thrown.
 
+.. warning::
+
+  Creating top-level actors with ``system.actorOf`` is a blocking operation,
+  hence it may dead-lock due to starvation if the default dispatcher is
+  overloaded. To avoid problems, do not call this method from within actors or
+  futures which run on the default dispatcher.
+
 Actors are automatically started asynchronously when created.
 When you create the ``UntypedActor`` then it will automatically call the ``preStart``
 callback method on the ``UntypedActor`` class. This is an excellent place to

akka-docs/scala/actors.rst

@@ -76,6 +76,13 @@ that is used in log messages and for identifying actors. The name must not be em
 or start with ``$``. If the given name is already in use by another child to the
 same parent actor an `InvalidActorNameException` is thrown.
 
+.. warning::
+
+  Creating top-level actors with ``system.actorOf`` is a blocking operation,
+  hence it may dead-lock due to starvation if the default dispatcher is
+  overloaded. To avoid problems, do not call this method from within actors or
+  futures which run on the default dispatcher.
+
 Actors are automatically started asynchronously when created.
 When you create the ``Actor`` then it will automatically call the ``preStart``
 callback method on the ``Actor`` trait. This is an excellent place to