Document RestAction and TransportAction threading model #135043

zhubotang-wq · 2025-09-18T22:11:59Z

This PR is based on discussion #100229 and #100162 .

Additional thread model description is added to the "transport layer" section.

github-actions · 2025-09-18T22:14:07Z

🔍 Preview links for changed docs

docs/internal/GeneralArchitectureGuide.md

github-actions · 2025-09-18T22:14:08Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

DaveCTurner

Looks good, thanks - I left a few small suggestions

DaveCTurner · 2025-09-19T08:42:28Z

docs/internal/GeneralArchitectureGuide.md

+> Upon entry into the "transport layer", [NodeClient] delegates the remaining processing to its [TaskManager] thread. The [TaskManager]
+> thread eventually returns control to the original [EventLoop] thread to write the response back to the Netty channel.


There isn't a separate TaskManager thread. Some transport actions do their work directly on the Netty event loop (ok if quick, bad if not) while others will dispatch the work onto a separate thread (pool).

In practice today because of #97916 transport actions invoked on the local node via the NodeClient will always start to run on the calling thread and may then have to dispatch to a separate pool manually.

Ack. Fixed the inaccuracy in previous description.

DaveCTurner · 2025-09-19T08:48:11Z

docs/internal/GeneralArchitectureGuide.md

+> Upon entry into the "transport layer", [NodeClient] delegates the remaining processing to its [TaskManager] thread. The [TaskManager]
+> thread eventually returns control to the original [EventLoop] thread to write the response back to the Netty channel.
+>
+> [TransportAction] can also be initiated through peer-to-peer communication between nodes. In such cases, the [InboundHandler]


Might also be worth mentioning about how the responses to these remote actions are threaded, using the executor defined in the response handler, see org.elasticsearch.transport.TransportResponseHandler#executor().

Also note that requests received remotely are always deserialized on the Netty event loop, but responses are deserialized after dispatching to the relevant executor. Outbound messages (both requests and responses) are serialized on the calling thread.

Ack. Added referenced to TransportResponseHandler and missing details on division of workload between IO and logic layer thread pools.

DaveCTurner · 2025-09-19T08:49:22Z

