Skip to content

aalmada/Stationary / .agents/skills/dotnet-pipelines

dotnet-pipelines

Verified

Design, implement, debug, test, and review high-throughput byte-stream processing with System.IO.Pipelines. USE FOR: Pipe, PipeReader, PipeWriter, ReadResult, FlushResult, ReadOnlySequence, SequenceReader, buffer lifecycle, AdvanceTo, GetMemory, Advance, FlushAsync, stream and socket adapters, framing protocols, incremental parsing, backpressure, cancellation, and Pipes-to-Channels handoff. DO NOT USE FOR: item-level producer-consumer queues, durable/distributed messaging, ordinary small file I/O with no measured bottleneck, generic Stream APIs with no buffer-management concern, or ASP.NET middleware pipelines unrelated to System.IO.Pipelines.

references/testing-performance-and-review.md

View on GitHub
# Testing, Performance, And Review

## Test Matrix

| Scenario | Assert |
| --- | --- |
| Frame split across reads | Reader retains the suffix and emits one correct frame |
| Multiple frames in one read | Reader emits each frame and advances past all consumed bytes |
| Final incomplete data | Protocol reports the chosen invalid/truncation outcome |
| Empty completion | Reader completes without a spin or leaked buffer |
| Oversized header/frame | Reader rejects it before unbounded buffering/allocation |
| Read/flush cancellation | Loop exits according to the ownership contract and completes safely |
| Consumer completes early | Writer observes `FlushResult.IsCompleted` and stops |
| Deferred handling | Payload remains correct after `AdvanceTo` because it was copied/decoded |

Use controlled in-memory pipes and deliberately segmented writes. Avoid timing-based tests; await a known read/flush boundary or use a test-controlled synchronization point.

## Review Checklist

1. Is a pipe justified by measured throughput, allocation, framing, or an existing pipe API?
2. Does every `ReadAsync` call receive one `AdvanceTo` in `finally`?
3. Do `consumed` and `examined` describe the parser's actual progress?
4. Can any pipe-owned buffer escape past `AdvanceTo`?
5. Are maximum header/frame sizes and invalid terminal data behavior defined?
6. Is every `FlushAsync` awaited and are `IsCompleted`/`IsCanceled` results handled?
7. Are reader/writer completion owners unambiguous and exceptions propagated?
8. Are calls to `ReadAsync` and `FlushAsync` serialized per pipe end?
9. If Channels follow parsing, are work items owned, bounded, and ordering-safe?

## Measure Before Tuning

- Compare end-to-end throughput, allocation rate, retained bytes, latency, and CPU under representative frame sizes and fragmentation.
- Benchmark alternative framing/copying strategies with realistic I/O and concurrency. Do not infer a general speedup from another workload's benchmark.
- Investigate sustained retained buffers, pending flushes, read loops that wake without new data, and growing incomplete frames.

## Sources

- [System.IO.Pipelines: common PipeReader problems](https://learn.microsoft.com/dotnet/standard/io/pipelines#pipereader-common-problems)
- [Pipelines and Channels performance example](https://dev.to/joni2nja/use-system-io-pipelines-and-system-threading-channels-apis-to-boost-performance-2nj5)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall