document creator requirement, see #2131

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; <code>ActorSystem.actorOf</code> and <code>ActorContext.actorOf</code>.
  *
+ * 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)

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
 }
 

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
 ---------------------
 

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
 ================

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
 -----