docs/internal/GeneralArchitectureGuide.md

 [TransportService]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportService.java
 [TransportSingleShardAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/single/shard/TransportSingleShardAction.java
 [Transport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/Transport.java
+[EventLoop]:https://github.com/netty/netty/blob/4.2/transport/src/main/java/io/netty/channel/EventLoop.java


Might (also/instead) be worth linking https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/networking-settings#modules-network-threading-model

DiannaHohensee · 2025-09-22T23:15:27Z

@zhubotang-wq not a big deal, but we try to avoid force-pushes if possible, because it can erase PR history.

DiannaHohensee

Left some style nits

docs/internal/GeneralArchitectureGuide.md

DiannaHohensee · 2025-09-22T23:29:39Z

docs/internal/GeneralArchitectureGuide.md

 > the `Transport*Action` class that handles it.
+>
+> A netty [EventLoop] thread handles the initial steps of a Rest*Action request lifecycle such as decoding, validation and routing.
+> Upon entry into the "transport layer", [NodeClient] delegates the decision of execution to individual [TransportAction]. Each action


Personally, I prefer not to make every mention of a class name a code link. Maybe use a link the first time a class is mentioned, if you think it's helpful to go look at some particular piece of code for additional information.

When I see a link, I think I should click on it, and then I'm disappointed when it's redundant and I have too many tabs open (the last part is my own problem I suppose 😌).

Instead of highlighting text with a hyperlink, you can use back ticks (``) to emphasize that it's a code name. I'd replace all your new text's [TransportAction] with TransportAction, since there's already a link reference above the new text. Same for [ActionType]

Agreed. Dialed down the use of code links more sparingly as to not distract readers.

docs/internal/GeneralArchitectureGuide.md

elasticsearchmachine · 2025-09-22T23:36:10Z

Pinging @elastic/es-distributed-coordination (Team:Distributed Coordination)

…l_architecture_threading_models

zhubotang-wq · 2025-09-29T20:25:36Z

@zhubotang-wq not a big deal, but we try to avoid force-pushes if possible, because it can erase PR history.

Ack. This meant is always preferable to do git merge rather than git rebase, which by definitions changes SHAs and requires accompanied either --force or --force-with-lease, i looked up both had the effects of wiping SHAs and comments along with them.

So we use git merge to preserve SHAs of commits during the code review phases, then during the PR merge back, we squash the commit history into a single commit, thus leave upstream with a clean history?

Co-authored-by: Dianna Hohensee <[email protected]>

DiannaHohensee · 2025-09-29T22:46:19Z

So we use git merge to preserve SHAs of commits during the code review phases, then during the PR merge back, we squash the commit history into a single commit, thus leave upstream with a clean history?

Yes, merge main into the work branch however many times you need, and then hitting the merge button on the PR will handle squashing / rebasing all the work before the commit. When you hit the merge button, you'll be asked for the final commit message.

zhubotang-wq · 2025-10-02T17:12:26Z

Could use an approval to get this doc update merged. Thanks!

DaveCTurner

LGTM thanks @zhubotang-wq

zhubotang-wq requested review from DaveCTurner and JeremyDahlgren September 18, 2025 22:11

elasticsearchmachine added needs:triage Requires assignment of a team area label v9.2.0 labels Sep 18, 2025

zhubotang-wq added documentation >non-issue labels Sep 18, 2025

zhubotang-wq mentioned this pull request Sep 19, 2025

Document an overview of action names and how they're used in the transport layer #100229

Closed

DaveCTurner reviewed Sep 19, 2025

View reviewed changes

zhubotang-wq added 6 commits September 21, 2025 17:49

Documentation : Rest and Transport Action Threading Model

e659a25

Documentation : Rest and Transport Action Threading Model

f1c7de0

Documentation : Transport action type strings.

f6c71ed

Documentation : Transport action type strings.

8310030

Documentation : Transport action type strings.

e0004ba

Documentation : Transport action type strings.

21f95b1

zhubotang-wq force-pushed the fix/document_general_architecture_threading_models branch from b9ecf19 to 21f95b1 Compare September 22, 2025 00:49

zhubotang-wq requested a review from DaveCTurner September 22, 2025 00:50

DiannaHohensee reviewed Sep 22, 2025

View reviewed changes

DiannaHohensee added Team:Distributed Coordination Meta label for Distributed Coordination team :Distributed Coordination/Network Http and internode communication implementations labels Sep 22, 2025

elasticsearchmachine removed the needs:triage Requires assignment of a team area label label Sep 22, 2025

Merge remote-tracking branch 'upstream/main' into fix/document_genera…

dd2ae71

…l_architecture_threading_models

zhubotang-wq and others added 4 commits September 29, 2025 13:51

Update docs/internal/GeneralArchitectureGuide.md

3c91c6f

Co-authored-by: Dianna Hohensee <[email protected]>

Update docs/internal/GeneralArchitectureGuide.md

31c25a1

Co-authored-by: Dianna Hohensee <[email protected]>

Update docs/internal/GeneralArchitectureGuide.md

b833f7e

Co-authored-by: Dianna Hohensee <[email protected]>

Update docs/internal/GeneralArchitectureGuide.md

1a45418

Co-authored-by: Dianna Hohensee <[email protected]>

Documentation : Rest and Transport Action Threading Model

660570c

zhubotang-wq requested a review from DiannaHohensee September 29, 2025 21:03

zhubotang-wq self-assigned this Sep 29, 2025

elasticsearchmachine added v9.3.0 and removed v9.2.0 labels Oct 2, 2025

DaveCTurner approved these changes Oct 2, 2025

View reviewed changes

zhubotang-wq merged commit fb5fe5e into elastic:main Oct 2, 2025
11 checks passed

		> Upon entry into the "transport layer", [NodeClient] delegates the remaining processing to its [TaskManager] thread. The [TaskManager]
		> thread eventually returns control to the original [EventLoop] thread to write the response back to the Netty channel.

Document Rest*Action and Transport*Action threading model #135043

Document Rest*Action and Transport*Action threading model #135043

Uh oh!

Conversation

zhubotang-wq commented Sep 18, 2025

Uh oh!

github-actions bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Sep 18, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

DaveCTurner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DiannaHohensee commented Sep 22, 2025

Uh oh!

DiannaHohensee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

elasticsearchmachine commented Sep 22, 2025

Uh oh!

zhubotang-wq commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DiannaHohensee commented Sep 29, 2025

Uh oh!

zhubotang-wq commented Oct 2, 2025

Uh oh!

DaveCTurner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Document RestAction and TransportAction threading model #135043

Document RestAction and TransportAction threading model #135043

github-actions bot commented Sep 18, 2025 •

edited

Loading

zhubotang-wq commented Sep 29, 2025 •

edited

Loading