data 字段的编码

pub struct BytesMut {
    ptr: NonNull<u8>,
    len: usize,
    cap: usize,
    data: *mut Shared,
}

// Buffer storage strategy flags.
const KIND_ARC: usize = 0b0;
const KIND_VEC: usize = 0b1;
const KIND_MASK: usize = 0b1;

    #[inline]
    fn kind(&self) -> usize {
        self.data as usize & KIND_MASK
    }

struct Shared {
    vec: Vec<u8>,
    original_capacity_repr: usize,
    ref_count: AtomicUsize,
}

// Assert that the alignment of `Shared` is divisible by 2.
// This is a necessary invariant since we depend on allocating `Shared` a
// shared object to implicitly carry the `KIND_ARC` flag in its pointer.
// This flag is set when the LSB is 0.
const _: [(); 0 - mem::align_of::<Shared>() % 2] = []; // Assert that the alignment of `Shared` is divisible by 2.

// The max original capacity value. Any `Bytes` allocated with a greater initial
// capacity will default to this.
const MAX_ORIGINAL_CAPACITY_WIDTH: usize = 17;
// The original capacity algorithm will not take effect unless the originally
// allocated capacity was at least 1kb in size.
const MIN_ORIGINAL_CAPACITY_WIDTH: usize = 10;
// The original capacity is stored in powers of 2 starting at 1kb to a max of
// 64kb. Representing it as such requires only 3 bits of storage.
const ORIGINAL_CAPACITY_MASK: usize = 0b11100;
const ORIGINAL_CAPACITY_OFFSET: usize = 2;

const VEC_POS_OFFSET: usize = 5;
// When the storage is in the `Vec` representation, the pointer can be advanced
// at most this value. This is due to the amount of storage available to track
// the offset is usize - number of KIND bits and number of ORIGINAL_CAPACITY
// bits.
const MAX_VEC_POS: usize = usize::MAX >> VEC_POS_OFFSET;
const NOT_VEC_POS_MASK: usize = 0b11111;

#[inline]
fn original_capacity_to_repr(cap: usize) -> usize {
    let width = PTR_WIDTH - ((cap >> MIN_ORIGINAL_CAPACITY_WIDTH).leading_zeros() as usize);
    cmp::min(
        width,
        MAX_ORIGINAL_CAPACITY_WIDTH - MIN_ORIGINAL_CAPACITY_WIDTH,
    )
}

fn original_capacity_from_repr(repr: usize) -> usize {
    if repr == 0 {
        return 0;
    }

    1 << (repr + (MIN_ORIGINAL_CAPACITY_WIDTH - 1))
}

#[cfg(target_pointer_width = "64")]
const PTR_WIDTH: usize = 64;
#[cfg(target_pointer_width = "32")]
const PTR_WIDTH: usize = 32;

    #[inline]
    pub(crate) fn from_vec(vec: Vec<u8>) -> BytesMut {
        let mut vec = ManuallyDrop::new(vec);
        let ptr = vptr(vec.as_mut_ptr());
        let len = vec.len();
        let cap = vec.capacity();

        let original_capacity_repr = original_capacity_to_repr(cap);
        let data = (original_capacity_repr << ORIGINAL_CAPACITY_OFFSET) | KIND_VEC;

        BytesMut {
            ptr,
            len,
            cap,
            data: invalid_ptr(data),
        }
    }

    #[inline]
    unsafe fn get_vec_pos(&self) -> usize {
        debug_assert_eq!(self.kind(), KIND_VEC);

        self.data as usize >> VEC_POS_OFFSET
    }

    #[inline]
    unsafe fn set_vec_pos(&mut self, pos: usize) {
        debug_assert_eq!(self.kind(), KIND_VEC);
        debug_assert!(pos <= MAX_VEC_POS);

        self.data = invalid_ptr((pos << VEC_POS_OFFSET) | (self.data as usize & NOT_VEC_POS_MASK));
    }

