diff --git a/akka-actor/src/main/scala/akka/actor/Props.scala b/akka-actor/src/main/scala/akka/actor/Props.scala
index 292a437dab..f6552179c3 100644
--- a/akka-actor/src/main/scala/akka/actor/Props.scala
+++ b/akka-actor/src/main/scala/akka/actor/Props.scala
@@ -87,6 +87,8 @@ object Props {
* Props is a ActorRef configuration object, that is thread safe and fully sharable.
* Used when creating new actors through; ActorSystem.actorOf and ActorContext.actorOf.
*
+ * In case of providing code which creates the actual Actor instance, that must not return the same instance multiple times.
+ *
* Examples on Scala API:
* {{{
* val props = Props[MyActor]
@@ -144,6 +146,8 @@ case class Props(
/**
* Returns a new Props with the specified creator set.
+ *
+ * The creator must not return the same instance multiple times.
*
* Scala API.
*/
@@ -152,6 +156,8 @@ case class Props(
/**
* Returns a new Props with the specified creator set.
*
+ * The creator must not return the same instance multiple times.
+ *
* Java API.
*/
def withCreator(c: Creator[Actor]): Props = copy(creator = () ⇒ c.create)
diff --git a/akka-actor/src/main/scala/akka/japi/JavaAPI.scala b/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
index 5bd38ad52a..b0db141aee 100644
--- a/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
+++ b/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
@@ -38,6 +38,9 @@ trait Effect {
* A constructor/factory, takes no parameters but creates a new value of type T every call.
*/
trait Creator[T] {
+ /**
+ * This method must return a different instance upon every call.
+ */
def create(): T
}
diff --git a/akka-docs/general/supervision.rst b/akka-docs/general/supervision.rst
index fef3a585dd..c1bc684ce4 100644
--- a/akka-docs/general/supervision.rst
+++ b/akka-docs/general/supervision.rst
@@ -55,6 +55,8 @@ actors cannot be orphaned or attached to supervisors from the outside, which
might otherwise catch them unawares. In addition, this yields a natural and
clean shutdown procedure for (sub-trees of) actor applications.
+.. _supervision-restart:
+
What Restarting Means
---------------------
diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst
index d7c99199ed..9ee8d5ba47 100644
--- a/akka-docs/java/untyped-actors.rst
+++ b/akka-docs/java/untyped-actors.rst
@@ -115,6 +115,12 @@ Here is an example:
This way of creating the Actor is also great for integrating with Dependency Injection
(DI) frameworks like Guice or Spring.
+.. warning::
+
+ You might be tempted at times to offer an ``UntypedActor`` factory which
+ always returns the same instance, e.g. by using a static field. This is not
+ supported, as it works against the meaning of an actor restart, which is
+ described here: :ref:`supervision-restart`.
UntypedActor API
================
diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst
index 92c335120a..66b775aa0f 100644
--- a/akka-docs/scala/actors.rst
+++ b/akka-docs/scala/actors.rst
@@ -105,6 +105,13 @@ Here is an example:
.. includecode:: code/docs/actor/ActorDocSpec.scala#creating-constructor
+.. warning::
+
+ You might be tempted at times to offer an ``Actor`` factory which always
+ returns the same instance, e.g. by using a ``lazy val`` or an
+ ``object ... extends Actor``. This is not supported, as it works against the
+ meaning of an actor restart, which is described here:
+ :ref:`supervision-restart`.
Props
-----