Skip to main content

hyperlight_common/virtq/
buffer.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 The Hyperlight Authors.
3
4//! Owned and segmented virtqueue buffer representations.
5
6use alloc::vec::Vec;
7
8use bytes::{Buf, Bytes};
9use smallvec::{SmallVec, smallvec};
10
11use super::{Allocation, SlotPool};
12
13/// Ordered byte segments that make up one virtqueue payload.
14///
15/// This is the high-level counterpart to the descriptor-oriented
16/// [`BufferChain`](super::BufferChain).
17#[derive(Debug, Default)]
18pub struct Segments {
19    chunks: SmallVec<[Bytes; 4]>,
20    /// Earlier slots contain empty `Bytes` and retain no owners.
21    head: usize,
22}
23
24impl Segments {
25    /// Build a segmented payload from ordered byte segments.
26    pub fn new(segments: impl IntoIterator<Item = Bytes>) -> Self {
27        Self::from_smallvec(segments.into_iter().collect())
28    }
29
30    /// Build a single-segment payload.
31    pub fn single(segment: Bytes) -> Self {
32        Self::from_smallvec(smallvec![segment])
33    }
34
35    /// Reuse an existing segment list.
36    pub(crate) fn from_smallvec(segments: SmallVec<[Bytes; 4]>) -> Self {
37        Self {
38            chunks: segments,
39            head: 0,
40        }
41    }
42
43    /// Total payload length across all segments.
44    pub fn len(&self) -> usize {
45        self.iter().map(Bytes::len).sum()
46    }
47
48    /// Whether the payload contains zero bytes.
49    pub fn is_empty(&self) -> bool {
50        self.iter().all(Bytes::is_empty)
51    }
52
53    /// Number of byte segments.
54    pub fn segment_count(&self) -> usize {
55        self.chunks.len() - self.head
56    }
57
58    /// Borrow all segments.
59    pub fn as_slice(&self) -> &[Bytes] {
60        &self.chunks[self.head..]
61    }
62
63    /// Iterate over segments.
64    pub fn iter(&self) -> impl Iterator<Item = &Bytes> {
65        self.as_slice().iter()
66    }
67
68    /// Append another payload without copying its bytes.
69    ///
70    /// Compacts consumed slots before extending the segment list.
71    pub fn append(&mut self, other: Self) {
72        if self.head != 0 {
73            drop(self.chunks.drain(..self.head));
74            self.head = 0;
75        }
76
77        self.chunks
78            .extend(other.chunks.into_iter().skip(other.head));
79    }
80
81    /// Split off an owned byte prefix without copying payload data.
82    ///
83    /// Scans only the prefix, then transfers its segments without shifting the
84    /// remainder. A boundary segment shares its [`Bytes`] owner.
85    ///
86    /// Returns `None` and leaves `self` unchanged when `len` exceeds the
87    /// remaining payload length.
88    pub fn split_to(&mut self, len: usize) -> Option<Self> {
89        if len == 0 {
90            return Some(Self::default());
91        }
92
93        let mut end = self.head;
94        let mut remaining = len;
95
96        while remaining != 0 {
97            let segment = self.chunks.get(end)?;
98
99            if segment.len() > remaining {
100                break;
101            }
102
103            remaining -= segment.len();
104            end += 1;
105        }
106
107        // Small suffixes must not inherit storage for consumed segments.
108        if self.head == 0 && end == self.chunks.len() {
109            return Some(core::mem::take(self));
110        }
111
112        let mut prefix =
113            SmallVec::<[Bytes; 4]>::with_capacity(end - self.head + usize::from(remaining != 0));
114
115        for segment in &mut self.chunks[self.head..end] {
116            prefix.push(core::mem::take(segment));
117        }
118
119        self.head = end;
120
121        if remaining != 0 {
122            prefix.push(self.chunks[end].split_to(remaining));
123        }
124
125        Some(Self::from_smallvec(prefix))
126    }
127
128    /// Borrow this payload as a [`Buf`] cursor.
129    pub fn as_buf(&self) -> SegmentsBuf<'_> {
130        SegmentsBuf::new(self.as_slice(), self.len())
131    }
132
133    /// Return this payload as contiguous bytes.
134    ///
135    /// This is O(1) for zero or one segment, and allocates/copies for multiple
136    /// segments.
137    pub fn to_bytes(&self) -> Bytes {
138        match self.as_slice() {
139            [] => Bytes::new(),
140            [segment] => segment.clone(),
141            _ => self.collect(self.as_slice(), self.len()),
142        }
143    }
144
145    /// Consume this payload and return contiguous bytes.
146    ///
147    /// Reuses a single segment's storage, and allocates/copies for multiple segments.
148    pub fn into_bytes(mut self) -> Bytes {
149        match self.segment_count() {
150            0 => Bytes::new(),
151            1 => self.chunks.pop().unwrap_or_default(),
152            _ => self.collect(self.as_slice(), self.len()),
153        }
154    }
155
156    /// Consume this payload without flattening its segments.
157    pub fn into_chunks(mut self) -> Vec<Bytes> {
158        if self.head != 0 {
159            drop(self.chunks.drain(..self.head));
160        }
161
162        self.chunks.into_vec()
163    }
164
165    fn collect(&self, sgs: &[Bytes], len: usize) -> Bytes {
166        let mut out = Vec::with_capacity(len);
167        for seg in sgs {
168            out.extend_from_slice(seg);
169        }
170        Bytes::from(out)
171    }
172}
173
174impl Clone for Segments {
175    /// Clone only unconsumed segment handles.
176    fn clone(&self) -> Self {
177        Self::new(self.iter().cloned())
178    }
179}
180
181/// Borrowed [`Buf`] cursor over [`Segments`].
182///
183/// Advancing the cursor does not mutate the underlying [`Segments`].
184#[derive(Debug, Clone)]
185pub struct SegmentsBuf<'a> {
186    segments: &'a [Bytes],
187    index: usize,
188    offset: usize,
189    remaining: usize,
190}
191
192impl<'a> SegmentsBuf<'a> {
193    fn new(segments: &'a [Bytes], len: usize) -> Self {
194        let mut this = Self {
195            segments,
196            index: 0,
197            offset: 0,
198            remaining: len,
199        };
200
201        this.skip_empty_segments();
202        this
203    }
204
205    fn skip_empty_segments(&mut self) {
206        while self.index < self.segments.len() && self.offset >= self.segments[self.index].len() {
207            self.index += 1;
208            self.offset = 0;
209        }
210    }
211}
212
213impl Buf for SegmentsBuf<'_> {
214    fn remaining(&self) -> usize {
215        self.remaining
216    }
217
218    fn chunk(&self) -> &[u8] {
219        if self.remaining == 0 {
220            return &[];
221        }
222
223        let segment = self.segments[self.index].as_ref();
224        &segment[self.offset..]
225    }
226
227    fn advance(&mut self, cnt: usize) {
228        assert!(cnt <= self.remaining, "cannot advance past remaining bytes");
229
230        self.remaining -= cnt;
231        let mut cnt = cnt;
232
233        while cnt > 0 {
234            let seg_rem = self.segments[self.index].len() - self.offset;
235            let n = seg_rem.min(cnt);
236            self.offset += n;
237            cnt -= n;
238            self.skip_empty_segments();
239        }
240
241        if self.remaining == 0 {
242            self.index = self.segments.len();
243            self.offset = 0;
244        }
245    }
246}
247
248/// A buffer allocation returned to its original pool on drop.
249pub struct BufferLease {
250    /// The pool that allocated the buffer.
251    pool: SlotPool,
252    /// The buffer's start address and full allocation capacity.
253    allocation: Allocation,
254}
255
256impl BufferLease {
257    /// Create a new buffer lease from a pool and allocation.
258    pub fn new(pool: SlotPool, allocation: Allocation) -> Self {
259        Self { pool, allocation }
260    }
261
262    /// The buffer's start address and full allocation capacity.
263    pub fn allocation(&self) -> Allocation {
264        self.allocation
265    }
266}
267
268impl Drop for BufferLease {
269    fn drop(&mut self) {
270        if let Err(error) = self.pool.dealloc(self.allocation.addr) {
271            log::error!("Failed to release a virtqueue buffer: {error}");
272            debug_assert!(false, "BufferLease deallocation failed: {error}");
273        }
274    }
275}
276
277#[cfg(test)]
278mod tests {
279    use alloc::sync::Arc;
280
281    use bytes::Buf;
282
283    use super::*;
284    use crate::virtq::{SlotLayout, SlotPool};
285
286    #[test]
287    fn lease_returns_slot_on_drop() {
288        let layout = SlotLayout::new(0, 4, 1).unwrap();
289        let pool = SlotPool::new(layout).unwrap();
290        let allocation = pool.alloc(4).unwrap();
291        let lease = BufferLease::new(pool.clone(), allocation);
292
293        assert_eq!(lease.allocation().addr, allocation.addr);
294        assert_eq!(lease.allocation().len, 4);
295        assert_eq!(pool.num_free(), 0);
296
297        drop(lease);
298        assert_eq!(pool.num_free(), 1);
299
300        let reused = pool.alloc(4).unwrap();
301        assert_eq!(reused.addr, allocation.addr);
302        pool.dealloc(reused.addr).unwrap();
303    }
304
305    #[test]
306    fn old_leases_do_not_release_a_reused_slot() {
307        let mut pool = SlotPool::new(SlotLayout::new(0x1000, 4096, 1).unwrap()).unwrap();
308        let mut allocation = pool.alloc(4096).unwrap();
309        let mut retained = Vec::new();
310
311        for _ in 0..3 {
312            retained.push(BufferLease::new(pool.clone(), allocation));
313            pool = pool.swap(core::iter::empty()).unwrap();
314            let reused = pool.alloc(4096).unwrap();
315            assert_eq!(reused.addr, allocation.addr);
316            allocation = reused;
317        }
318
319        drop(retained);
320        assert_eq!(pool.num_free(), 0);
321        drop(BufferLease::new(pool.clone(), allocation));
322        assert_eq!(pool.num_free(), 1);
323    }
324
325    #[test]
326    fn swap_preserves_queue_reservations() {
327        let pool = SlotPool::new(SlotLayout::new(0x1000, 4096, 2).unwrap()).unwrap();
328        let reserved = pool.alloc(4096).unwrap();
329        let captured = pool.alloc(4096).unwrap();
330        let retained = BufferLease::new(pool.clone(), captured);
331
332        let swapped = pool.swap(core::iter::once(reserved.addr)).unwrap();
333        assert_eq!(swapped.num_free(), 1);
334        assert_eq!(swapped.alloc(4096).unwrap().addr, captured.addr);
335
336        drop(retained);
337        assert_eq!(swapped.num_free(), 0);
338        swapped.dealloc(reserved.addr).unwrap();
339        swapped.dealloc(captured.addr).unwrap();
340        assert_eq!(swapped.num_free(), 2);
341        pool.dealloc(reserved.addr).unwrap();
342        assert_eq!(pool.num_free(), 2);
343    }
344
345    #[test]
346    fn segments_cursor_advances_across_segments() {
347        let segments = Segments::new([
348            Bytes::from_static(b"abc"),
349            Bytes::from_static(b"def"),
350            Bytes::from_static(b"ghi"),
351        ]);
352        let mut cursor = segments.as_buf();
353
354        assert_eq!(cursor.remaining(), 9);
355        assert_eq!(cursor.chunk(), b"abc");
356
357        cursor.advance(2);
358        assert_eq!(cursor.remaining(), 7);
359        assert_eq!(cursor.chunk(), b"c");
360
361        cursor.advance(1);
362        assert_eq!(cursor.chunk(), b"def");
363
364        cursor.advance(4);
365        assert_eq!(cursor.chunk(), b"hi");
366
367        cursor.advance(2);
368        assert_eq!(cursor.remaining(), 0);
369        assert_eq!(cursor.chunk(), b"");
370    }
371
372    #[test]
373    fn segments_cursor_skips_empty_segments() {
374        let segments = Segments::new([
375            Bytes::new(),
376            Bytes::from_static(b"ab"),
377            Bytes::new(),
378            Bytes::from_static(b"cd"),
379            Bytes::new(),
380        ]);
381        let mut cursor = segments.as_buf();
382
383        assert_eq!(cursor.remaining(), 4);
384        assert_eq!(cursor.chunk(), b"ab");
385
386        cursor.advance(2);
387        assert_eq!(cursor.remaining(), 2);
388        assert_eq!(cursor.chunk(), b"cd");
389
390        cursor.advance(2);
391        assert!(!cursor.has_remaining());
392        assert_eq!(cursor.chunk(), b"");
393    }
394
395    #[test]
396    fn segments_cursor_reads_split_header_without_collecting_all_segments() {
397        let segments = Segments::new([
398            Bytes::from_static(&[0x01, 0x02, 0x03]),
399            Bytes::from_static(&[0x04, 0x05]),
400            Bytes::from_static(&[0x06, 0x07, 0x08, 0xff]),
401        ]);
402        let mut cursor = segments.as_buf();
403        let mut header = [0u8; 8];
404
405        cursor.try_copy_to_slice(&mut header).unwrap();
406
407        assert_eq!(header, [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
408        assert_eq!(cursor.remaining(), 1);
409        assert_eq!(cursor.chunk(), &[0xff]);
410    }
411
412    #[test]
413    fn segments_cursor_copy_to_bytes_collects_only_requested_prefix() {
414        let segments = Segments::new([
415            Bytes::from_static(b"hello"),
416            Bytes::from_static(b" "),
417            Bytes::from_static(b"world"),
418        ]);
419        let mut cursor = segments.as_buf();
420
421        let prefix = cursor.copy_to_bytes(6);
422
423        assert_eq!(prefix.as_ref(), b"hello ");
424        assert_eq!(cursor.remaining(), 5);
425        assert_eq!(cursor.chunk(), b"world");
426    }
427
428    #[test]
429    fn segments_split_to_shares_boundary_segment() {
430        let boundary = Bytes::from(vec![b'd', b'e', b'f']);
431        let boundary_ptr = boundary.as_ptr();
432        let mut segments = Segments::new([
433            Bytes::from_static(b"abc"),
434            boundary,
435            Bytes::from_static(b"ghi"),
436        ]);
437
438        let prefix = segments.split_to(5).unwrap();
439
440        assert_eq!(prefix.segment_count(), 2);
441        assert_eq!(prefix.to_bytes().as_ref(), b"abcde");
442        assert_eq!(prefix.as_slice()[1].as_ptr(), boundary_ptr);
443        assert_eq!(segments.segment_count(), 2);
444        assert_eq!(segments.to_bytes().as_ref(), b"fghi");
445        assert_eq!(
446            segments.as_slice()[0].as_ptr(),
447            boundary_ptr.wrapping_add(2)
448        );
449
450        assert!(segments.split_to(5).is_none());
451        assert_eq!(segments.to_bytes().as_ref(), b"fghi");
452    }
453
454    #[test]
455    fn segments_split_to_preserves_empty_segments() {
456        let mut segments = Segments::new([
457            Bytes::new(),
458            Bytes::from_static(b"ab"),
459            Bytes::new(),
460            Bytes::from_static(b"cd"),
461            Bytes::new(),
462        ]);
463        let original = segments.as_slice().to_vec();
464
465        assert!(segments.split_to(5).is_none());
466        assert_eq!(segments.as_slice(), original);
467        assert_eq!(segments.split_to(0).unwrap().segment_count(), 0);
468        assert_eq!(segments.as_slice(), original);
469
470        let first = segments.split_to(2).unwrap();
471        assert_eq!(first.as_slice(), &[Bytes::new(), Bytes::from_static(b"ab")]);
472        assert_eq!(segments.segment_count(), 3);
473
474        let second = segments.split_to(2).unwrap();
475        assert_eq!(
476            second.as_slice(),
477            &[Bytes::new(), Bytes::from_static(b"cd")]
478        );
479        assert!(segments.is_empty());
480        assert_eq!(segments.segment_count(), 1);
481        assert_eq!(segments.split_to(0).unwrap().segment_count(), 0);
482        assert!(segments.split_to(1).is_none());
483        assert_eq!(segments.as_slice(), &[Bytes::new()]);
484    }
485
486    #[test]
487    fn segments_split_to_reuses_full_segment_list() {
488        let mut segments = Segments::new((0..8).map(|byte| Bytes::from(vec![byte])));
489        let storage = segments.chunks.as_ptr();
490
491        let prefix = segments.split_to(8).unwrap();
492
493        assert_eq!(prefix.chunks.as_ptr(), storage);
494        assert_eq!(prefix.segment_count(), 8);
495        assert_eq!(prefix.into_bytes().as_ref(), &[0, 1, 2, 3, 4, 5, 6, 7]);
496        assert!(segments.is_empty());
497        assert_eq!(segments.segment_count(), 0);
498    }
499
500    #[test]
501    fn segments_split_to_keeps_small_suffix_inline() {
502        #[cfg(miri)]
503        let count = 64;
504        #[cfg(not(miri))]
505        let count = 8192;
506
507        let mut segments = Segments::new((0..count).map(|_| Bytes::from_static(b"x")));
508        drop(segments.split_to(count - 1).unwrap());
509
510        let suffix = segments.split_to(1).unwrap();
511
512        assert!(!suffix.chunks.spilled());
513        assert_eq!(suffix.head, 0);
514        assert_eq!(suffix.into_bytes().as_ref(), b"x");
515        assert!(segments.is_empty());
516        assert_eq!(segments.segment_count(), 0);
517    }
518
519    #[test]
520    fn segments_split_to_keeps_large_remainder_in_place() {
521        #[cfg(miri)]
522        let count = 64;
523        #[cfg(not(miri))]
524        let count = 8192;
525        let half = count / 2;
526
527        let mut segments = Segments::new((0..count).map(|_| Bytes::from_static(b"x")));
528        let storage = segments.chunks.as_ptr();
529
530        let prefix = segments.split_to(half).unwrap();
531
532        assert_eq!(prefix.segment_count(), half);
533        assert!(prefix.iter().all(|segment| segment.as_ref() == b"x"));
534        assert_eq!(segments.segment_count(), half);
535        assert_eq!(segments.as_slice().as_ptr(), storage.wrapping_add(half));
536        assert!(segments.chunks[..segments.head].iter().all(Bytes::is_empty));
537    }
538
539    #[test]
540    fn segments_split_to_repeatedly_consumes_fragments() {
541        #[cfg(miri)]
542        let count = 64;
543        #[cfg(not(miri))]
544        let count = 4096;
545
546        let mut segments = Segments::new((0..count).map(|_| Bytes::from_static(b"ab")));
547
548        for _ in 0..count {
549            assert_eq!(segments.split_to(1).unwrap().into_bytes().as_ref(), b"a");
550            assert_eq!(segments.split_to(1).unwrap().into_bytes().as_ref(), b"b");
551        }
552
553        assert!(segments.is_empty());
554        assert_eq!(segments.segment_count(), 0);
555        assert!(segments.split_to(1).is_none());
556    }
557
558    #[test]
559    fn segments_split_to_releases_owners_independently() {
560        let first: Arc<[u8]> = Arc::from(&b"abc"[..]);
561        let boundary: Arc<[u8]> = Arc::from(&b"def"[..]);
562        let last: Arc<[u8]> = Arc::from(&b"ghi"[..]);
563        let first_owner = Arc::downgrade(&first);
564        let boundary_owner = Arc::downgrade(&boundary);
565        let last_owner = Arc::downgrade(&last);
566        let mut segments = Segments::new([
567            Bytes::from_owner(first),
568            Bytes::from_owner(boundary),
569            Bytes::from_owner(last),
570        ]);
571
572        let prefix = segments.split_to(4).unwrap();
573        assert_eq!(prefix.to_bytes().as_ref(), b"abcd");
574        assert!(first_owner.upgrade().is_some());
575
576        drop(prefix);
577
578        assert!(first_owner.upgrade().is_none());
579        assert!(boundary_owner.upgrade().is_some());
580        assert!(last_owner.upgrade().is_some());
581        assert_eq!(segments.to_bytes().as_ref(), b"efghi");
582
583        drop(segments);
584
585        assert!(boundary_owner.upgrade().is_none());
586        assert!(last_owner.upgrade().is_none());
587    }
588
589    #[test]
590    fn segments_views_ignore_consumed_segments() {
591        let mut segments = Segments::new([
592            Bytes::from_static(b"ab"),
593            Bytes::from_static(b"cd"),
594            Bytes::from_static(b"ef"),
595        ]);
596        drop(segments.split_to(3).unwrap());
597        let expected = [Bytes::from_static(b"d"), Bytes::from_static(b"ef")];
598
599        assert_eq!(segments.len(), 3);
600        assert!(!segments.is_empty());
601        assert_eq!(segments.segment_count(), 2);
602        assert_eq!(segments.as_slice(), &expected);
603        assert!(segments.iter().eq(expected.iter()));
604        assert_eq!(segments.to_bytes().as_ref(), b"def");
605
606        let mut cursor = segments.as_buf();
607        let mut bytes = [0; 3];
608        cursor.copy_to_slice(&mut bytes);
609        assert_eq!(&bytes, b"def");
610        assert_eq!(cursor.remaining(), 0);
611
612        let cloned = segments.clone();
613        assert_eq!(cloned.head, 0);
614        assert_eq!(cloned.chunks.len(), 2);
615        assert_eq!(cloned.into_bytes().as_ref(), b"def");
616        assert_eq!(segments.into_chunks(), expected);
617    }
618
619    #[test]
620    fn segments_into_bytes_reuses_single_segment() {
621        let segment = Bytes::from(vec![1, 2, 3, 4]);
622        let ptr = segment.as_ptr();
623
624        let collected = Segments::single(segment).into_bytes();
625
626        assert_eq!(collected.as_ptr(), ptr);
627        assert_eq!(collected.as_ref(), &[1, 2, 3, 4]);
628    }
629
630    #[test]
631    fn segments_into_bytes_reuses_remaining_segment() {
632        let segment = Bytes::from(vec![1, 2, 3, 4]);
633        let ptr = segment.as_ptr();
634        let mut segments = Segments::new([Bytes::from_static(b"prefix"), segment]);
635        drop(segments.split_to(6).unwrap());
636
637        assert_eq!(segments.to_bytes().as_ptr(), ptr);
638
639        let collected = segments.into_bytes();
640
641        assert_eq!(collected.as_ptr(), ptr);
642        assert_eq!(collected.as_ref(), &[1, 2, 3, 4]);
643    }
644
645    #[test]
646    fn segments_into_chunks_preserves_segment_storage() {
647        let first = Bytes::from(vec![1, 2]);
648        let second = Bytes::from(vec![3, 4]);
649        let first_ptr = first.as_ptr();
650        let second_ptr = second.as_ptr();
651
652        let chunks = Segments::new([first, second]).into_chunks();
653
654        assert_eq!(chunks.len(), 2);
655        assert_eq!(chunks[0].as_ptr(), first_ptr);
656        assert_eq!(chunks[1].as_ptr(), second_ptr);
657    }
658
659    #[test]
660    fn segments_append_keeps_small_payloads_inline() {
661        let chunks = [
662            Bytes::from(vec![1]),
663            Bytes::from(vec![2]),
664            Bytes::from(vec![3]),
665            Bytes::from(vec![4]),
666        ];
667        let ptrs = chunks.each_ref().map(|chunk| chunk.as_ptr());
668        let [first, second, third, fourth] = chunks;
669        let mut segments = Segments::new([first, second]);
670
671        // Four segments fit in the inline storage.
672        segments.append(Segments::new([third, fourth]));
673        assert!(!segments.chunks.spilled());
674        assert_eq!(segments.len(), 4);
675        assert_eq!(segments.segment_count(), 4);
676        assert_eq!(segments.to_bytes().as_ref(), &[1, 2, 3, 4]);
677        for (segment, ptr) in segments.iter().zip(ptrs) {
678            assert_eq!(segment.as_ptr(), ptr);
679        }
680    }
681
682    #[test]
683    fn segments_append_spills_in_order() {
684        let mut segments = Segments::new((0..4).map(|byte| Bytes::from(vec![byte])));
685        let last = Bytes::from(vec![4]);
686        let ptr = last.as_ptr();
687        assert!(!segments.chunks.spilled());
688
689        // The fifth segment requires heap storage for the segment list.
690        segments.append(Segments::single(last));
691        assert!(segments.chunks.spilled());
692        assert_eq!(segments.len(), 5);
693        assert_eq!(segments.segment_count(), 5);
694        assert_eq!(segments.to_bytes().as_ref(), &[0, 1, 2, 3, 4]);
695        assert_eq!(segments.as_slice()[4].as_ptr(), ptr);
696    }
697
698    #[test]
699    fn segments_append_to_empty() {
700        let bytes = Bytes::from(vec![1, 2, 3]);
701        let ptr = bytes.as_ptr();
702        let mut segments = Segments::default();
703
704        segments.append(Segments::single(bytes));
705
706        assert_eq!(segments.len(), 3);
707        assert_eq!(segments.segment_count(), 1);
708        assert_eq!(segments.as_slice()[0].as_ptr(), ptr);
709        assert_eq!(segments.as_slice()[0].as_ref(), &[1, 2, 3]);
710    }
711
712    #[test]
713    fn segments_append_empty_payload() {
714        let bytes = Bytes::from(vec![1, 2, 3]);
715        let ptr = bytes.as_ptr();
716        let mut segments = Segments::single(bytes);
717
718        segments.append(Segments::default());
719
720        assert_eq!(segments.len(), 3);
721        assert_eq!(segments.segment_count(), 1);
722        assert_eq!(segments.as_slice()[0].as_ptr(), ptr);
723        assert_eq!(segments.as_slice()[0].as_ref(), &[1, 2, 3]);
724    }
725
726    #[test]
727    fn segments_append_compacts_consumed_slots() {
728        let mut segments = Segments::new([
729            Bytes::from_static(b"a"),
730            Bytes::from_static(b"b"),
731            Bytes::from_static(b"c"),
732            Bytes::from_static(b"d"),
733        ]);
734
735        let mut other = Segments::new([
736            Bytes::from_static(b"x"),
737            Bytes::from_static(b"y"),
738            Bytes::from_static(b"z"),
739        ]);
740
741        drop(segments.split_to(2).unwrap());
742        drop(other.split_to(1).unwrap());
743
744        segments.append(other);
745
746        assert!(!segments.chunks.spilled());
747        assert_eq!(segments.head, 0);
748        assert_eq!(segments.segment_count(), 4);
749        assert_eq!(segments.to_bytes().as_ref(), b"cdyz");
750    }
751
752    #[test]
753    fn segments_append_preserves_owner_lifetime() {
754        let storage: Arc<[u8]> = Arc::from(&b"data"[..]);
755        let owner = Arc::downgrade(&storage);
756        let mut segments = Segments::single(Bytes::from_static(b"header"));
757
758        // The appended segment becomes the only owner of this storage.
759        segments.append(Segments::single(Bytes::from_owner(storage)));
760        assert_eq!(owner.strong_count(), 1);
761        assert_eq!(segments.to_bytes().as_ref(), b"headerdata");
762
763        drop(segments);
764        assert!(owner.upgrade().is_none());
765    }
766}