fix

Author: Joshuahoky

examples/src/hello_world/greeter_client_v5_default.rs

@@ -46,9 +46,12 @@ async fn main() {
     const SIZES: [usize; 3] = [25, 64 << 10, 512 << 10];
     const ROUNDS: usize = 90;
 
-    // Nothing calls `release_previous_read`: a block goes back to its owner as soon as its
-    // last byte is read. Whether that actually happens is what the numbers below show — a
-    // segment that never took anything back would climb without bound instead of settling.
+    // Nothing calls `release_previous_read`: a block goes back to its owner once its last byte
+    // has been read and the reader has dropped what the read handed it, which is what the
+    // `drop(body)` below is. A read of shared memory is a borrow of the peer's block rather
+    // than a copy of it, so holding on to one holds the block. Whether the blocks come back at
+    // all is what the numbers below show — a segment that never took anything back would climb
+    // without bound instead of settling.
     for round in 1..=ROUNDS {
         let size = SIZES[round % SIZES.len()];
         let payload = vec![b'x'; size];

src/buffer/buf.rs

@@ -12,11 +12,28 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use std::{borrow::Borrow, cmp, fmt, hash, ops::Deref};
+use std::{borrow::Borrow, cmp, fmt, hash, ops::Deref, sync::Arc};
 
 use bytes::Bytes;
 
-use super::linked::PinLease;
+use super::{linked::SlicePinState, v5::V5PinState};
+
+/// What holds the memory a [`ShmBuf`] borrows in place for as long as the borrow lives.
+///
+/// A lease is never read: it is a drop guard, and it is the last one dropped that hands the
+/// memory back. What that means differs by buffer — a V4 slice goes to the buffer manager it
+/// was allocated from, a V5 block goes onto the peer's release queue — so each buffer keeps
+/// its own state behind its own `Drop` and this only says which.
+#[allow(
+    dead_code,
+    reason = "holding the state is the whole of a lease's job; nothing ever reads it"
+)]
+pub(crate) enum PinLease {
+    /// One slice of a V4 [`LinkedBuffer`](super::LinkedBuffer).
+    Slice(Arc<SlicePinState>),
+    /// One block of the peer's V5 segment.
+    Block(Arc<V5PinState>),
+}
 
 pub struct ShmBuf<'shm> {
     buf: &'shm [u8],
@@ -35,8 +52,10 @@ impl<'shm> ShmBuf<'shm> {
     }
 
     fn into_bytes(self) -> Bytes {
-        // The lease keeps both the mapping and the retired BufferSlice alive until the final
-        // Bytes clone is dropped, so erasing the borrow lifetime here is sound.
+        // The lease keeps the mapping alive, along with whatever inside it the bytes were read
+        // out of — a retired BufferSlice, or a block of the peer's segment that is kept off
+        // the release queue — until the final Bytes clone is dropped, so erasing the borrow
+        // lifetime here is sound.
         let owner: ShmBuf<'static> = unsafe { std::mem::transmute(self) };
         Bytes::from_owner(owner)
     }

src/buffer/linked.rs

@@ -22,7 +22,7 @@ use tokio::io::ReadBuf;
 
 use super::{
     BufferReader, BufferWriter,
-    buf::{Buf, ShmBuf},
+    buf::{Buf, PinLease, ShmBuf},
 };
 use crate::{
     buffer::{
@@ -66,7 +66,7 @@ impl PinRegistry {
             });
             state
         };
-        PinLease { _state: state }
+        PinLease::Slice(state)
     }
 
     fn is_pinned(&self, slice: &BufferSlice) -> bool {
@@ -110,8 +110,13 @@ impl PinRegistry {
     }
 }
 
+/// Keeps one V4 slice alive while a zero-copy read still borrows from it.
+///
+/// The slice is retired into here when the buffer is done with it, and reclaimed when the last
+/// [`PinLease`] over it is dropped — the counterpart on the V5 side is
+/// [`V5PinState`](super::v5::V5PinState).
 #[derive(Debug)]
-struct SlicePinState {
+pub(crate) struct SlicePinState {
     buffer_manager: Arc<BufferManager>,
     retired_slice: Mutex<Option<BufferSlice>>,
 }
@@ -152,10 +157,6 @@ fn reclaim_slice(buffer_manager: &BufferManager, slice: BufferSlice) {
     }
 }
 
-pub(crate) struct PinLease {
-    _state: Arc<SlicePinState>,
-}
-
 #[derive(Debug)]
 pub struct LinkedBuffer {
     slice_list: SliceList,