Chenhao Zuo

This commit **refactors** the build configuration for the **`starlark-rust/benchmark_memory`** module by moving the `libc` crate dependency into a Linux-specific `select` block within the `buck_rust_binary` rule. This **maintenance** change addresses an **unused dependency warning** from `arc rust-check` on non-Linux platforms, as `libc` is only utilized for `malloc_trim` under `#[cfg(target_os = "linux")]`. By making the dependency conditional, it improves build hygiene and ensures that `libc` is only linked when functionally required, preventing unnecessary dependencies on other operating systems.

This commit performs **maintenance refactoring** to eliminate **dead code warnings** within the **Buck2 build system** by explicitly marking Linux-specific code and dependencies. It gates `InvocationRecorder::start_time()` in **`buck2_client_ctx`** with `#[cfg(target_os = "linux")]` and adds `#[cfg_attr(not(target_os = "linux"), allow(dead_code))]` to `ValidatedCommand::network_access` in **`buck2_forkserver`**, as these elements are only utilized in Linux-only code paths. Furthermore, the `nix` dependency in `buck2_forkserver/BUCK` is now conditionally included only for Linux builds. This change improves code hygiene and reduces unnecessary compilation and dependencies on non-Linux platforms.

This commit **fixes a naming issue** within the **configuration system** where **exec dependency configurations** were incorrectly labeled as `cfg:<empty>` after modifier application. The `cfg_name` function in `prelude/cfg/modifier/name.bzl` is updated to use the **exec platform label** as the configuration name, prepended with `exec_cfg:`, providing a clear and consistent identifier. This **maintenance fix** ensures that exec dependency configurations are properly named and identifiable, improving debugging and build graph clarity. A new test case has been added to verify this correct naming behavior.

This commit **removes** a "flag cleaned" configuration previously associated with the **`exec` modifier**. This is a **maintenance** and **cleanup** task, as the configuration has become redundant. A recent update or "bump" to the codebase has already incorporated the necessary changes, making this specific configuration obsolete. The removal simplifies the configuration logic for the `exec` modifier, streamlining the codebase by eliminating unnecessary settings.

This commit introduces a **new capability** to the **Starlark interpreter's heap management** by making `FrozenHeapName` hashable, which is crucial for serialization and deserialization processes. It achieves this by replacing the generic `Any` type with a new object-safe `UserHeapName` trait for user-defined heap names within `FrozenHeapName`. The `UserHeapName` trait provides a `dyn_hash` method, effectively wrapping the non-object-safe `Hash` trait, with a blanket implementation ensuring compatibility for existing types. This **refactoring** primarily impacts the `starlark::values::layout::heap` module, allowing `FrozenHeapName` to now implement `Hash`, `PartialEq`, and `Eq`, and directly benefits components like `StarlarkEvalKind` by providing a stable hashing mechanism for its internal state.

This commit **refactors** the **Starlark heap management** within the `starlark` crate by feature-gating the unnamed `freeze()` and `into_ref()` APIs behind the `pagable` feature flag. This **maintenance** change enforces that all frozen heaps in Buck2 must be created with a name, completing a migration to **named heaps**. When `pagable` is enabled, the `freeze` function in `starlark-rust/starlark/src/environment/modules.rs` and `into_ref` in `starlark-rust/starlark/src/values/layout/heap/heap_type.rs` are hidden, requiring the use of their named counterparts. Documentation and examples in `starlark-rust/starlark/src/lib.rs` and `starlark-rust/starlark/src/values/owned.rs` are updated to reflect this new requirement. External consumers of the `starlark` crate not using the `pagable` feature are **unaffected**, as the original APIs remain available to them.

This commit **refactors** the **Starlark compiler's def-inlining optimization** by assigning a specific name to the `local_as_value` static cache heap. The `local_as_value` function is updated to use `singleton_heap_name!()`, and the `FrozenHeapName` enum is extended with a `Singleton` variant to categorize such heaps. This **maintenance** change improves the clarity and manageability of singleton heaps within the compiler's **heap management system**, specifically for the `local_as_value` cache, without altering its functional behavior.

This commit **refactors** the internal testing infrastructure by migrating various test callers in both the **`starlark`** and **`buck2`** crates to use `freeze_named` and `into_ref_named` with dedicated, private testing sentinels. Specifically, `StarlarkTestHeapName` is introduced for `starlark`'s internal tests, and `Buck2TestHeapName` for `buck2`'s shared test crates, defined in `buck2_interpreter::testing`. This **improves the encapsulation of test-only concerns**, preventing test-specific heap naming from polluting the public `FrozenHeapName` API while still allowing distinct test sentinel types for different parts of the codebase. The change primarily affects **test helper functions and test cases** across multiple modules, enhancing the maintainability and clarity of the testing setup.

This commit **enhances the observability** of the **Starlark CLI tool** by assigning meaningful names to its memory heaps. It configures the heaps within `eval.rs` and `bazel.rs` to utilize `FrozenHeapName::User`, incorporating the file path currently being evaluated. This **maintenance improvement** provides clearer identification of memory allocations during Starlark script execution, significantly aiding in profiling and debugging efforts for the CLI tool's operations.

This commit **refactors** the **Starlark environment methods** by conditionally hiding the `MethodsStatic::methods()` function behind a `#[cfg(not(starlark_require_heap_names))]` attribute. This **maintenance** change, coupled with an update to the `starlark-rust/starlark/BUCK` file, ensures that the `starlark_require_heap_names` flag is set when the `pagable` feature is enabled in Buck builds. The primary goal is to **prevent the introduction of new unnamed methods heaps** in specific build environments by making the unnamed API a compile-time error, thereby enforcing a stricter naming convention. While the unnamed API remains available for OSS, non-Buck, and Cargo builds, this **build system enforcement** ensures adherence to architectural constraints in environments where the `pagable` feature is active.

