microsoft / microsoft/microsoft-ui-reactor
Implement spec 031: Frame-aligned sampling (UseSample)
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 646
- Forks
- 54
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 84
Description
Tracks implementation of [spec 031 — Frame-aligned sampling design](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/031-frame-aligned-sampling-design.md).
Spec authored in #81 (view the spec on that PR until it merges).
## Summary
Add `UseSample(IObservable, int framesPer, T initial)` so components can consume high-frequency data sources (e.g., 50 Hz telemetry) but re-render at most every N display frames. Most-recent-value-wins; producer-thread drop coalesces background-thread events before the dispatcher hop.
## v1 scope
- [ ] `UseSample(IObservable, int framesPer, T initial)` primitive
- [ ] `UseSampled(Func, INotifyPropertyChanged, int framesPer)` INPC sibling
- [ ] `IFrameClock` abstraction + production implementation in `ReactorHost`
- [ ] `VirtualFrameClock` in selftest harness + fixtures covering the test matrix in the spec
- [ ] `StressPerf.Reactor --sample-frames N` CLI flag + baseline comparison
- [ ] User-facing doc page (`docs/guide/` or `docs/reference/`)
## Out of scope (deferred)
- `UseSampledCollection` for `INotifyCollectionChanged` (incremental coalescing)
- `` subtree render boundary
- Display-refresh-rate discovery / `UseSampleHz` convenience overload
- Devtools commit-rate / drop-rate counters
## Open issues to resolve before / during implementation
See the [Open issues](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/031-frame-aligned-sampling-design.md#open-issues) section of the spec. Highlights:
1. Display refresh rate on 120/240 Hz displays (`framesPer` is honest but changes meaning)
2. Boxing for value-typed `T` in the pending slot
3. Equality-based commit skip (likely no)
4. Multiple consumers of one source at different rates (independent subscriptions vs. shared publisher)
5. `UseSampled` getter timing — call on notify or on commit
6. Whether `IFrameClock.OnFrameAdvanced` is a general host primitive
7. Commit dispatcher priority (Low vs. Normal, interaction with existing render-loop re-enqueue)
8. Selftest harness clock wiring
9. Devtools metric surface (deferred)
10. Naming bikeshed — `UseSample` / `UseSampled` / `UseSampleProperty`
## Acceptance
- All spec test-matrix fixtures pass under the virtual frame clock.
- `StressPerf.Reactor --sample-frames 3` shows reconcile-phase time per second dropping by ≥50% vs. baseline at equivalent producer rate, no visible correctness regressions.
- Open issues resolved (or explicitly deferred with rationale) before merging the implementation PR.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/specs/031-frame-aligned-sampling-design.md, especially its test matrix and Open issues section. Then inspect the ReactorHost frame-clock entry point, the selftest harness and VirtualFrameClock, and the StressPerf.Reactor CLI entry point; done means the fixtures pass, the specified performance comparison succeeds, and unresolved design questions are resolved or explicitly deferred.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- desktop, frontend, performance, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100