Loretta
73d81ea580
AcBinary: add framing doc, buffer growth fixes, doc updates - Added `BINARY_WHYUSE.md` for architectural framing and value proposition - Updated `BINARY_FEATURES.md` and `README.md` to reference and prioritize the new doc - Documented AsyncPipeWriterOutput chunk-size limitation and workarounds in `BINARY_ASYNCPIPE_ISSUES.md` - Refactored buffer growth logic in `AcBinarySerializer.BinarySerializationContext.cs` to validate capacity after grow and throw clear exceptions on under-provisioning; removed dead method - Fixed chunk size alignment bug in `AsyncPipeWriterOutput.cs` to prevent buffer under-provisioning - Added `AYCODE_NATIVEAOT` build config support in `Program.cs` - Improved documentation clarity and error diagnostics for streaming/buffered serialization edge cases |
||
|---|---|---|
| .. | ||
| BINARY_ASYNCPIPE_ISSUES.md | ||
| BINARY_ASYNCPIPE_TODO.md | ||
| BINARY_FEATURES.md | ||
| BINARY_FORMAT.md | ||
| BINARY_IMPLEMENTATION.md | ||
| BINARY_ISSUES.md | ||
| BINARY_OPTIONS.md | ||
| BINARY_SGEN.md | ||
| BINARY_TODO.md | ||
| BINARY_WHYUSE.md | ||
| BINARY_WRITERS.md | ||
| README.md | ||
README.md
BINARY — AcBinary serializer
AcBinary serialization system. Primary goal: speed (two-phase scan+serialize, reference tracking, string interning).
Files in this folder
BINARY_WHYUSE.md— Architectural framing: why AcBinary exists (category vs wire-only serializers, three-pillar value proposition, fit/not-fit decision lists, benchmark reading guide)BINARY_FEATURES.md— High-level features and capabilitiesBINARY_FORMAT.md— Wire format specificationBINARY_OPTIONS.md— Configuration options (AcBinaryOptions)BINARY_IMPLEMENTATION.md— Internal implementation detailsBINARY_WRITERS.md— Writer internals (streaming, buffering)BINARY_SGEN.md— Source generator (AyCode.Core.Serializers.SourceGenerator)BINARY_ISSUES.md— Known issues and limitations (binary serializer core)BINARY_TODO.md— Planned work / open tickets (binary serializer core)BINARY_ASYNCPIPE_ISSUES.md— Known issues and limitations (streaming I/O layer:AsyncPipeReaderInput+AsyncPipeWriterOutput)BINARY_ASYNCPIPE_TODO.md— Planned work / open tickets (streaming I/O layer)
Start here
Start with BINARY_WHYUSE.md (architectural framing — why this serializer over the alternatives), then BINARY_FEATURES.md (feature overview), then BINARY_FORMAT.md (wire-level). BINARY_SGEN.md covers build-time code-gen integration.
Cross-references
- Serialization overview (Toon vs AcBinary vs AcJson, shared infrastructure):
../../Serializers/README.md - SignalR binary transport (uses this serializer):
../../AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/README.md - ASP.NET Core MVC formatter (uses this serializer):
../../AyCode.Services/docs/MVC/README.md - Glossary terms:
../../../docs/GLOSSARY.md
Related ADRs
AyCode.Core/docs/adr/0003-acbinary-streaming-receive-architecture.md— Receive-side streaming architecture (Status: Accepted 2026-05-03, partially executed). Delivered:SegmentBufferReader+SegmentBufferReaderInputconsolidated into a singleAsyncPipeReaderInputprimitive (mirrors send-sideAsyncPipeWriterOutput); SignalR receive-side migration completed. Dropped during execution: NamedPipe + FileStream helpers (Steps 4 & 5) — framework stays consumer-implements-transport, exposes only genericPipeWriter/PipeReaderprimitives.