From e94d011cbd43746531982f0540cb101739f5d6ad Mon Sep 17 00:00:00 2001 From: Roman Filonenko Date: Mon, 2 Jul 2018 14:31:39 +0200 Subject: [PATCH] populate Creating Actors section in the akka typed documentation (#25218) (#25236) * populate Creating Actors section in the akka typed documentation (#25218) --- .../actor/typed/DispatcherSelectorTest.java | 4 --- .../test/java/jdocs/akka/typed/IntroTest.java | 33 +++++++++++++++++ .../scala/docs/akka/typed/IntroSpec.scala | 23 +++++++++++- .../scala/akka/actor/typed/ActorSystem.scala | 2 -- .../main/scala/akka/actor/typed/Props.scala | 6 ++-- .../akka/actor/typed/javadsl/Behaviors.scala | 7 ++-- .../src/main/paradox/typed/actor-lifecycle.md | 36 ++++++++++++++++++- 7 files changed, 96 insertions(+), 15 deletions(-) diff --git a/akka-actor-typed-tests/src/test/java/akka/actor/typed/DispatcherSelectorTest.java b/akka-actor-typed-tests/src/test/java/akka/actor/typed/DispatcherSelectorTest.java index 01af6af6d0..45e5d58f81 100644 --- a/akka-actor-typed-tests/src/test/java/akka/actor/typed/DispatcherSelectorTest.java +++ b/akka-actor-typed-tests/src/test/java/akka/actor/typed/DispatcherSelectorTest.java @@ -4,10 +4,6 @@ package akka.actor.typed; -import scala.concurrent.ExecutionContext; - -import java.util.concurrent.Executor; - public class DispatcherSelectorTest { // Compile time only test to verify // dispatcher factories are accessible from Java diff --git a/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java b/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java index e56d610fce..f71768ba8f 100644 --- a/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java +++ b/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java @@ -10,6 +10,8 @@ import akka.actor.typed.ActorRef; import akka.actor.typed.ActorSystem; import akka.actor.typed.Behavior; import akka.actor.typed.Terminated; +import akka.actor.typed.Props; +import akka.actor.typed.DispatcherSelector; import akka.actor.typed.javadsl.Behaviors; //#imports @@ -104,6 +106,37 @@ public class IntroTest { } //#hello-world-main + public abstract static class CustomDispatchersExample { + private CustomDispatchersExample() { + } + + public static class Start { + public final String name; + + public Start(String name) { + this.name = name; + } + } + + //#hello-world-main-with-dispatchers + public static final Behavior main = + Behaviors.setup( context -> { + final String dispatcherPath = "akka.actor.default-blocking-io-dispatcher"; + + Props props = DispatcherSelector.fromConfig(dispatcherPath); + final ActorRef greeter = + context.spawn(HelloWorld.greeter, "greeter", props); + + return Behaviors.receiveMessage(msg -> { + ActorRef replyTo = + context.spawn(HelloWorldBot.bot(0, 3), msg.name); + greeter.tell(new HelloWorld.Greet(msg.name, replyTo)); + return Behaviors.same(); + }); + }); + //#hello-world-main-with-dispatchers + } + public static void main(String[] args) throws Exception { //#hello-world final ActorSystem system = diff --git a/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala b/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala index e44552335b..f8505844ef 100644 --- a/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala +++ b/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala @@ -7,7 +7,7 @@ package docs.akka.typed //#imports import akka.NotUsed import akka.actor.typed.scaladsl.Behaviors -import akka.actor.typed.{ ActorRef, ActorSystem, Behavior, Terminated } +import akka.actor.typed.{ ActorRef, ActorSystem, Behavior, DispatcherSelector, Terminated } //#imports import akka.actor.testkit.typed.scaladsl.ActorTestKit @@ -68,6 +68,27 @@ object IntroSpec { } //#hello-world-main + object CustomDispatchersExample { + import HelloWorldMain.Start + + //#hello-world-main-with-dispatchers + val main: Behavior[Start] = + Behaviors.setup { context ⇒ + val dispatcherPath = "akka.actor.default-blocking-io-dispatcher" + + val props = DispatcherSelector.fromConfig(dispatcherPath) + val greeter = context.spawn(HelloWorld.greeter, "greeter", props) + + Behaviors.receiveMessage { msg ⇒ + val replyTo = context.spawn(HelloWorldBot.bot(greetingCounter = 0, max = 3), msg.name) + + greeter ! HelloWorld.Greet(msg.name, replyTo) + Behaviors.same + } + } + //#hello-world-main-with-dispatchers + } + //#chatroom-actor object ChatRoom { //#chatroom-protocol diff --git a/akka-actor-typed/src/main/scala/akka/actor/typed/ActorSystem.scala b/akka-actor-typed/src/main/scala/akka/actor/typed/ActorSystem.scala index e3057a6ab6..229b30f8fb 100644 --- a/akka-actor-typed/src/main/scala/akka/actor/typed/ActorSystem.scala +++ b/akka-actor-typed/src/main/scala/akka/actor/typed/ActorSystem.scala @@ -4,7 +4,6 @@ package akka.actor.typed -import scala.concurrent.ExecutionContext import akka.{ actor ⇒ a } import java.util.concurrent.{ CompletionStage, ThreadFactory } @@ -16,7 +15,6 @@ import akka.actor.typed.internal.adapter.{ ActorSystemAdapter, PropsAdapter } import akka.util.Timeout import akka.annotation.DoNotInherit import akka.annotation.ApiMayChange -import java.util.Optional import akka.actor.BootstrapSetup import akka.actor.typed.internal.adapter.GuardianActorAdapter diff --git a/akka-actor-typed/src/main/scala/akka/actor/typed/Props.scala b/akka-actor-typed/src/main/scala/akka/actor/typed/Props.scala index f5289a402f..abbce37130 100644 --- a/akka-actor-typed/src/main/scala/akka/actor/typed/Props.scala +++ b/akka-actor-typed/src/main/scala/akka/actor/typed/Props.scala @@ -148,19 +148,19 @@ sealed abstract class DispatcherSelector extends Props * on the options. * * The default configuration if none of these options are present is to run - * the actor on the same executor as its parent. + * the actor on the default [[ActorSystem]] executor. */ object DispatcherSelector { /** * Scala API: - * Run the actor on the same executor as its parent. + * Run the actor on the default [[ActorSystem]] executor. */ def default(): DispatcherSelector = DispatcherDefault() /** * Java API: - * Run the actor on the same executor as its parent. + * Run the actor on the default [[ActorSystem]] executor. */ def defaultDispatcher(): DispatcherSelector = default() diff --git a/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/Behaviors.scala b/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/Behaviors.scala index c2ffa1b2f4..a54ab0723f 100644 --- a/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/Behaviors.scala +++ b/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/Behaviors.scala @@ -12,7 +12,6 @@ import akka.actor.typed.internal.{ BehaviorImpl, Supervisor, TimerSchedulerImpl, import akka.annotation.{ ApiMayChange, DoNotInherit } import akka.japi.function.{ Procedure2, Function2 ⇒ JapiFunction2 } import akka.japi.pf.PFBuilder -import akka.util.ConstantFun import scala.collection.JavaConverters._ import scala.reflect.ClassTag /** @@ -245,11 +244,11 @@ object Behaviors { * * Example: * {{{ - * Behavior<String> s = immutable((ctx, msg) -> { + * Behavior s = Behaviors.receive((ctx, msg) -> { * System.out.println(msg); - * return same(); + * return Behaviors.same(); * }); - * Behavior<Number> n = widened(s, pf -> pf. + * Behavior n = Behaviors.widened(s, pf -> pf. * match(BigInteger.class, i -> "BigInteger(" + i + ")"). * match(BigDecimal.class, d -> "BigDecimal(" + d + ")") * // drop all other kinds of Number diff --git a/akka-docs/src/main/paradox/typed/actor-lifecycle.md b/akka-docs/src/main/paradox/typed/actor-lifecycle.md index 6217a18882..12a4c19cf9 100644 --- a/akka-docs/src/main/paradox/typed/actor-lifecycle.md +++ b/akka-docs/src/main/paradox/typed/actor-lifecycle.md @@ -16,7 +16,41 @@ TODO intro ## Creating Actors -TODO +An actor can create, or _spawn_, an arbitrary number of child actors, which in turn can spawn children of their own, thus +forming an actor hierarchy. @unidoc[akka.actor.typed.ActorSystem] hosts the hierarchy and there can be only one _root actor_, +actor at the top of the hierarchy, per `ActorSystem`. The lifecycle of a child actor is tied to the parent -- a child +can stop itself or be stopped at any time but it can never outlive its parent. + +The root actor, also called the guardian actor, is created along with the `ActorSystem`. Messages sent to the actor system are directed to the root actor. +The root actor is defined by the behavior used to create the `ActorSystem`, named `HelloWorldMain.main` in the example below: + +Scala +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world } + +Java +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world } + + +Child actors are spawned with @unidoc[akka.actor.typed.ActorContext]'s `spawn`. In the example below, when the root actor +is started, it spawns a child actor described by the behavior `HelloWorld.greeter`. Additionally, when the root actor receives a +`Start` message, it creates a child actor defined by the behavior `HelloWorldBot.bot`: + +Scala +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main } + +Java +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main } + +To specify a dispatcher when spawning an actor use @unidoc[DispatcherSelector]. If not specified, the actor will +use the default dispatcher, see @ref:[Default dispatcher](../dispatchers.md#default-dispatcher) for details. + +Scala +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main-with-dispatchers } + +Java +: @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main-with-dispatchers } + +Refer to @ref:[Actors](actors.md#introduction) for a walk-through of the above examples. ## Stopping Actors