What is the difference between `bytes::BytesMut::freeze` and `split` for converting mutable buffers to immutable?

freeze converts an entire BytesMut buffer into an immutable Bytes by consuming it, making the data read-only and shareable through reference counting, while split divides a BytesMut into two separate BytesMut buffers at a given position without changing mutability—both resulting buffers remain mutable. The key distinction is that freeze is about transitioning from mutable to immutable, while split is about dividing a buffer into smaller mutable pieces, and they serve fundamentally different purposes: freeze for finalizing data, split for buffer management.

Basic freeze Behavior

use bytes::{Bytes, BytesMut};
 
fn freeze_example() {
    // freeze converts BytesMut -> Bytes (mutable -> immutable)
    let mut buffer = BytesMut::with_capacity(100);
    buffer.extend_from_slice(b"Hello, World!");
    
    // buffer is mutable
    buffer.extend_from_slice(b" More data.");
    
    // freeze consumes the BytesMut and returns immutable Bytes
    let frozen: Bytes = buffer.freeze();
    
    // frozen is now immutable
    // Cannot modify frozen data
    
    // frozen can be cloned cheaply (reference counted)
    let frozen_clone = frozen.clone();
    
    // Both point to the same underlying data
    assert_eq!(&frozen[..], &frozen_clone[..]);
    
    // buffer is consumed, cannot be used anymore
    // let _ = buffer; // Error: buffer moved
    
    println!("Frozen data: {:?}", frozen);
}

freeze consumes the BytesMut and produces an immutable Bytes that can be cheaply cloned.

Basic split Behavior

use bytes::BytesMut;
 
fn split_example() {
    // split divides BytesMut into two at a position
    let mut buffer = BytesMut::from("Hello, World!");
    
    // Split at position 7
    let (left, right) = buffer.split_at(7);
    
    // Both left and right are still BytesMut (mutable)
    // left = "Hello, "
    // right = "World!"
    
    assert_eq!(&left[..], b"Hello, ");
    assert_eq!(&right[..], b"World!");
    
    // Both remain mutable
    // Can continue appending to right
    // (left is dropped or used separately)
    
    // Original buffer is consumed
    // Cannot use buffer after split
    
    // split_to is a variant that returns only one side
    let mut buffer = BytesMut::from("Hello, World!");
    let prefix = buffer.split_to(7);
    
    assert_eq!(&prefix[..], b"Hello, ");
    assert_eq!(&buffer[..], b"World!");
    
    // prefix is the front part, buffer is the remaining part
    // Both are still BytesMut
}

split divides a BytesMut into two BytesMut values, preserving mutability.

Memory Sharing After Freeze

use bytes::{Bytes, BytesMut};
 
fn freeze_memory_sharing() {
    let mut buffer = BytesMut::from("Hello, World!");
    
    // freeze creates a reference-counted immutable buffer
    let frozen: Bytes = buffer.freeze();
    
    // Cloning frozen is O(1) - reference count increment
    let clone1 = frozen.clone();
    let clone2 = frozen.clone();
    
    // All three Bytes share the same underlying data
    // No copying of actual bytes
    
    // Memory layout:
    // [Reference Count] -> [Data: "Hello, World!"]
    //                      ^
    // frozen ----/--------/
    // clone1 ----|--------/
    // clone2 ----+--------/
    
    // When all references are dropped, data is deallocated
    drop(frozen);
    drop(clone1);
    // Data still exists (clone2 holds reference)
    drop(clone2);
    // Now data is deallocated
    
    // freeze is ideal for:
    // - Sharing data across threads
    // - Sending through channels
    // - Returning from functions
}

freeze creates a reference-counted handle, enabling cheap cloning and safe sharing.

Memory After Split

use bytes::BytesMut;
 
fn split_memory_layout() {
    let mut buffer = BytesMut::from("Hello, World!");
    
    // split_to moves bytes from one buffer to another
    let prefix = buffer.split_to(7);
    
    // After split_to:
    // - prefix owns bytes 0..7
    // - buffer owns bytes 7..13
    // - No sharing between them
    
    assert_eq!(&prefix[..], b"Hello, ");
    assert_eq!(&buffer[..], b"World!");
    
    // This is NOT reference counting
    // Each buffer owns its portion independently
    
    // For split_at (returns both sides):
    let mut buffer2 = BytesMut::from("Hello, World!");
    let (left, right) = buffer2.split_at(7);
    
    // left and right are independent
    // No reference counting involved
    
    // Memory layout after split:
    // Original contiguous buffer is now logically two buffers
    // Implementation may or may not involve actual copying
    // (BytesMut uses a kind of reference counting internally)
    
    // Key difference from freeze:
    // - split: produces mutable BytesMut values
    // - freeze: produces immutable Bytes
}

split creates independent mutable buffers; no reference counting for immutability.

Combining Freeze and Split

use bytes::{Bytes, BytesMut};
 
fn freeze_after_split() {
    // Common pattern: split buffer, then freeze
    
    let mut buffer = BytesMut::from("HEADER:body content");
    
    // Split into header and body
    let header = buffer.split_to(7);  // "HEADER:"
    // buffer now contains "body content"
    
    // Freeze both parts for sharing
    let header_bytes: Bytes = header.freeze();
    let body_bytes: Bytes = buffer.freeze();
    
    // Both are now immutable and shareable
    let header_clone = header_bytes.clone();
    let body_clone = body_bytes.clone();
    
    // Each can be sent to different consumers
    // process_header(header_bytes);
    // process_body(body_bytes);
    
    assert_eq!(&header_bytes[..], b"HEADER:");
    assert_eq!(&body_bytes[..], b"body content");
}

Combine split_to followed by freeze to create independent immutable buffers from parts.

Splitting vs Freezing Semantics

use bytes::{Bytes, BytesMut};
 
fn semantics_comparison() {
    // freeze: Mutability transition
    // Purpose: Make data read-only and shareable
    
    let mut buffer = BytesMut::from("data");
    let frozen: Bytes = buffer.freeze();
    // buffer -> frozen
    // BytesMut -> Bytes
    // Mutable -> Immutable
    // Consumed -> Produced
    
    // split: Buffer division
    // Purpose: Divide buffer into parts
    
    let mut buffer = BytesMut::from("Hello, World!");
    let (left, right) = buffer.split_at(7);
    // buffer -> (left, right)
    // BytesMut -> (BytesMut, BytesMut)
    // One buffer -> Two buffers
    // Mutable -> Mutable
    
    // Key semantic differences:
    // 1. freeze changes mutability, split does not
    // 2. freeze is for finalizing, split is for managing
    // 3. freeze produces Bytes, split produces BytesMut
    // 4. freeze is O(1) for the whole buffer
    //    split_at is O(1) but may involve ref counting
    
    // Use freeze when:
    // - Data is complete and ready to share
    // - You need immutable, clonable handle
    // - Sending across threads or channels
    
    // Use split when:
    // - You need to process parts separately
    // - Buffer contains multiple logical sections
    // - Still building/modifying the data
}

freeze transitions mutability; split divides the buffer while preserving mutability.

Reserving Capacity and Splitting

use bytes::BytesMut;
 
fn capacity_and_split() {
    // BytesMut manages capacity for efficient growth
    
    let mut buffer = BytesMut::with_capacity(100);
    buffer.extend_from_slice(b"Hello");
    
    println!("Len: {}, Capacity: {}", buffer.len(), buffer.capacity());
    // Len: 5, Capacity: 100
    
    // split_to can use reserved capacity
    let prefix = buffer.split_to(3);  // "Hel"
    
    // prefix has "Hel" and its own capacity management
    // buffer has "lo" and remaining capacity
    
    // After split:
    // - Both buffers can grow independently
    // - Reserved capacity is divided or reassigned
    
    buffer.extend_from_slice(b", World!");
    // buffer can grow if capacity allows
    
    // Split operations work with capacity:
    // - split_at(n): Split at position n
    // - split_to(n): Split off first n bytes, rest remains
    // - split_off(n): Split off bytes after n, first part remains
    
    let mut buffer2 = BytesMut::from("Hello, World!");
    let suffix = buffer2.split_off(7);
    
    assert_eq!(&buffer2[..], b"Hello, ");  // Original has first part
    assert_eq!(&suffix[..], b"World!");    // suffix has rest
}

Split operations work with buffer capacity, allowing subsequent growth of each part.

Freeze for Network Protocols

use bytes::{Bytes, BytesMut, Buf, BufMut};
 
fn network_protocol_example() {
    // Common pattern: Build response in BytesMut, freeze to send
    
    fn build_response(status: u16, body: &[u8]) -> Bytes {
        let mut buffer = BytesMut::new();
        
        // Build response headers
        buffer.put_slice(b"HTTP/1.1 ");
        buffer.put_slice(status.to_string().as_bytes());
        buffer.put_slice(b" OK\r\n");
        buffer.put_slice(b"Content-Length: ");
        buffer.put_slice(body.len().to_string().as_bytes());
        buffer.put_slice(b"\r\n\r\n");
        
        // Add body
        buffer.put_slice(body);
        
        // Freeze to send over network
        buffer.freeze()
    }
    
    let response = build_response(200, b"Hello, World!");
    
    // response is now immutable Bytes
    // Can be sent through channels, cloned for logging, etc.
    
    // Multiple consumers can share the same data
    let for_network = response.clone();
    let for_logging = response.clone();
    let for_metrics = response.clone();
    
    // All reference the same underlying bytes
    // No copying of actual data
}

freeze is essential for network protocols where built data becomes read-only for transmission.

Buffer Pooling Pattern

use bytes::BytesMut;
 
fn buffer_pooling() {
    // BytesMut is often used with pooling for allocation reuse
    
    // Acquire buffer from pool (conceptual)
    fn get_buffer() -> BytesMut {
        BytesMut::with_capacity(1024)
    }
    
    // Return buffer to pool after use
    fn process_message(data: &[u8]) -> BytesMut {
        let mut buffer = get_buffer();
        
        // Process and build response
        buffer.extend_from_slice(b"Response: ");
        buffer.extend_from_slice(data);
        
        buffer
    }
    
    // Pattern 1: Freeze and return to pool
    let mut buffer = process_message(b"test");
    let frozen = buffer.freeze();
    // buffer is consumed, frozen is sent
    
    // Pattern 2: Split, use one part, keep other
    let mut buffer = BytesMut::from("header:body");
    let header = buffer.split_to(7);
    // Use header, continue using buffer for body
    
    // freeze prevents further modification
    // split allows continuing modification
    
    // Choose based on:
    // - Is data complete? -> freeze
    // - Need to process parts separately? -> split
}

Use freeze when data is complete; use split when processing continues on parts.

Advanced BytesMut Internals

use bytes::{Bytes, BytesMut};
 
fn internals() {
    // BytesMut uses reference counting internally
    // This enables efficient split operations
    
    let mut buffer = BytesMut::from("Hello, World!");
    
    // Clone before split (shows ref counting)
    let cloned = buffer.clone();
    
    // buffer and cloned share data initially
    // (Copy-on-write semantics)
    
    // After modification:
    buffer.extend_from_slice(b"!");
    // buffer may have been copied if cloned still exists
    
    // freeze leverages this reference counting:
    let mut buffer2 = BytesMut::from("data");
    let bytes = buffer2.freeze();
    
    // bytes is now a reference-counted handle
    // The underlying allocation is shared
    
    // Multiple clones of bytes share data:
    let b1 = bytes.clone();
    let b2 = bytes.clone();
    let b3 = bytes.clone();
    
    // All reference the same allocation
    // O(1) cloning, zero copying
    
    // split_to also uses reference counting:
    let mut buffer3 = BytesMut::from("Hello, World!");
    let prefix = buffer3.split_to(5);
    
    // Both prefix and buffer3 reference the original allocation
    // But are logically separate buffers
    // Modifications may trigger copying
}

Both freeze and split leverage internal reference counting for efficiency, but with different mutability outcomes.

When to Use Each

use bytes::{Bytes, BytesMut};
 
fn usage_guidelines() {
    // Use freeze when:
    // 1. Data is complete and ready to be shared
    // 2. You need an immutable handle (Bytes)
    // 3. Sending data across threads/channels
    // 4. Returning from function builder pattern
    // 5. Creating cheap clones of read-only data
    
    fn build_message(content: &str) -> Bytes {
        let mut buffer = BytesMut::new();
        buffer.extend_from_slice(content.as_bytes());
        buffer.freeze()  // Return immutable Bytes
    }
    
    // Use split when:
    // 1. Processing different parts of buffer separately
    // 2. Implementing framed protocols (length-prefixed)
    // 3. Need mutable buffers for each part
    // 4. Continuing to build on remaining buffer
    
    fn parse_framed(mut buffer: BytesMut) -> (BytesMut, BytesMut) {
        // Assume first 4 bytes are length prefix
        let len = u32::from_be_bytes([
            buffer[0], buffer[1], buffer[2], buffer[3]
        ]) as usize;
        
        let prefix = buffer.split_to(4);  // Length prefix
        let frame = buffer.split_to(len); // Frame content
        
        // Both prefix and frame are still BytesMut
        // Can continue processing
        
        (prefix, frame)
    }
    
    // Use split + freeze combination when:
    // 1. Need to split data and then share parts
    
    fn parse_and_share(mut buffer: BytesMut) -> (Bytes, Bytes) {
        let header = buffer.split_to(10).freeze();
        let body = buffer.freeze();
        (header, body)
    }
}

Choose freeze for finalizing data, split for dividing buffers that need further processing.

Comparison Summary

use bytes::{Bytes, BytesMut};
 
fn summary() {
    // freeze:
    // - Input: BytesMut
    // - Output: Bytes (immutable)
    // - Effect: Transitions mutability to immutable
    // - Use case: Finalizing data, sharing across threads
    // - Cloning: O(1) reference count increment
    // - Memory: Reference counted, shareable
    
    let mut buffer = BytesMut::from("data");
    let frozen: Bytes = buffer.freeze();
    
    // split_at:
    // - Input: BytesMut + position
    // - Output: (BytesMut, BytesMut)
    // - Effect: Divides buffer, preserves mutability
    // - Use case: Processing parts separately
    // - Cloning: Each part has its own reference
    // - Memory: Both parts reference original allocation
    
    let mut buffer = BytesMut::from("Hello, World!");
    let (left, right) = buffer.split_at(7);
    // left = "Hello, " (mutable)
    // right = "World!" (mutable)
    
    // split_to:
    // - Input: BytesMut + position
    // - Output: BytesMut (prefix), original modified
    // - Effect: Removes prefix from buffer
    // - Use case: Consuming framed messages
    
    let mut buffer = BytesMut::from("Hello, World!");
    let prefix = buffer.split_to(7);
    // prefix = "Hello, " (mutable)
    // buffer = "World!" (mutable)
    
    // Key distinction:
    // freeze: BytesMut -> Bytes (mutability change)
    // split: BytesMut -> (BytesMut, BytesMut) (division, same mutability)
}

Synthesis

Core difference:

// freeze: Transition from mutable to immutable
let bytes: Bytes = bytes_mut.freeze();
// BytesMut is consumed, Bytes is produced
// Data is now read-only and shareable
 
// split: Divide buffer while keeping mutability
let (left, right) = bytes_mut.split_at(n);
// Both left and right are BytesMut
// Can continue modifying both

Memory behavior:

// After freeze: Bytes is reference-counted
let b1 = frozen.clone();  // O(1), shares data
let b2 = frozen.clone();  // O(1), shares data
// All clones point to same underlying bytes
 
// After split: Both parts reference original allocation
let (left, right) = buffer.split_at(n);
// left and right are logically separate
// But may share underlying allocation initially
// Modifications may trigger copying

When to use:

Operation	When to use	Result
`freeze`	Data complete, need immutable handle	`Bytes`
`freeze`	Sharing across threads	`Bytes`
`freeze`	Sending through channels	`Bytes`
`split_at`	Processing parts separately	`(BytesMut, BytesMut)`
`split_to`	Consuming framed messages	`BytesMut` (prefix) + `BytesMut` (rest)
`split_off`	Extracting suffix	`BytesMut` (rest) + `BytesMut` (suffix)

Key insight: freeze and split serve fundamentally different purposes—freeze is about finalizing data, converting a BytesMut into an immutable Bytes that can be cheaply cloned and shared across threads, while split is about buffer management, dividing a BytesMut into smaller BytesMut pieces that remain mutable for continued processing. freeze consumes the entire buffer and produces a single immutable handle; split produces multiple mutable handles referencing portions of the original. Use freeze when you've finished building data and need to share it immutably; use split when you're still processing and need to handle different parts of the buffer independently. A common pattern combines both: split_to to separate a logical section, then freeze on each part to create shareable immutable references—this is how network protocols typically handle framing: split the message from the buffer, freeze the message for processing.

What is the difference between bytes::BytesMut::freeze and split for converting mutable buffers to immutable?