pjfanning commented on code in PR #3664:
URL: https://github.com/apache/pekko/pull/3664#discussion_r4358091101
##########
docs/src/main/paradox/typed/from-classic.md:
##########
@@ -306,6 +306,25 @@ removes the need for `pipeTo`. However, for interactions
with other APIs that re
@scala[`Future`]@java[`CompletionStage`] it is still useful to send the result
as a message to the actor.
For this purpose there is a `pipeToSelf` method in the `ActorContext` in Typed.
+## ActorContext
+
+The @apidoc[ActorContext](typed.*.ActorContext) belongs to the running actor.
A behavior can access it through
+@apidoc[Behaviors.setup](typed.*.Behaviors$), and nested setup blocks for the
same actor receive the same context.
+Returning a different behavior does not create a different actor or context.
+
+An `ActorRef` provides access to the actor from the outside, while its
`ActorContext` provides operations for
+the actor's current behavior, such as spawning children, logging and accessing
its own reference.
+Follow the @ref:[ActorContext thread safety
rules](actor-lifecycle.md#actorcontext-thread-safety) when using these
operations.
+
+The context and the current behavior have different responsibilities. In
Classic, an actor class contains
+state and defines a `Receive` behavior, while the context provides actor
operations. In Typed, a
+@apidoc[AbstractBehavior](typed.*.AbstractBehavior) can hold mutable state, or
a function-based behavior can
+return a new behavior carrying updated state for the next message. In either
style, changing the behavior
+does not change the identity of the running actor.
+
+On a supervised restart, setup and behavior construction may run again; do not
assume that an
+`AbstractBehavior` instance survives a restart. See @ref:[fault
tolerance](fault-tolerance.md) for the restart lifecycle.
Review Comment:
Could this say what actually re-runs? Only the behavior wrapped by
`Behaviors.supervise` is re-created on restart. A `setup` outside the
`supervise` does not run again, and the `ActorContext` is kept. Readers coming
from Classic `preRestart`/`postRestart` will want that distinction. For example:
```suggestion
On a supervised restart, the behavior wrapped by `Behaviors.supervise` is
created again from its initial definition,
including any `Behaviors.setup` inside it, while a `setup` outside the
`supervise` does not run again and the
`ActorContext` stays the same. Do not assume that an `AbstractBehavior`
instance survives a restart.
See @ref:[fault tolerance](fault-tolerance.md) for the restart lifecycle.
```
##########
docs/src/main/paradox/typed/from-classic.md:
##########
@@ -306,6 +306,25 @@ removes the need for `pipeTo`. However, for interactions
with other APIs that re
@scala[`Future`]@java[`CompletionStage`] it is still useful to send the result
as a message to the actor.
For this purpose there is a `pipeToSelf` method in the `ActorContext` in Typed.
+## ActorContext
+
+The @apidoc[ActorContext](typed.*.ActorContext) belongs to the running actor.
A behavior can access it through
+@apidoc[Behaviors.setup](typed.*.Behaviors$), and nested setup blocks for the
same actor receive the same context.
Review Comment:
nit: the other `Behaviors.setup` links in the docs (e.g.
`actor-lifecycle.md`, `actors.md`) add the method anchor so the link goes to
`setup` rather than the `Behaviors` page:
```
@apidoc[Behaviors.setup](typed.*.Behaviors$)
{scala="#setup[T](factory:org.apache.pekko.actor.typed.scaladsl.ActorContext[T]=%3Eorg.apache.pekko.actor.typed.Behavior[T]):org.apache.pekko.actor.typed.Behavior[T]"
java="#setup(org.apache.pekko.japi.function.Function)"}
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
