From cadfc6dbcb1fa7d2daca2473117207b88518db86 Mon Sep 17 00:00:00 2001 From: Googler Date: Sun, 17 Dec 2023 21:31:43 -0800 Subject: [PATCH] Briefly document about StateMachines and virtual threads in CODEBASE.md. StateMachines are instrumental to optimize the analysis phase for computing CT and Aspect values, so I think it warrants a place in CODEBASE.md where restarts are mentioned. RELNOTES: PiperOrigin-RevId: 591779728 Change-Id: Ia359da0cbd2c3179120860f7dbeb00550ae7f066 --- site/en/contribute/codebase.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/site/en/contribute/codebase.md b/site/en/contribute/codebase.md index 9bb908ad1ab999..a06989e7314ad2 100644 --- a/site/en/contribute/codebase.md +++ b/site/en/contribute/codebase.md @@ -395,11 +395,24 @@ around this issue by: usage. 3. Storing state between restarts, either using `SkyFunction.Environment.getState()`, or keeping an ad hoc static cache - "behind the back of Skyframe". - -Fundamentally, we need these types of workarounds because we routinely have -hundreds of thousands of in-flight Skyframe nodes, and Java doesn't support -lightweight threads. + "behind the back of Skyframe". With complex SkyFunctions, state management + between restarts can get tricky, so + [`StateMachine`s](/contribute/statemachine-guide) were introduced for a + structured approach to logical concurrency, including hooks to suspend and + resume hierarchical computations within a `SkyFunction`. Example: + [`DependencyResolver#computeDependencies`][statemachine_example] + uses a `StateMachine` with `getState()` to compute the potentially huge set + of direct dependencies of a configured target, which otherwise can result in + expensive restarts. + +[statemachine_example]: https://developers.google.com/devsite/reference/markdown/links#reference_links + +Fundamentally, Bazel need these types of workarounds because hundreds of +thousands of in-flight Skyframe nodes is common, and Java's support of +lightweight threads [does not outperform][virtual_threads] the +`StateMachine` implementation as of 2023. + +[virtual_threads]: /contribute/statemachine-guide#epilogue_eventually_removing_callbacks ## Starlark {:#starlark}