unsafe fn rebuild_vec(ptr: *mut u8, mut len: usize, mut cap: usize, off: usize) -> Vec<u8> {
    let ptr = ptr.sub(off);
    len += off;
    cap += off;

    Vec::from_raw_parts(ptr, len, cap)
}

    pub(crate) unsafe fn advance_unchecked(&mut self, count: usize) {
        // Setting the start to 0 is a no-op, so return early if this is the
        // case.
        if count == 0 {
            return;
        }

        debug_assert!(count <= self.cap, "internal: set_start out of bounds");

        let kind = self.kind();

        if kind == KIND_VEC {
            // ...
            let pos = self.get_vec_pos() + count;

            if pos <= MAX_VEC_POS {
                self.set_vec_pos(pos);
            } else {
                // The repr must be upgraded to ARC. This will never happen
                // on 64 bit systems and will only happen on 32 bit systems
                // when shifting past 134,217,727 bytes. As such, we don't
                // worry too much about performance here.
                self.promote_to_shared(/*ref_count = */ 1);
            }
        }

        // Updating the start of the view is setting `ptr` to point to the
        // new start and updating the `len` field to reflect the new length
        // of the view.
        self.ptr = vptr(self.ptr.as_ptr().add(count));
        self.len = self.len.saturating_sub(count);
        self.cap -= count;
    }

    unsafe fn promote_to_shared(&mut self, ref_cnt: usize) {
        debug_assert_eq!(self.kind(), KIND_VEC);
        debug_assert!(ref_cnt == 1 || ref_cnt == 2);

        let original_capacity_repr =
            (self.data as usize & ORIGINAL_CAPACITY_MASK) >> ORIGINAL_CAPACITY_OFFSET;

        // The vec offset cannot be concurrently mutated, so there
        // should be no danger reading it.
        let off = (self.data as usize) >> VEC_POS_OFFSET;

        // ...
        // Explicitly allocate before invoking rebuild_vec() so that
        // the vector is not dropped if Box::new() panics.
        let shared = Box::new(MaybeUninit::<Shared>::uninit());
        let shared = Shared::init_to_raw(
            shared,
            Shared {
                vec: rebuild_vec(self.ptr.as_ptr(), self.len, self.cap, off),
                original_capacity_repr,
                ref_count: AtomicUsize::new(ref_cnt),
            },
        );

        // The pointer should be aligned, so this assert should
        // always succeed.
        debug_assert_eq!(shared as usize & KIND_MASK, KIND_ARC);

        self.data = shared;
    }

        let data = (original_capacity_repr << ORIGINAL_CAPACITY_OFFSET) | KIND_VEC;
        self.data = invalid_ptr(data);

bytes = "=1.12.1"

use std::mem::size_of;

use bytes::{BufMut, Bytes, BytesMut};

// ---- 只用于观察：把 BytesMut / Bytes 当成 4 个 usize 读（依赖私有布局）----
pub struct Layout4 {
  ptr: usize,
  len: usize,
  cap: usize,
  data: usize,
}

fn words_mut(b: &BytesMut) -> [usize; 4] {
  assert_eq!(size_of::<[usize; 4]>(), size_of::<BytesMut>());
  unsafe { *(b as *const BytesMut as *const [usize; 4]) }
}

pub fn words_bytes(b: &Bytes) -> [usize; 4] {
  assert_eq!(size_of::<[usize; 4]>(), size_of::<Bytes>());
  unsafe { *(b as *const Bytes as *const [usize; 4]) }
}

pub fn locate() -> Layout4 {
  let mut b = BytesMut::with_capacity(3000);
  b.put_slice(b"hello");
  let w = words_mut(&b);
  let ptr = w.iter().position(|&x| x == b.as_ptr() as usize).unwrap();
  let len = w.iter().position(|&x| x == b.len()).unwrap();
  let cap = w.iter().position(|&x| x == b.capacity()).unwrap();
  let data = (0..4).find(|&i| i != ptr && i != len && i != cap).unwrap();
  Layout4 { ptr, len, cap, data }
}

