From 60db27f961564980779d30ef2f8b2e2d53be1495 Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:04:18 +0200 Subject: [PATCH 1/4] docs(bytesbuf): add stabilization notes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: d2e2ec60-4490-44b2-8717-aad478da5b0a --- crates/bytesbuf/docs/DESIGN.md | 0 crates/bytesbuf/docs/STABILIZATION.md | 66 +++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 crates/bytesbuf/docs/DESIGN.md create mode 100644 crates/bytesbuf/docs/STABILIZATION.md diff --git a/crates/bytesbuf/docs/DESIGN.md b/crates/bytesbuf/docs/DESIGN.md new file mode 100644 index 000000000..e69de29bb diff --git a/crates/bytesbuf/docs/STABILIZATION.md b/crates/bytesbuf/docs/STABILIZATION.md new file mode 100644 index 000000000..5e940a9b6 --- /dev/null +++ b/crates/bytesbuf/docs/STABILIZATION.md @@ -0,0 +1,66 @@ +# Stabilization Notes + +These notes capture the pending decisions for stabilizing `bytesbuf`. They +describe proposals under review, not a finalized stable API. + +## Proposed stable boundary + +Stabilize the core owned byte-sequence types: + +- `BytesBuf` for assembling and owning writable byte sequences. +- `BytesView` for sharing and consuming immutable byte sequences. +- The iterator and cursor types returned by their stable operations: + `BytesBufRemaining`, `BytesBufVectoredWrite`, and `BytesViewSlices`. +- `MemoryGuard` for keeping memory alive while native or unsafe I/O uses it. + +The stable operation groups should cover: + +- Creating empty buffers and views, reserving capacity, and querying length, + capacity, and emptiness. +- Appending copied bytes or existing views, then consuming or peeking buffered + data as immutable views. +- Slicing, ranging, concatenating, advancing, and iterating over view contents. +- Accessing unfilled buffer memory, including vectored access, and committing + the number of bytes initialized by an owned-buffer read operation. +- Standard I/O and `bytes` crate adapters where their Cargo features are + enabled. + +## Memory-provider boundary + +Stabilize the provider contracts needed by consumers and I/O implementations: + +- `Memory` for reserving owned writable capacity. +- `MemoryShared` and `HasMemory` for sharing an endpoint-compatible provider. +- `GlobalPool` as the standard pooled provider. +- `OpaqueMemory` for storing a provider without exposing its concrete type. + +The provider surface must preserve ownership, reuse, and cross-thread release +semantics needed by asynchronous operating-system I/O. + +## Deferred surface + +Keep convenience providers, test utilities, constants, and low-level block and +reference-counting machinery outside the stable surface unless the provider +implementation review proves they are required. This includes +`CallbackMemory`, `Block`, `BlockRef`, their metadata and vtable APIs, and +`MAX_INLINE_SPANS`. + +If stable custom memory providers require any of these types, expose only the +smallest reviewed construction boundary instead of stabilizing implementation +details by default. + +## Pending review + +- [ ] Explicitly list and review every method included for `BytesBuf` and + `BytesView`. +- [ ] Confirm the writable-slice and vectored-write APIs support the approved + owned-buffer Read/Write design without exposing uninitialized memory + unsafely. +- [ ] Validate ownership transfer, reuse, cloning, range, and conversion + semantics for asynchronous I/O. +- [ ] Decide whether `BytesBufWriter` belongs in the stable standard-library + adapter surface. +- [ ] Decide which `bytes` compatibility implementations are stable. +- [ ] Determine the minimal stable API for implementing custom memory providers. +- [ ] Confirm stable downstream crates expose no deferred `bytesbuf` types. +- [ ] Identify all remaining APIs as stable, unstable, or unnecessary for 1.0. From 92af927df6fcc1f60b3a7eeb497e62a44f61a0ce Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:12:18 +0200 Subject: [PATCH 2/4] docs(bytesbuf): clarify stabilization dependencies Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: d2e2ec60-4490-44b2-8717-aad478da5b0a --- crates/bytesbuf/docs/STABILIZATION.md | 28 +++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/crates/bytesbuf/docs/STABILIZATION.md b/crates/bytesbuf/docs/STABILIZATION.md index 5e940a9b6..a4f95bc62 100644 --- a/crates/bytesbuf/docs/STABILIZATION.md +++ b/crates/bytesbuf/docs/STABILIZATION.md @@ -11,6 +11,8 @@ Stabilize the core owned byte-sequence types: - `BytesView` for sharing and consuming immutable byte sequences. - The iterator and cursor types returned by their stable operations: `BytesBufRemaining`, `BytesBufVectoredWrite`, and `BytesViewSlices`. +- `BlockMeta`, because the current slice iterator types expose it in their + public item types. - `MemoryGuard` for keeping memory alive while native or unsafe I/O uses it. The stable operation groups should cover: @@ -22,8 +24,9 @@ The stable operation groups should cover: - Slicing, ranging, concatenating, advancing, and iterating over view contents. - Accessing unfilled buffer memory, including vectored access, and committing the number of bytes initialized by an owned-buffer read operation. -- Standard I/O and `bytes` crate adapters where their Cargo features are - enabled. + +Standard I/O and `bytes` crate adapters require separate review before they +join the stable boundary. ## Memory-provider boundary @@ -31,7 +34,8 @@ Stabilize the provider contracts needed by consumers and I/O implementations: - `Memory` for reserving owned writable capacity. - `MemoryShared` and `HasMemory` for sharing an endpoint-compatible provider. -- `GlobalPool` as the standard pooled provider. +- `GlobalPool` as the standard pooled provider when the `std` feature is + enabled. - `OpaqueMemory` for storing a provider without exposing its concrete type. The provider surface must preserve ownership, reuse, and cross-thread release @@ -39,15 +43,16 @@ semantics needed by asynchronous operating-system I/O. ## Deferred surface -Keep convenience providers, test utilities, constants, and low-level block and +Keep convenience providers, test utilities, constants, and low-level reference-counting machinery outside the stable surface unless the provider implementation review proves they are required. This includes -`CallbackMemory`, `Block`, `BlockRef`, their metadata and vtable APIs, and +`CallbackMemory`, `BlockRef`, its dynamic traits and vtable API, and `MAX_INLINE_SPANS`. -If stable custom memory providers require any of these types, expose only the -smallest reviewed construction boundary instead of stabilizing implementation -details by default. +These APIs are public today, so excluding them requires removing or hiding them +before 1.0. The current custom-provider workflow also requires `Block` and the +`BlockRef` family. Either stabilize the smallest reviewed subset of that +machinery or replace it with a narrower stable construction API. ## Pending review @@ -59,8 +64,11 @@ details by default. - [ ] Validate ownership transfer, reuse, cloning, range, and conversion semantics for asynchronous I/O. - [ ] Decide whether `BytesBufWriter` belongs in the stable standard-library - adapter surface. + adapter surface enabled by the `std` feature. - [ ] Decide which `bytes` compatibility implementations are stable. -- [ ] Determine the minimal stable API for implementing custom memory providers. +- [ ] Determine the minimal stable API for implementing custom memory providers, + including whether `Block`, `BlockRef`, and related traits remain public. +- [ ] Confirm whether the metadata-returning iterator shapes remain stable; if + they change, reconsider whether `BlockMeta` belongs in the stable surface. - [ ] Confirm stable downstream crates expose no deferred `bytesbuf` types. - [ ] Identify all remaining APIs as stable, unstable, or unnecessary for 1.0. From fcfee9b18f9185292614ba2ae415e7abbed77771 Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:13:53 +0200 Subject: [PATCH 3/4] docs(bytesbuf): cover metadata exposure points Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: d2e2ec60-4490-44b2-8717-aad478da5b0a --- crates/bytesbuf/docs/STABILIZATION.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/crates/bytesbuf/docs/STABILIZATION.md b/crates/bytesbuf/docs/STABILIZATION.md index a4f95bc62..9b4e2ca25 100644 --- a/crates/bytesbuf/docs/STABILIZATION.md +++ b/crates/bytesbuf/docs/STABILIZATION.md @@ -11,8 +11,8 @@ Stabilize the core owned byte-sequence types: - `BytesView` for sharing and consuming immutable byte sequences. - The iterator and cursor types returned by their stable operations: `BytesBufRemaining`, `BytesBufVectoredWrite`, and `BytesViewSlices`. -- `BlockMeta`, because the current slice iterator types expose it in their - public item types. +- `BlockMeta`, because the current slice iterator types and direct slice + metadata methods expose it in their public signatures. - `MemoryGuard` for keeping memory alive while native or unsafe I/O uses it. The stable operation groups should cover: @@ -68,7 +68,8 @@ machinery or replace it with a narrower stable construction API. - [ ] Decide which `bytes` compatibility implementations are stable. - [ ] Determine the minimal stable API for implementing custom memory providers, including whether `Block`, `BlockRef`, and related traits remain public. -- [ ] Confirm whether the metadata-returning iterator shapes remain stable; if - they change, reconsider whether `BlockMeta` belongs in the stable surface. +- [ ] Confirm whether the metadata-returning iterator shapes and direct + `first_slice_meta()` methods remain stable. Removing `BlockMeta` from the + stable surface requires redesigning all of these exposure points. - [ ] Confirm stable downstream crates expose no deferred `bytesbuf` types. - [ ] Identify all remaining APIs as stable, unstable, or unnecessary for 1.0. From cf75956bf67d44c381889e1900933fa9fdb6417c Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:16:17 +0200 Subject: [PATCH 4/4] docs(bytesbuf): name all metadata methods Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: d2e2ec60-4490-44b2-8717-aad478da5b0a --- crates/bytesbuf/docs/STABILIZATION.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/crates/bytesbuf/docs/STABILIZATION.md b/crates/bytesbuf/docs/STABILIZATION.md index 9b4e2ca25..83d408c24 100644 --- a/crates/bytesbuf/docs/STABILIZATION.md +++ b/crates/bytesbuf/docs/STABILIZATION.md @@ -68,8 +68,9 @@ machinery or replace it with a narrower stable construction API. - [ ] Decide which `bytes` compatibility implementations are stable. - [ ] Determine the minimal stable API for implementing custom memory providers, including whether `Block`, `BlockRef`, and related traits remain public. -- [ ] Confirm whether the metadata-returning iterator shapes and direct - `first_slice_meta()` methods remain stable. Removing `BlockMeta` from the - stable surface requires redesigning all of these exposure points. +- [ ] Confirm whether the metadata-returning iterator shapes, + `first_slice_meta()`, and `first_unfilled_slice_meta()` remain stable. + Removing `BlockMeta` from the stable surface requires redesigning all of + these exposure points. - [ ] Confirm stable downstream crates expose no deferred `bytesbuf` types. - [ ] Identify all remaining APIs as stable, unstable, or unnecessary for 1.0.