Skip to content

feat(lib): targeted device refresh and stable correlation IDs for AllSmi#225

Merged
inureyes merged 1 commit into
mainfrom
feat/issue-211-targeted-device-refresh
May 24, 2026
Merged

feat(lib): targeted device refresh and stable correlation IDs for AllSmi#225
inureyes merged 1 commit into
mainfrom
feat/issue-211-targeted-device-refresh

Conversation

@inureyes

Copy link
Copy Markdown
Member

Summary

  • Adds targeted single-device refresh methods on AllSmi: get_gpu_by_uuid / refresh_gpu, get_cpu_by_index / refresh_cpu, get_memory_by_index / refresh_memory. Each refresh_* returns bool and leaves the original struct untouched on a miss.
  • Adds a 0-based stable index: u32 field on CpuInfo and MemoryInfo, populated by AllSmi while flattening readers, marked #[serde(default)] for snapshot and wire backward compatibility. CPU topology is static so the index is a stable correlation key across refreshes; MemoryInfo.index exists for API symmetry.
  • Adds a default trait method GpuReader::get_gpu_info_by_uuid (filters the full enumeration). The NVIDIA reader keeps the default for this PR per the issue's staged plan; an NVML device_by_uuid fast path is the logical follow-up.
  • Extends examples/library_usage.rs with a correlate-and-refresh loop covering GPU, CPU, and memory.

Why this approach

  • New methods live on AllSmi, not on the info structs. GpuInfo / CpuInfo / MemoryInfo are plain Serialize + Deserialize + Clone DTOs with no hardware handle; the readers already live inside AllSmi, so that is the correct owner of refresh logic. A self-updating update(&mut self) on the structs would have to embed a #[serde(skip)] reader handle that is None for any deserialized value.
  • GPUs key on uuid (already unique per device, hot-plug / MIG reconfiguration safe). CPUs and memory key on index because their topology is static and there was previously no per-entry identifier.
  • All new methods take &self; AllSmi: Send + Sync is preserved.
  • Additive surface — only consumers that build CpuInfo / MemoryInfo via exhaustive struct literals see a compile break. Internal call sites are updated; downstream consumers normally receive these structs from the library rather than building them.

Test plan

  • cargo fmt --check
  • cargo clippy --lib --tests -- -D warnings
  • cargo check --lib --tests
  • cargo test --doc client (14 doctests, including the new get_gpu_by_uuid and refresh_gpu examples)
  • cargo test --test library_api_test — 25 tests pass, including the 9 new tests for by-uuid hit/miss, in-place refresh idempotency, index stability across consecutive calls, and out-of-range index handling
  • cargo test --test snapshot_test — confirms index round-trips through JSON
  • cargo run --example library_usage — prints fresh utilization for one GPU by UUID, one CPU by index, and memory by index on a system with one NVIDIA GB10 GPU
  • View-cache and renderer unit tests still pass after the struct-literal updates

Follow-up

  • NVIDIA device_by_uuid fast-path override on NvidiaGpuReader::get_gpu_info_by_uuid (the static cache is currently keyed by index; a uuid resolution layer or a uuid-keyed static cache will make this a single-NVML-handle path instead of filtering the full enumeration).

Closes #211

…AllSmi

Re-fetching one device of interest previously meant calling get_*_info()
and re-enumerating the entire pool, and CpuInfo / MemoryInfo had no per
-entry identifier callers could use to map a refreshed batch back onto a
previously held one. This change closes both gaps:

* New AllSmi methods:
  - get_gpu_by_uuid(uuid)  /  refresh_gpu(&mut GpuInfo)
  - get_cpu_by_index(idx)  /  refresh_cpu(&mut CpuInfo)
  - get_memory_by_index(idx) / refresh_memory(&mut MemoryInfo)
  refresh_* returns bool: true on hit (struct overwritten), false on
  miss (struct left untouched).

* New default trait method GpuReader::get_gpu_info_by_uuid filters the
  full enumeration; readers that can address a device directly (NVML
  via nvmlDeviceGetHandleByUUID) MAY override for a faster path. The
  NVIDIA reader keeps the default filter for this PR per the issue's
  staged plan; an NVML by-uuid fast path is a logical follow-up.

* CpuInfo and MemoryInfo gain a stable, 0-based index: u32 populated by
  AllSmi::get_cpu_info / get_memory_info while flattening readers. The
  field is marked #[serde(default)] for snapshot and wire backward
  compatibility (same convention used elsewhere in types.rs).

* examples/library_usage.rs demonstrates correlate-and-refresh for GPU,
  CPU, and memory.

* tests/library_api_test.rs adds 9 tests covering by-uuid hit/miss,
  in-place refresh idempotency, index stability across consecutive
  calls, and out-of-range index handling.

All new methods are &self; AllSmi remains Send + Sync.

Closes #211
@inureyes inureyes added type:enhancement New feature or request priority:medium Medium priority issue status:review Under review status:done Completed and removed status:review Under review labels May 24, 2026
@inureyes inureyes merged commit 84cc94c into main May 24, 2026
4 checks passed
@inureyes inureyes deleted the feat/issue-211-targeted-device-refresh branch May 24, 2026 06:37
@inureyes inureyes self-assigned this May 24, 2026
inureyes added a commit that referenced this pull request May 24, 2026
Refs #221, #222, #224, #225, #226, #227.

Align config path active discovery with the implicit loader's first-existing-candidate semantics, correct record output help and resolver docs against the binary default, and make the swap-color regression test derive crossterm's current Red SGR sequence instead of hard-coding older encodings.
inureyes added a commit that referenced this pull request May 24, 2026
Refs #221, #222, #224, #225, #226, #227.

Align config path active discovery with the implicit loader's first-existing-candidate semantics, correct record output help and resolver docs against the binary default, and make the swap-color regression test derive crossterm's current Red SGR sequence instead of hard-coding older encodings.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority:medium Medium priority issue status:done Completed type:enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(lib): targeted device refresh and stable correlation IDs for the AllSmi API

1 participant