microsoft / microsoft/microsoft-ui-reactor

Implement spec 031: Frame-aligned sampling (UseSample)

Open
#82 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design proposal
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.