From b989c4cf3efdda62f9934ea1485fc1428feb475f Mon Sep 17 00:00:00 2001 From: Justin Pihony Date: Tue, 25 May 2021 09:12:49 -0400 Subject: [PATCH] Add more explicit docs of top level coexistence (#29921) --- akka-docs/src/main/paradox/typed/coexisting.md | 13 +++++++++++-- akka-docs/src/main/paradox/typed/from-classic.md | 5 ++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/akka-docs/src/main/paradox/typed/coexisting.md b/akka-docs/src/main/paradox/typed/coexisting.md index 2e4906f186..0165537f4c 100644 --- a/akka-docs/src/main/paradox/typed/coexisting.md +++ b/akka-docs/src/main/paradox/typed/coexisting.md @@ -88,7 +88,17 @@ Java @scala[That adds some implicit extension methods that are added to classic and typed `ActorSystem`, `ActorContext` and `ActorRef` in both directions.] @java[To convert between typed and classic `ActorSystem`, `ActorContext` and `ActorRef` in both directions there are adapter methods in `akka.actor.typed.javadsl.Adapter`.] -Note the inline comments in the example above. +Note the inline comments in the example above. + +This method of using a top level classic actor is the suggested path for this type of co-existence. However, if you prefer to start with a typed top level actor then you can use the @scala[implicit `spawn` -method]@java[`Adapter.spawn`] directly from the typed system: + +Scala +: @@snip [TypedWatchingClassicSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/coexistence/TypedWatchingClassicSpec.scala) { #create } + +Java +: @@snip [TypedWatchingClassicTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/coexistence/TypedWatchingClassicTest.java) { #create } + +The above classic-typed difference is further elaborated in @ref:[the `ActorSystem` section](./from-classic.md#actorsystem) of "Learning Akka Typed from Classic". ## Typed to classic @@ -145,4 +155,3 @@ the child, for example if a classic actor creates a typed child, its default sup actor creates a classic child, its default supervision will be to restart. - diff --git a/akka-docs/src/main/paradox/typed/from-classic.md b/akka-docs/src/main/paradox/typed/from-classic.md index af44bb28da..387214b05a 100644 --- a/akka-docs/src/main/paradox/typed/from-classic.md +++ b/akka-docs/src/main/paradox/typed/from-classic.md @@ -159,7 +159,10 @@ typically performed from the "outside". The `actorOf` method of the classic `ActorSystem` is typically used to create a few (or many) top level actors. The `ActorSystem` in Typed doesn't have that capability. Instead, such actors are started as children of -the user guardian actor or children of other actors in the actor hierarchy. +the user guardian actor or children of other actors in the actor hierarchy. The rationale for this is partly about consistency. +In a typed system you can’t create children to an arbitrary actor from anywhere in your app without messaging it, +so this will also hold true for the user guardian actor. That noted, in cases where you do need to spawn outside of this guardian +then you can use the @ref:[`SpawnProtocol`](./actor-lifecycle.md#spawnprotocol) to spawn as needed. ## become