This commit **refactors** the **Buck2 interpreter's `host_info()` built-in function** by assigning a specific name to its singleton heap. Previously unnamed, this heap now explicitly identifies the memory region holding the frozen OS, architecture, and Xcode version struct returned by `host_info()`. This **maintenance improvement** enhances internal clarity and consistency in the **interpreter's memory management** for built-in values. Specifically, it affects how the **host information struct** is managed as a singleton, providing better internal identification without altering its functional behavior or user-facing output.

This commit **refactors** the **Starlark environment's module freezing mechanism** by explicitly naming the heap used by the `FrozenModule::from_globals` function. Specifically, it updates the `starlark-rust/starlark/src/environment/modules.rs` file to assign `FrozenHeapName::Singleton(singleton_heap_name!())` to the heap associated with `from_globals`. This **maintenance** change improves internal consistency and clarity for heap identification during module freezing. The **downstream impact is minimal**, as `FrozenModule::from_globals` is currently only called in a single test within Buck2.

This commit **enhances the `benchmark_memory` tool** by assigning a specific name to its heap. It modifies the `main` function within `starlark-rust/benchmark_memory/src/main.rs` to utilize `singleton_heap_name!()`, ensuring the tool's memory allocation is clearly identified. This is a **maintenance improvement** for the standalone memory benchmarking utility, which operates with a single freeze per process. By explicitly naming the heap, it improves the **clarity and traceability** of memory usage for this specific benchmarking component.

This commit introduces a **new capability** to the **Starlark runtime's heap management** by defining the `SingletonFrozenHeapName` type and its associated `singleton_heap_name!()` macro. The `SingletonFrozenHeapName` acts as a **type-safe, unique, and cross-process stable identifier** for singleton heaps, derived from their source code location (`file:line:col`). This enhancement improves the robustness and clarity of identifying specific heap objects within the `starlark` crate's `values` module. The new type is exported for public use, facilitating more reliable management and referencing of these critical heap elements.

This commit **refactors** the **Starlark interpreter's global heap management** within Buck2 by introducing explicit naming for all global heaps. It extends the `FrozenHeapName` enum with a `Global` variant and modifies `GlobalsBuilder` and `GlobalsStatic` in the `starlark-rust` library to support assigning these names. Specifically, it ensures that inner cache heaps created by `#[starlark_module]`, single function heaps from `#[internal_provider]`, and the main `GlobalInterpreterState` composition heap are all given descriptive names. This **enhancement** improves **observability and debugging** by allowing better identification and tracking of memory usage for different Starlark components within Buck2.

This commit **adds comprehensive documentation** for the **Persistent Workers** feature, specifically targeting **Rule Authors**. It introduces a new page, `persistent_workers.md`, detailing worker identity, how to define and use workers via `WorkerInfo` and `WorkerRunInfo`, and the recommended pattern of sharing workers through toolchains. The documentation also covers supported protocols like local gRPC and remote Bazel, along with various configuration options. This **new documentation** significantly improves the clarity and usability of this advanced build system capability for rule authors. The website's sidebar configuration is updated to include this valuable new resource.

This commit **adds new documentation** to `docs/rule_authors/test_execution.md`, providing a comprehensive explanation of how **Buck2 caches test listings**. It details the operational specifics of the caching mechanism, including local upload behavior, methods for opting out, and relevant configuration options. This **documentation update** clarifies an important aspect of **test execution** for **rule authors**, enabling them to better understand and manage their build processes. The change improves the overall clarity and usability of the **Buck2 documentation**.

This commit performs a **system-wide refactoring** by **migrating all remaining call sites** from `RES.methods(f)` to `RES.methods_named::<Self::Canonical>(f)`. This change ensures that every `Methods` heap within the Starlark runtime now has a name derived from its associated `StarlarkValue`'s `Canonical` type. The **mechanical migration** affects numerous modules across `starlark-rust`, various `buck2 app crates` (e.g., `buck2_action_impl`, `buck2_build_api`, `buck2_bxl`), and the `provider derive macro`. This is an **internal change** with **no behavioral impact**, primarily improving internal consistency and potentially aiding future introspection or debugging of Starlark method resolution.

This commit performs a significant **refactoring** of the **Starlark runtime's method registration system**, specifically for core value types like dictionaries, lists, sets, and strings. It **removes standalone helper functions** such as `dict_methods()`, `list_methods()`, `set_methods()`, and `str_methods()`, inlining their method registration logic directly into each type's respective `get_methods()` implementation. This change simplifies the internal architecture of the **`starlark-rust/starlark/src/values/types` module**, making the method setup more cohesive and directly associated with the types themselves. The **`known_methods.rs` module** is updated to reflect this, now calling the type-specific `get_methods()` functions directly, resulting in improved code organization and reduced indirection without any functional changes to the Starlark language's behavior.

This commit introduces a **new capability** for uniquely naming **Starlark method heaps**, essential for pagable serialization and deduplication across serialization boundaries. It defines `MethodFrozenHeapName` and extends `FrozenHeapName` with a `Method` variant to identify these heaps. The `MethodsStatic::methods_for_type::<T>()` API is added to derive deterministic heap names from type information, and `MethodsStatic::populate()` now accepts a `name` parameter, which the `#[starlark_module]` macro automatically generates. This **enhancement** ensures that method heaps can be consistently identified and deduplicated, improving the efficiency and correctness of the Starlark runtime's persistence layer, and includes a minor **bug fix** in `buck2_sketches.rs`.