pub fn data_of(l: &Layout4, b: &BytesMut) -> usize {
  let w = words_mut(b);
  assert_eq!(w[l.ptr], b.as_ptr() as usize);
  assert_eq!(w[l.len], b.len());
  assert_eq!(w[l.cap], b.capacity());
  w[l.data]
}

// 照 bytes_mut.rs 的常量拆 data
pub fn decode(d: usize) -> String {
  if d & 1 == 1 {
    let bit1 = (d >> 1) & 1;
    let repr = (d & 0b11100) >> 2;
    let pos = d >> 5;
    format!("KIND_VEC bit1={bit1} repr={repr} pos={pos}")
  } else {
    format!("KIND_ARC Shared 指针 (d & 0b111 = {})", d & 0b111)
  }
}

// 低位用二进制打出来；KIND_ARC 时是真地址，每次运行不同，只打低 3 位
pub fn show(d: usize) -> String {
  if d & 1 == 1 { format!("{d:#b}") } else { format!("...{:03b}", d & 0b111) }
}

use bytes::{Buf, BufMut, BytesMut};

#[path = "../mirror.rs"]
mod mirror;
use mirror::*;

// 照抄 original_capacity_from_repr 的公式，只用来和观察值对照
fn from_repr(repr: usize) -> usize {
  if repr == 0 { 0 } else { 1 << (repr + 9) }
}

fn main() {
  let l = locate();

  println!("== 1. with_capacity(n) 之后的 data，以及共享路径 reserve 用到的原始容量");
  for n in [0usize, 1, 1023, 1024, 1500, 2047, 2048, 3000, 4096, 8192, 65535, 65536, 131072, 1 << 20] {
    let mut b = BytesMut::with_capacity(n);
    let d = data_of(&l, &b);
    let repr = (d & 0b11100) >> 2;
    // 填满、整段切走并留着，b 变成 KIND_ARC 且不唯一；
    // 这时 reserve(1) 只能另分配 max(0 + 1, 原始容量)
    let c = b.capacity();
    b.put_bytes(0, c);
    let keep = b.split_to(c);
    b.reserve(1);
    println!(
      "n={n:<8} data={:<10} repr={repr} 公式还原={:<6} 共享后 reserve(1) 得到 cap={}",
      show(d),
      from_repr(repr),
      b.capacity()
    );
    drop(keep);
  }

  println!();
  println!("== 2. 一块 8192 字节缓冲的一串操作");
  let mut b = BytesMut::with_capacity(8192);
  let base = b.as_ptr() as usize;
  b.put_slice(&[7u8; 100]);
  let d = data_of(&l, &b);
  println!("put_slice(100)    data={:<16} {}  ptr=base+{} len={} cap={}", show(d), decode(d), b.as_ptr() as usize - base, b.len(), b.capacity());
  b.advance(10);
  let d = data_of(&l, &b);
  println!("advance(10)       data={:<16} {}  ptr=base+{} len={} cap={}", show(d), decode(d), b.as_ptr() as usize - base, b.len(), b.capacity());
  b.advance(20);
  let d = data_of(&l, &b);
  println!("advance(20)       data={:<16} {}  ptr=base+{} len={} cap={}", show(d), decode(d), b.as_ptr() as usize - base, b.len(), b.capacity());

  let (a0, s0) = allocs();
  let head = b.split_to(20);
  let (a1, s1) = allocs();
  let dh = data_of(&l, &head);
  let db = data_of(&l, &b);
  println!("split_to(20)      alloc+{} ({}B)  head: {}  b: {}  同一个 Shared={}", a1 - a0, s1 - s0, decode(dh), decode(db), dh == db);
  println!("                  head: ptr=base+{} len={} cap={} | b: ptr=base+{} len={} cap={}",
    head.as_ptr() as usize - base, head.len(), head.capacity(), b.as_ptr() as usize - base, b.len(), b.capacity());

  let (a0, _) = allocs();
  let head = head.freeze();
  let (a1, _) = allocs();
  let w = words_bytes(&head);
  println!("head.freeze()     alloc+{}  Bytes 的 4 个字里有原来的 Shared 指针={}  ptr=base+{} len={}",
    a1 - a0, w.contains(&dh), head.as_ptr() as usize - base, head.len());

  let (a0, s0) = allocs();
  b.reserve(10000);
  let (a1, s1) = allocs();
  let d = data_of(&l, &b);
  println!("b.reserve(10000)  alloc+{} ({}B)  data={} {}  ptr 在原缓冲内={} len={} cap={}",
    a1 - a0, s1 - s0, show(d), decode(d), (b.as_ptr() as usize).wrapping_sub(base) < 8192, b.len(), b.capacity());
  drop(head);

  println!();
  println!("== 3. KIND_VEC 带偏移的 freeze");
  let mut v = BytesMut::with_capacity(8192);
  let base = v.as_ptr() as usize;
  v.put_slice(&[7u8; 100]);
  v.advance(10);
  let d = data_of(&l, &v);
  let (a0, s0) = allocs();
  let f = v.freeze();
  let (a1, s1) = allocs();
  println!("freeze 前 data={} {}", show(d), decode(d));
  println!("freeze 后 alloc+{} ({}B)  Bytes ptr=base+{} len={}", a1 - a0, s1 - s0, f.as_ptr() as usize - base, f.len());
  drop(f);

  println!();
  println!("== 4. 先 with_capacity(0) 再 reserve，和直接 with_capacity");
  for (label, mut b) in [
    ("with_capacity(0)+reserve(65536)", {
      let mut b = BytesMut::with_capacity(0);
      b.reserve(65536);
      b
    }),
    ("with_capacity(65536)", BytesMut::with_capacity(65536)),
  ] {
    let d = data_of(&l, &b);
    let c = b.capacity();
    b.put_bytes(0, c);
    let keep = b.split_to(c);
    b.reserve(10);
    println!("{label:<32} cap={c} data={:<10} {}  切走全部后 reserve(10) cap={}", show(d), decode(d), b.capacity());
    drop(keep);
  }
}

