feat(thread_aware): add ProcessorCount::AtMost for capped processor count

[sandersaares]

What

Adds a new ProcessorCount::AtMost(NonZero<usize>) variant that requests an upper bound on the number of processors, clamping down to every available processor when the hardware offers fewer than requested.

Also renames the existing ProcessorCount::Manual variant to ProcessorCount::Exactly. Reviewers noted that Manual was easy to confuse with the newly added AtMost variant; Exactly makes the "require exactly this many processors" semantics unambiguous versus AtMost's upper-bound behavior.

Why

Exactly(N) requires exactly N processors and panics via ThreadRegistry::new/with_hardware when the machine has fewer. There was no way to express "use up to N, but accept fewer if that is all the machine has". AtMost fills that gap for callers that want to cap resource usage while still running unchanged on smaller machines. For example, AtMost(32) uses 32 processors on a machine with at least 32, and all of them on a machine with fewer.

How

ThreadRegistry::with_hardware clamps the ceiling to hardware.processors().len() (the quota-enforced available count) and calls the existing ProcessorSetBuilder::take(). No change to many_cpus is required. Unlike Exactly, AtMost never fails when the machine is smaller than the ceiling.

Testing

Added three deterministic tests using the many_cpus::fake hardware harness: request below available, request equal to available, and request exceeding available (clamps to all, no panic). cargo test -p thread_aware, just clippy, just format-check, and the docs.rs doc build all pass.

[Copilot]

Pull request overview

Adds a new ProcessorCount::AtMost(NonZero<usize>) option to thread_aware’s ThreadRegistry processor-selection policy so callers can cap processor usage without failing on smaller machines.

Changes:

• Introduces ProcessorCount::AtMost and documents intended behavior vs Manual/All.
• Updates ThreadRegistry::with_hardware to clamp requested processors to the hardware’s available processor count.
• Adds deterministic fake-hardware tests covering below/equal/exceeding available processor counts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

⚠️ Breaking Changes Detected

--- failure enum_marked_non_exhaustive: enum marked #[non_exhaustive] ---

Description:
A public enum has been marked #[non_exhaustive]. Pattern-matching on it outside of its crate must now include a wildcard pattern like `_`, or it will fail to compile.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#attr-adding-non-exhaustive
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/enum_marked_non_exhaustive.ron

Failed in:
  enum ProcessorCount in /home/runner/work/oxidizer/oxidizer/crates/thread_aware/src/registry.rs:24

--- failure enum_variant_missing: pub enum variant removed or renamed ---

Description:
A publicly-visible enum has at least one variant that is no longer available under its prior name. It may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/enum_variant_missing.ron

Failed in:
  variant ProcessorCount::Manual, previously in file /home/runner/work/oxidizer/oxidizer/target/semver-checks/git-origin_main/b688c5ea86cea70c894be0740ad66ba080518dfe/crates/thread_aware/src/registry.rs:29

If the breaking changes are intentional then everything is fine - this message is merely informative.

Remember to apply a version number bump with the correct severity when publishing a version with breaking changes (1.x.x -> 2.x.x or 0.1.x -> 0.2.x).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (917aa13) to head (2b4335b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #541   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         355      355           
  Lines       26963    26968    +5     
=======================================
+ Hits        26963    26968    +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sandersaares]

Intentional. Adding ProcessorCount::AtMost to this exhaustive enum is a deliberate breaking change; the release should be cut as thread_aware@breaking (0.7.5 -> 0.8.0 under the repo's 0.x SemVer rules).

[Copilot]

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

[sandersaares]

AtMost being a breaking change is annoying. I campaign for all y'all's upvotes at https://o365exchange.visualstudio.com/O365%20Core/_workitems/edit/7546921/

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.