This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new 43e18eb18b Clarify ActorContext and Behavior lifecycles (#3664)
43e18eb18b is described below
commit 43e18eb18bcc6bf060efff357bcb725beae216cc
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Fri Oct 23 21:27:22 2026 +0800
Clarify ActorContext and Behavior lifecycles (#3664)
* Clarify ActorContext and Behavior lifecycles
Motivation:
The classic-to-typed guide does not explain why ActorContext remains
associated with the actor while its Behavior can change.
Modification:
Explain the context/behavior relationship and link the lifecycle and
thread-safety guidance. Adapt the wording to Pekko's lazy context adapter and
existing restart semantics.
Result:
The guide describes the current implementation without implying that
ActorContext is safe to use from arbitrary threads.
Tests:
- Tests: Not run - docs only.
- Passed: `docs/paradox`.
- Passed: `+headerCheckAll`.
- Full `validatePullRequest` is left to remote CI.
References:
- Refs [akka/akka-core#32087](https://github.com/akka/akka-core/pull/32087).
- Upstream commit:
[44f60e0d4079957a38dc3a49ec3dee7835d3fcfe](https://github.com/akka/akka-core/commit/44f60e0d4079957a38dc3a49ec3dee7835d3fcfe).
- Source snapshot: Akka `v2.9.0`
(`bf20e967571574994ccb3cae411401f5a9021ab9`). Its
[license](https://github.com/akka/akka-core/blob/v2.9.0/LICENSE) names
2026-10-23 as the Change Date and Apache License 2.0 as the Change License.
`LICENSE` and `NOTICE` record the source, and original copyright notices are
retained. Headers were generated/checked with the project sbt tasks.
* Keep licensing metadata outside the migration change
Motivation:
Keep PR #3664 scoped to its code or documentation change.
Modification:
Restore the root LICENSE and NOTICE files to main.
Result:
The migration diff retains its source headers without repository-level
licensing edits.
Tests:
- git diff --check passed.
- Verified every other file is unchanged; prior focused validation still
applies.
References:
Refs #3664.
* Clarify setup behavior on supervised restart #3664
Motivation:
The Classic-to-Typed guide did not distinguish setup inside supervision
from setup outside it.
Modification:
Describe reinstalling the original supervised behavior, the setup boundary,
and stable ActorContext identity; link setup to its method anchors.
Result:
Readers can identify which initialization runs again on restart.
Tests:
Validation used a local integration checkout with current main and the
other review fixes.
- Runtime tests: Not run - docs only.
- docs/paradox, headerCreateAll, +headerCheckAll, and git diff --check:
passed.
- Verified the generated Scala and Java Behaviors.setup method anchors.
- Full validation is delegated to remote CI.
References:
Refs #3664.
---
docs/src/main/paradox/typed/from-classic.md | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/docs/src/main/paradox/typed/from-classic.md
b/docs/src/main/paradox/typed/from-classic.md
index f8c601af94..3c1d84c7e7 100644
--- a/docs/src/main/paradox/typed/from-classic.md
+++ b/docs/src/main/paradox/typed/from-classic.md
@@ -306,6 +306,27 @@ 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$)
{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)"}, 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, the original behavior passed to `Behaviors.supervise`
is reinstalled,
+including rerunning any `Behaviors.setup` inside it. 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.
+
## ActorContext.children
The `ActorContext` has methods @scala[`children` and
`child`]@java[`getChildren` and `getChild`]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