== 1. with_capacity(n) 之后的 data，以及共享路径 reserve 用到的原始容量
n=0        data=0b1        repr=0 公式还原=0      共享后 reserve(1) 得到 cap=1
n=1        data=0b1        repr=0 公式还原=0      共享后 reserve(1) 得到 cap=1
n=1023     data=0b1        repr=0 公式还原=0      共享后 reserve(1) 得到 cap=1
n=1024     data=0b101      repr=1 公式还原=1024   共享后 reserve(1) 得到 cap=1024
n=1500     data=0b101      repr=1 公式还原=1024   共享后 reserve(1) 得到 cap=1024
n=2047     data=0b101      repr=1 公式还原=1024   共享后 reserve(1) 得到 cap=1024
n=2048     data=0b1001     repr=2 公式还原=2048   共享后 reserve(1) 得到 cap=2048
n=3000     data=0b1001     repr=2 公式还原=2048   共享后 reserve(1) 得到 cap=2048
n=4096     data=0b1101     repr=3 公式还原=4096   共享后 reserve(1) 得到 cap=4096
n=8192     data=0b10001    repr=4 公式还原=8192   共享后 reserve(1) 得到 cap=8192
n=65535    data=0b11001    repr=6 公式还原=32768  共享后 reserve(1) 得到 cap=32768
n=65536    data=0b11101    repr=7 公式还原=65536  共享后 reserve(1) 得到 cap=65536
n=131072   data=0b11101    repr=7 公式还原=65536  共享后 reserve(1) 得到 cap=65536
n=1048576  data=0b11101    repr=7 公式还原=65536  共享后 reserve(1) 得到 cap=65536

