DOC: Added recommendation about naming actors and added name to some samples

akka-actor/src/main/scala/akka/actor/ActorCell.scala

@@ -14,7 +14,6 @@ import akka.util.{ Duration, Helpers }
 import akka.japi.Procedure
 import java.io.{ NotSerializableException, ObjectOutputStream }
 
-
 //TODO: everything here for current compatibility - could be limited more
 
 /**

akka-docs/java/code/akka/docs/actor/FirstUntypedActor.java

@@ -7,7 +7,7 @@ import akka.actor.UntypedActor;
 
 //#context-actorOf
 public class FirstUntypedActor extends UntypedActor {
-  ActorRef myActor = getContext().actorOf(new Props(MyActor.class));
+  ActorRef myActor = getContext().actorOf(new Props(MyActor.class), "myactor");
 
   //#context-actorOf
 

akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java

@@ -58,7 +58,7 @@ public class UntypedActorDocTestBase {
   public void systemActorOf() {
     //#system-actorOf
     ActorSystem system = ActorSystem.create("MySystem");
-    ActorRef myActor = system.actorOf(new Props(MyUntypedActor.class));
+    ActorRef myActor = system.actorOf(new Props(MyUntypedActor.class), "myactor");
     //#system-actorOf
     myActor.tell("test");
     system.shutdown();
@@ -68,7 +68,7 @@ public class UntypedActorDocTestBase {
   public void contextActorOf() {
     //#context-actorOf
     ActorSystem system = ActorSystem.create("MySystem");
-    ActorRef myActor = system.actorOf(new Props(MyUntypedActor.class));
+    ActorRef myActor = system.actorOf(new Props(MyUntypedActor.class), "myactor");
     //#context-actorOf
     myActor.tell("test");
     system.shutdown();
@@ -83,7 +83,7 @@ public class UntypedActorDocTestBase {
       public UntypedActor create() {
         return new MyActor("...");
       }
-    }));
+    }), "myactor");
     //#creating-constructor
     myActor.tell("test");
     system.shutdown();
@@ -94,9 +94,8 @@ public class UntypedActorDocTestBase {
     ActorSystem system = ActorSystem.create("MySystem");
     //#creating-props
     MessageDispatcher dispatcher = system.dispatcherFactory().lookup("my-dispatcher");
-    ActorRef myActor = system.actorOf(
+    ActorRef myActor = system.actorOf(new Props().withCreator(MyUntypedActor.class).withDispatcher(dispatcher),
-      new Props().withCreator(MyUntypedActor.class).withDispatcher(dispatcher),
+        "myactor");
-      "myactor");
     //#creating-props
     myActor.tell("test");
     system.shutdown();
@@ -109,7 +108,7 @@ public class UntypedActorDocTestBase {
       public UntypedActor create() {
         return new MyAskActor();
       }
-    }));
+    }), "myactor");
 
     //#using-ask
     Future<Object> future = myActor.ask("Hello", 1000);

akka-docs/java/untyped-actors.rst

@@ -78,6 +78,11 @@ a top level actor, that is supervised by the system (internal guardian actor).
 
 .. includecode:: code/akka/docs/actor/FirstUntypedActor.java#context-actorOf
 
+The name parameter is optional, but you should preferably name your actors, since
+that is used in log messages and for identifying actors. The name must not be empty
+or start with ``$``. If the given name is already in use by another child to the
+same parent actor an `InvalidActorNameException` is thrown.
+
 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

@@ -72,6 +72,11 @@ a top level actor, that is supervised by the system (internal guardian actor).
 
 .. includecode:: code/akka/docs/actor/ActorDocSpec.scala#context-actorOf
 
+The name parameter is optional, but you should preferably name your actors, since
+that is used in log messages and for identifying actors. The name must not be empty
+or start with ``$``. If the given name is already in use by another child to the
+same parent actor an `InvalidActorNameException` is thrown.
+
 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

akka-docs/scala/code/akka/docs/actor/ActorDocSpec.scala

@@ -33,7 +33,7 @@ case class Message(s: String)
 
 //#context-actorOf
 class FirstActor extends Actor {
-  val myActor = context.actorOf(Props[MyActor])
+  val myActor = context.actorOf(Props[MyActor], name = "myactor")
   //#context-actorOf
   //#anonymous-actor
   def receive = {
@@ -56,7 +56,7 @@ class FirstActor extends Actor {
 //#system-actorOf
 object Main extends App {
   val system = ActorSystem("MySystem")
-  val myActor = system.actorOf(Props[MyActor])
+  val myActor = system.actorOf(Props[MyActor], name = "myactor")
   //#system-actorOf
 }
 
@@ -98,7 +98,7 @@ class Swapper extends Actor {
 
 object SwapperApp extends App {
   val system = ActorSystem("SwapperSystem")
-  val swap = system.actorOf(Props[Swapper])
+  val swap = system.actorOf(Props[Swapper], name = "swapper")
   swap ! Swap // logs Hi
   swap ! Swap // logs Ho
   swap ! Swap // logs Hi
@@ -138,14 +138,14 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     //#import-context
     class FirstActor extends Actor {
       import context._
-      val myActor = actorOf(Props[MyActor])
+      val myActor = actorOf(Props[MyActor], name = "myactor")
       def receive = {
         case x ⇒ myActor ! x
       }
     }
     //#import-context
 
-    val first = system.actorOf(Props(new FirstActor))
+    val first = system.actorOf(Props(new FirstActor), name = "first")
     system.stop(first)
 
   }
@@ -182,7 +182,7 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
 
     //#creating-constructor
     // allows passing in arguments to the MyActor constructor
-    val myActor = system.actorOf(Props(new MyActor("...")))
+    val myActor = system.actorOf(Props(new MyActor("...")), name = "myactor")
     //#creating-constructor
 
     system.stop(myActor)
@@ -224,7 +224,7 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
       }
     }
 
-    val myActor = system.actorOf(Props(new MyActor))
+    val myActor = system.actorOf(Props(new MyActor), name = "myactor")
     implicit val timeout = system.settings.ActorTimeout
     val future = myActor ? "hello"
     for (x ← future) println(x) //Prints "hello"
@@ -270,6 +270,6 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     }
     //#hot-swap-actor
 
-    val actor = system.actorOf(Props(new HotSwapActor))
+    val actor = system.actorOf(Props(new HotSwapActor), name = "hot")
   }
 }