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