Repository navigation
docs: lead with who this is for, and put the landscape back on the site - #30
Merged
Merged
Conversation
The README opened with mechanism — stamped ring buffers, per-slot validation, T: Pod — and buried the audience mid-paragraph. The thing that actually distinguishes the crate, per-consumer delivery contracts, sat a hundred and fifty lines down under a heading nobody would search for. Both now come first: who this is for, what you get that you would otherwise build yourself, and an honest note about when to use something else. The seqlock mechanics follow, for readers who got that far because they care. The site had no landscape at all. Removing head-to-head scoring was right; removing every trace of context went too far, and left a visitor unable to answer why this instead of what they already use. It now carries an approach-level table — locked queue, lock-free queue, shared sequence barrier, stamped slots — with what each costs and which problem it actually solves. Categories rather than crates, because the useful information is the trade, not a ranking. No head-to-head benchmark scoring anywhere, which remains the line. The one named alternative on the site is the pointer telling readers to use a point-to-point channel when each message should have exactly one owner; sending people elsewhere when they are better served is not competitive framing. The relocated section keeps the parts that did not move up: the conditions under which a dying consumer releases the ring, the fact that the no-loss guarantee belongs to a subscriber's lifetime rather than the ring, and subscribe_from_oldest's two-sided contract on a bounded channel.
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.
Two problems, opposite in direction.
The README opened with mechanism. Stamped ring buffers, per-slot validation,
T: Pod— before saying who it is for. The audience was mid-paragraph and the one genuinely distinguishing property, per-consumer delivery contracts, sat ~150 lines down under a heading nobody would search for. Now: who this is for, what you get that you would otherwise build yourself, and when to use something else instead. Mechanics follow, for readers who got that far because they care.The site had no landscape at all. Removing head-to-head scoring was right; removing every trace of context went too far and left a visitor unable to answer why this instead of what I already use. It now carries an approach-level table — locked queue, lock-free queue, shared sequence barrier, stamped slots — with what each costs and which problem each solves.
Categories rather than crate names, deliberately: the useful information is the trade, not a ranking. The one named alternative is the existing pointer telling readers to use a point-to-point channel when each message should have exactly one owner — sending people elsewhere when they are better served is not competitive framing.
No head-to-head benchmark scoring anywhere; that line holds.
The relocated section keeps what did not move up: the conditions under which a dying consumer releases the ring, that the no-loss guarantee belongs to a subscriber's lifetime rather than to the ring, and
subscribe_from_oldest's two-sided contract on a bounded channel.Verified: 219 tests, rustdoc clean under
-D warnings, fmt clean, HTML tag balance checked.