diff --git a/akka-docs/general/actor-systems.rst b/akka-docs/general/actor-systems.rst index d3113d85be..ef922293a8 100644 --- a/akka-docs/general/actor-systems.rst +++ b/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 ----------------------------------------- diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst index 4ba40a8f1f..89553f091a 100644 --- a/akka-docs/java/untyped-actors.rst +++ b/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 diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst index 6c819facda..0c98960db1 100644 --- a/akka-docs/scala/actors.rst +++ b/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