== 2. 一块 8192 字节缓冲的一串操作
put_slice(100)    data=0b10001          KIND_VEC bit1=0 repr=4 pos=0  ptr=base+0 len=100 cap=8192
advance(10)       data=0b101010001      KIND_VEC bit1=0 repr=4 pos=10  ptr=base+10 len=90 cap=8182
advance(20)       data=0b1111010001     KIND_VEC bit1=0 repr=4 pos=30  ptr=base+30 len=70 cap=8162
split_to(20)      alloc+1 (40B)  head: KIND_ARC Shared 指针 (d & 0b111 = 0)  b: KIND_ARC Shared 指针 (d & 0b111 = 0)  同一个 Shared=true
                  head: ptr=base+30 len=20 cap=20 | b: ptr=base+50 len=50 cap=8142
head.freeze()     alloc+0  Bytes 的 4 个字里有原来的 Shared 指针=true  ptr=base+30 len=20
b.reserve(10000)  alloc+1 (10050B)  data=0b10001 KIND_VEC bit1=0 repr=4 pos=0  ptr 在原缓冲内=false len=50 cap=10050

== 3. KIND_VEC 带偏移的 freeze
freeze 前 data=0b101010001 KIND_VEC bit1=0 repr=4 pos=10
freeze 后 alloc+1 (24B)  Bytes ptr=base+10 len=90

== 4. 先 with_capacity(0) 再 reserve，和直接 with_capacity
with_capacity(0)+reserve(65536)  cap=65536 data=0b1        KIND_VEC bit1=0 repr=0 pos=0  切走全部后 reserve(10) cap=10
with_capacity(65536)             cap=65536 data=0b11101    KIND_VEC bit1=0 repr=7 pos=0  切走全部后 reserve(10) cap=65536

use std::fmt::Write;

use bytes::{Buf, BytesMut};

#[path = "../mirror.rs"]
mod mirror;
use mirror::*;

fn main() {
  // 输出先攒在 String 里，最后一次打印
  let mut out = String::with_capacity(4096);
  let l = locate();
  let max_vec_pos = usize::MAX >> 5; // MAX_VEC_POS
  writeln!(out, "usize = {} 位, MAX_VEC_POS = {max_vec_pos}", usize::BITS).unwrap();
  if usize::BITS == 32 {
    // 分配 MAX_VEC_POS + 2 字节，先前进到 MAX_VEC_POS，再前进 1
    let mut b = BytesMut::zeroed(max_vec_pos + 2);
    let d = data_of(&l, &b);
    writeln!(out, "zeroed({})          data={} {}", max_vec_pos + 2, show(d), decode(d)).unwrap();
    b.advance(max_vec_pos);
    let d = data_of(&l, &b);
    writeln!(out, "advance(MAX_VEC_POS)  data={:#x} {}  len={}", d, decode(d), b.len()).unwrap();
    let (a0, s0) = allocs();
    b.advance(1);
    let (a1, s1) = allocs();
    let d = data_of(&l, &b);
    writeln!(out, "advance(1)            alloc+{} ({}B) {}  len={}", a1 - a0, s1 - s0, decode(d), b.len()).unwrap();
  } else {
    writeln!(out, "64 位上偏移要超过 {max_vec_pos} 字节才会走提升这条路，跳过").unwrap();
  }
  print!("{out}");
}

usize = 64 位, MAX_VEC_POS = 576460752303423487
64 位上偏移要超过 576460752303423487 字节才会走提升这条路，跳过

usize = 32 位, MAX_VEC_POS = 134217727
zeroed(134217729)          data=0b11101 KIND_VEC bit1=0 repr=7 pos=0
advance(MAX_VEC_POS)  data=0xfffffffd KIND_VEC bit1=0 repr=7 pos=134217727  len=2
advance(1)            alloc+1 (20B) KIND_ARC Shared 指针 (d & 0b111 = 0)  len=1

data=0x509 (KIND_VEC bit1=0 repr=2 pos=40) len=60 cap=2960
split_to(0): alloc+1 (40B) KIND_ARC Shared 指针 (d & 0b111 = 0)