feat(linkable): add allocation-free postcard encode_into#180
Open
thaodt wants to merge 2 commits into
Open
Conversation
Add a caller-provided buffer API to `Linkable` while retaining the existing from_bytes and to_bytes signatures for compatibility. Introduce `LinkCodecError` and an optional into-slice serializer path in core. Each outbound route owns one bounded reusable scratch buffer, validates the returned length, and falls back to the existing `Vec` serializer when the buffer is too small. Legacy and custom codecs keep their previous behavior. Generate a true postcard override using `postcard::to_slice` with a 256-byte preferred capacity. Extend codegen drift coverage for generated connector wiring, exact and undersized buffers, Cortex-M compilation and the JSON-free dependency graph. Add an allocation-counting benchmark covering 10000 `encode_into` calls with zero allocation calls and zero allocated bytes. This removes the codec allocation only, connector-internal payload copies remain outside the claim.
Remove the newly introduced `LinkCodecError` and reuse the existing `aimdb_core::connector::SerializeError` across the into-slice API, postcard codegen, tests, benchmarks and documentation. Keep the legacy Linkable `from_bytes`/`to_bytes` String errors unchanged under the compatibility-first approach agreed in aimdb-dev#177.
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.
Description
This PR implements the foundation proposed in #177:
Linkable::encode_into(&mut [u8])aimdb_core::connector::SerializeErrorpostcard::to_sliceVec<u8>path for legacy, custom, and oversized valuesEach outbound route allocates its scratch buffer once when its pump starts and reuses it serially across messages.
No reference crosses the boxed reader-future boundary. The reader returns only payload metadata, while
pump_sinkowns the scratch storage, validates the returnedlength, and borrows the encoded prefix until
publish().awaitcompletes. This requires no newunsafe.When
encode_intoreturnsSerializeError::BufferTooSmall, the value is serialized once through the existing owned serializer:Other serialization errors retain the existing log-and-skip behavior.
postcardcodegenGenerated postcard
Linkableimpls now:ENCODE_BUFFER_CAPACITY = Some(256)postcard::to_sliceinencode_intoSerializeBufferFulltoLinkCodecError::BufferTooSmallpostcard::to_allocvecas the compatibility and oversized-value fallbackThe 256-byte capacity is a performance budget, not a wire-size limit. Generated outbound connector chains install
with_serializer_into, JSON and custom codecs remain unchanged.Compatibility and error scope
This implementation takes the compatibility-first approach agreed in #177's comment:
Linkable::from_bytesandLinkable::to_bytessignatures continue to returnStringLinkableimplementations continue to compile through the defaultencode_intoimplementationSerializedReaderimplementations continue to work through the default owned adapterSerializeError::{BufferTooSmall, InvalidData}aimdb_core::CodecErrorremains unchangedAllocation claim
The measured claim is intentionally limited to the codec seam:
The allocation benchmark executes 10000 encodes and reports:
This PR does not claim that the complete outbound connector path is allocation-free. The existing boxed
SerializedReaderfuture, dynamic topic generation and connector-internal payload ownership or copies remain outside this scope.Related Issue
Linkable::encode_into(&mut [u8])#177This also provides the allocation-aware foundation for #178.
Checklist
make check).