Reduce bounded observation backlog drain work - #64
Merged
Merged
Conversation
Replace EventMailbox and native pull-reader pending arrays with a private, lazily grown circular FIFO. Drop only the obsolete ordered prefix after resynchronization and release consumed envelope references immediately. The existing capacities, single scheduled drain, locks, generation/retirement checks and overflow/snapshot contracts are unchanged. Retain all existing tests; add seven tests covering 10,000-event wraps across non-power-of-two and maximum capacities, lazy bounded allocation, token release, partial reads, overflow recovery and repeated full-rate hub backlogs. Add an optional actual-mailbox release microbenchmark without a CI timing threshold. Linux validation: 89 package tests with warnings as errors and 6 real Swift/C/SDL/Cemu host CTests pass. The identical queue-only benchmark reduces 4096-envelope median drain time from about 42 ms to 0.94 ms on this runner; this is not controller latency or a platform guarantee. Native Apple-SDK and complete emulator qualification must run on the published head.
This was referenced Sep 17, 2026
jmonster
marked this pull request as ready for review
September 18, 2026 00:38
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
1 participant
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.
Bounded observation inbox optimization
Head:
5792b6d53ca2606e06d16b5c9252713c2136e610. Ready for review; all seven workflows for this unchanged head passed. Draft status has been removed. No PR merge or force-push was performed.EventMailboxshifted the remaining pending array for every callback and rescanned it for obsolete envelopes. Draining a full 4096-envelope inbox performed quadratic backlog work under a mutex also used by the producer. The native pull reader also shifted its backlog on partial reads.Use an internal specialized circular FIFO. Storage starts empty, grows geometrically to the unchanged configured bound, and immediately releases consumed envelopes/tokens. Ordered hub publication means obsolete envelopes after resynchronization form a prefix, rather than requiring a full scan.
Public Swift/C APIs, queue capacities, the single scheduled 32-event drain, queue/lock ownership, overflow/snapshot semantics and generation/retirement protections are unchanged. No dependency, public collection API, extra worker or telemetry is introduced.
Exact-head CI
These are the workflows that ran for the unchanged head, not a claim that the newer Linux workflow ran on this older branch. The completion audit found no review comments, submitted change-request reviews or unresolved review threads. The downloaded CI source archive matches the complete published tree and executable modes.
Validation
The original local run passed complete retained regressions and 89 debug / 89 release package tests with warnings as errors. The seven new tests cover lazy bounded growth, non-power-of-two storage, 10,000 events at six capacities, wrapped partial reads, obsolete-prefix cleanup, immediate lifetime/snapshot-token release, overflow recovery and 12,285 ordered input deliveries. No existing assertion was removed or weakened.
Additional completion validation combined current main
a187693b8ced4328758c4e242a4eb203d26608a2with #63, #64, corrected #65 (4fef3dc) and corrected #68 (9757016). The local combined tree isfa80b2e7eab3dfadc3196e73c01c9d59079b1422; it was not published or merged.lib/lib64relocation, two real C++ consumers and missing-library negative controls: PASS.Recorded performance evidence
tests/observation-buffer/benchmark.shmeasures nine release-mode resume-to-last-handler drain times after queuing the configured capacity and verifies delivery/completion. It is not a CI timing gate.A later original execution recorded 0.098 ms and 0.936 ms. These are queue-only measurements from the original Linux runner, not measured Bluetooth, gameplay or macOS latency. CPU load and scheduling affect results. No platform-wide speed guarantee, physical measurement, controller-capability change or calibration claim is introduced.