Conversation
added 9 commits
February 16, 2026 23:24
…dation pipeline, clarifying cancellation logic and ensuring correctness in rebalance necessity determination.
…lidation stages, enhancing decision-making clarity and execution control, solving intent trashing issue
…ment, encapsulating cancellation and execution logic within PendingRebalance, and enhancing diagnostics for rebalance events.
…on, enhancing architectural and behavioral descriptions of rebalance intent and cancellation mechanisms.
…r improved clarity and consistency across related classes.
…r improved readability
…stages and execution authority, emphasizing work avoidance and smart eventual consistency principles.
…eDecisionEngine, IntentController, and RebalanceScheduler files
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates SlidingWindowCache to a decision-driven rebalance model where rebalance necessity is determined by a multi-stage validation pipeline, and cancellation becomes a coordination tool rather than an automatic response to every new request.
Changes:
- Move rebalance necessity logic into a multi-stage
RebalanceDecisionEngine(current NoRebalanceRange, pending NoRebalanceRange anti-thrashing, desired==current short-circuit) and schedule execution only when validated. - Refactor intent/scheduling/execution boundaries (scheduler owns CTS/task; executor becomes purely mechanical and consumes pre-validated decision inputs).
- Update diagnostics surface area and adjust invariants/tests/docs to reflect non-deterministic cancellation semantics and stage-specific skip reasons.
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/SlidingWindowCache.Unit.Tests/Infrastructure/Instrumentation/NoOpDiagnosticsTests.cs | Updates no-op diagnostics test to cover new stage-specific skip counters. |
| tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs | Reworks invariants to validate lifecycle integrity/stability instead of deterministic cancellation counts; adds stage-specific tests. |
| tests/SlidingWindowCache.Invariants.Tests/TestInfrastructure/TestHelpers.cs | Adds assertions for stage-specific policy skips, scheduled rebalance counter, and pipeline integrity helper. |
| tests/SlidingWindowCache.Invariants.Tests/README.md | Updates invariant suite documentation to the new decision-driven/cancellation semantics model. |
| tests/SlidingWindowCache.Integration.Tests/RebalanceExceptionHandlingTests.cs | Updates sample diagnostics implementation and formatting; adds stub for RebalanceScheduled. |
| src/SlidingWindowCache/Public/WindowCache.cs | Wires new planners/decision engine and updates executor construction for the new responsibility split. |
| src/SlidingWindowCache/Infrastructure/Instrumentation/NoOpDiagnostics.cs | Adds no-op implementations for new diagnostics events (stage-specific skips + scheduled). |
| src/SlidingWindowCache/Infrastructure/Instrumentation/ICacheDiagnostics.cs | Replaces generic NoRebalanceRange skip with stage-specific skip events and adds RebalanceScheduled. |
| src/SlidingWindowCache/Infrastructure/Instrumentation/EventCounterCacheDiagnostics.cs | Adds counters for stage-specific skips and scheduled rebalance; updates reset logic. |
| src/SlidingWindowCache/Core/UserPath/UserRequestHandler.cs | Removes unconditional cancellation at request start; aligns user path with new model. |
| src/SlidingWindowCache/Core/Rebalance/Intent/ThresholdRebalancePolicy.cs | Removes old policy that mixed planning + decision responsibilities. |
| src/SlidingWindowCache/Core/Rebalance/Intent/RebalanceScheduler.cs | Refactors scheduler to accept pre-validated decisions and to return a pending-rebalance snapshot. |
| src/SlidingWindowCache/Core/Rebalance/Intent/PendingRebalance.cs | Introduces pending-rebalance snapshot that carries desired ranges + CTS/task references for anti-thrashing and coordination. |
| src/SlidingWindowCache/Core/Rebalance/Intent/IntentController.cs | Moves intent record, adds pending snapshot management, decision evaluation, stage reason recording, and observe-and-stabilize idle wait. |
| src/SlidingWindowCache/Core/Rebalance/Intent/Intent.cs | Removes old intent type file (intent record moved). |
| src/SlidingWindowCache/Core/Rebalance/Execution/RebalanceExecutor.cs | Makes executor purely mechanical; takes desired no-rebalance range from decision engine and writes it directly to state. |
| src/SlidingWindowCache/Core/Rebalance/Decision/ThresholdRebalancePolicy.cs | Adds stateless containment-based decision policy. |
| src/SlidingWindowCache/Core/Rebalance/Decision/RebalanceDecisionEngine.cs | Implements multi-stage validation pipeline including pending anti-thrashing check. |
| src/SlidingWindowCache/Core/Rebalance/Decision/RebalanceDecision.cs | Extends decision result to include reason and desired no-rebalance range. |
| src/SlidingWindowCache/Core/Planning/NoRebalanceRangePlanner.cs | Adds explicit planner for computing no-rebalance range from desired cache range + options. |
| docs/scenario-model.md | Updates decision path scenarios and adds Stage 2 anti-thrashing documentation. |
| docs/invariants.md | Reclassifies/rewords invariants around cancellation and decision authority; documents multi-stage pipeline. |
| docs/concurrency-model.md | Updates concurrency model to emphasize validation-driven cancellation and synchronous decision evaluation. |
| docs/component-map.md | Expands component map with decision pipeline model and roles. |
| docs/cache-state-machine.md | Updates state transitions to “MAY cancel” and validation-driven scheduling/cancellation. |
| docs/actors-to-components-mapping.md | Updates actor/component mapping to reflect synchronous decision evaluation and new scheduling boundaries. |
| docs/actors-and-responsibilities.md | Updates responsibilities to reflect decision authority and cancellation semantics. |
| README.md | Updates top-level project description and adds decision-driven rebalance execution section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…andlingTests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…havior and intent publication handling
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ion and clarity, moving decision-related classes to the Intent namespace.
…or improved performance and clarity, replacing Task.Run with Task.Delay and ContinueWith pattern.
… streamline handling of direct await scenarios
…on with ConfigureAwait(false) for improved performance and clarity in background execution
…to streamline IntentController functionality
…ispose of cancellation token source on cancel
…to improve performance and avoid deadlocks
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 29 out of 29 changed files in this pull request and generated 7 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…aphoreSlim to prevent concurrent cache writes, ensuring thread safety and improved cancellation handling.
…Tests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…Tests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
blaze6950
pushed a commit
that referenced
this pull request
Feb 21, 2026
BREAKING DOCS CHANGE: Decision evaluation runs in background intent processing loop, not user thread This corrects systematic documentation inaccuracies that emerged after architectural refactoring in commit 3e8ed0f (Feb 17, 2026). The decision evaluation pipeline (RebalanceDecisionEngine, ProportionalRangePlanner, NoRebalanceRangePlanner, ThresholdRebalancePolicy) executes in a background thread within the intent processing loop (IntentController.ProcessIntentsAsync), NOT in the user thread. User thread boundary ends at PublishIntent() return, which performs only atomic operations (Interlocked.Exchange + semaphore signal) and returns immediately (fire-and-forget pattern). THREADING MODEL CLARIFICATION: - User Thread: GetDataAsync → UserRequestHandler → PublishIntent [RETURNS HERE] - Background Thread #1: ProcessIntentsAsync → DecisionEngine → Planners - Background Thread #2: ProcessExecutionRequestsAsync → Executor → Cache Mutation Files updated: - XML docs: RebalanceDecisionEngine.cs, ProportionalRangePlanner.cs, NoRebalanceRangePlanner.cs, ThresholdRebalancePolicy.cs, IntentController.cs - Markdown docs: component-map.md, actors-and-responsibilities.md, actors-to-components-mapping.md, README.md - Added: Comprehensive threading flow diagram in component-map.md This is a documentation-only change with no functional code modifications.
blaze6950
added a commit
that referenced
this pull request
Feb 23, 2026
…cy model (#3) * fix: the async idle state detection logic was reconsidered; some optimizations and other fixes for stability was applied; test: tests have been adjusted a bit * docs: improve documentation for last execution request tracking in RebalanceExecutionController * refactor: refactor test diagnostics initialization to use readonly fields and constructor assignment for EventCounterCacheDiagnostics * todo: add TODO comments outlining planned improvements and refactoring for concurrency, diagnostics, and documentation * docs: agent guidelines for SlidingWindowCache have been added with architecture, build, test, and code style instructions * docs: exception testing examples to AGENTS.md for improved clarity on error handling hasve been added * feat: implement disposal pattern for WindowCache to ensure resource management and graceful shutdown; docs: update README with resource management and disposal behavior details; test: add unit tests for WindowCache disposal behavior and idempotency * docs: correct threading model documentation across codebase BREAKING DOCS CHANGE: Decision evaluation runs in background intent processing loop, not user thread This corrects systematic documentation inaccuracies that emerged after architectural refactoring in commit 3e8ed0f (Feb 17, 2026). The decision evaluation pipeline (RebalanceDecisionEngine, ProportionalRangePlanner, NoRebalanceRangePlanner, ThresholdRebalancePolicy) executes in a background thread within the intent processing loop (IntentController.ProcessIntentsAsync), NOT in the user thread. User thread boundary ends at PublishIntent() return, which performs only atomic operations (Interlocked.Exchange + semaphore signal) and returns immediately (fire-and-forget pattern). THREADING MODEL CLARIFICATION: - User Thread: GetDataAsync → UserRequestHandler → PublishIntent [RETURNS HERE] - Background Thread #1: ProcessIntentsAsync → DecisionEngine → Planners - Background Thread #2: ProcessExecutionRequestsAsync → Executor → Cache Mutation Files updated: - XML docs: RebalanceDecisionEngine.cs, ProportionalRangePlanner.cs, NoRebalanceRangePlanner.cs, ThresholdRebalancePolicy.cs, IntentController.cs - Markdown docs: component-map.md, actors-and-responsibilities.md, actors-to-components-mapping.md, README.md - Added: Comprehensive threading flow diagram in component-map.md This is a documentation-only change with no functional code modifications. * refactor: code clarity by removing redundant whitespace and enhancing documentation comments has been imporved * refactor: execution controller interface has been introduced for rebalance execution strategies; feat: rebalance execution queue capacity configuration has been added to support bounded and unbounded strategies; docs: execution strategy details have been documented in README and concurrency model; test: integration tests for execution strategy selection have been implemented; fix: cancellation handling in execution requests has been improved * refactor(concurrency model): improve clarity and detail of concurrency model documentation; enhance AsyncActivityCounter description and usage semantics * chore: not used DTO has been removed * docs: update invariants documentation to include activity tracking and idle detection invariants; docs: enhance AsyncActivityCounter documentation with critical invariants and call site details * feat(docs): add diagnostics documentation for cache behavior events; refactor(docs): improve clarity in concurrency model and decision pipeline descriptions; fix(docs): correct inaccuracies in rebalance execution and skip conditions; style(docs): update formatting and terminology for consistency across documentation * docs: update architectural documentation for clarity and accuracy; refactor: rename concurrency model document to architecture model; docs: enhance documentation with additional references and explanations * feat(tests): enhance test coverage with new gap tests and parameterized strategies; refactor test helpers to support execution strategy variations * docs: README and WasmCompilationValidator have been updated to include strategy coverage validation details * docs: glossary document has been added to define technical terms used in the project * fix: NoRebalanceRange planner logic was fixed taking into account that 1 or more of threshold sum means no rebalance range at all (not equal to the current cache range); also, the validation of threshold was extended in options; docs: update documentation for NoRebalanceRange and WindowCacheOptions validation; clarify threshold sum constraint and its enforcement * feat(benchmark): add execution strategy benchmarks for unbounded and bounded queue performance under burst loads; feat(data source): implement SlowDataSource to simulate I/O latency for testing; fix(README): update documentation to include execution strategy selection and benchmark results * refactor: data generation logic for range has been improved to respect boundary inclusivity; feat: cancellation token has been added to execution request methods for graceful shutdown during disposal * refactor(concurrency): enhance async disposal coordination using TaskCompletionSource for concurrent safety --------- Co-authored-by: Mykyta Zotov <mykyta.zotov@ihsmarkit.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Decision-Driven Rebalance Model & Cancellation Semantics
Problem
Previous implementation incorrectly coupled user requests, rebalance scheduling, and cancellation behavior, treating cancellation as a decision mechanism rather than a coordination tool. This caused:
Core Issue: System followed a reactive model where every request implied rebalance necessity.
Architectural Shift
Before:
New Request → Cancel Previous Work → Schedule New WorkAfter:
New Request → Analytical Validation → Scheduling Decision → (Optional Cancellation)Key Separation
Multi-Stage Decision Pipeline
Rebalance now validated through three stages:
Stage 1 — Current Cache Validation
RequestedRange ⊆ NoRebalanceRange(CurrentCacheRange)Stage 2 — Pending Desired Cache Validation (anti-thrashing)
RequestedRange ⊆ NoRebalanceRange(PendingDesiredCacheRange)Stage 3 — Desired vs Current Equality
DesiredCacheRange == CurrentCacheRangeRebalance executes ONLY if ALL stages confirm necessity.
Corrected Semantics
Cancellation
Before: New request → Guaranteed cancellation
After: Cancellation MAY occur, is NOT guaranteed
Cancellation now means:
Key Insights
Invariant Changes
Reclassified
Revised
F.35 — Cancellation Safety (not Guarantee)
G.46 — Conditional Background Cancellation
Test Changes
Removed:
Now Validate:
Results
System now operates as a stable, decision-driven sliding window cache: