From 444ded1051c99264d079e492baf720640332ae3f Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 8 Nov 2026 23:20:05 +1100 Subject: [PATCH] docs(byte-storage): say encode_into is not faster than store plus a copy --- src/byte_storage.rs | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/byte_storage.rs b/src/byte_storage.rs index c065011..441be55 100644 --- a/src/byte_storage.rs +++ b/src/byte_storage.rs @@ -271,12 +271,16 @@ impl StorageEnvelope { /// [`ByteStorage::store`] returns, into `out`, which must be exactly /// [`encoded_len`](Self::encoded_len) bytes long. /// - /// For a binding that owns the output memory (a Python `bytes`, say): it - /// sizes the buffer with `encoded_len` and writes once, with no - /// intermediate `Vec` and no MessagePack dependency of its own. Measure - /// before using it for envelopes of 64 KiB and up: removing a - /// payload-sized buffer there can make an operation slower under glibc's - /// malloc (see `ByteStorage::store`, which therefore does not). + /// It writes into memory the caller owns, so a binding needs no + /// MessagePack dependency of its own. It is not faster than + /// `ByteStorage::store` plus a copy: the slice writer makes one `memcpy` + /// call per field, and a zero-filled output buffer costs what the copy + /// saved. Measured in cachekit-py, it took more instructions per store at + /// most sizes below 32 KiB, saved at most 1.5% at any size, and made no + /// end-to-end difference. Measure before using it for envelopes of 64 KiB + /// and up: removing a payload-sized buffer there can make an operation + /// slower under glibc's malloc (see `ByteStorage::store`, which therefore + /// does not). /// /// # Errors ///