LRU Cache with Interior Mutability

Problem Statement

Implement a Least Recently Used (LRU) cache that tracks the most recently accessed items and evicts the least recently used item when capacity is reached. You’ll start with a simple single-threaded version, then progress to thread-safe variants.

Understanding Caches and the LRU Algorithm

What is a Cache?

A cache is a high-speed data storage layer that stores a subset of data, enabling faster retrieval than accessing the data from its primary storage location. Caches exploit the principle of locality: programs tend to access the same data repeatedly (temporal locality) and data stored near recently accessed data (spatial locality).

The fundamental trade-off:

• Speed vs Capacity: Caches are fast but small; primary storage is slow but large
• Memory hierarchy: CPU registers (fastest, ~1 cycle) → L1 cache (~4 cycles) → L2 cache (~12 cycles) → L3 cache (~40 cycles) → RAM (~100 cycles) → Disk (~10,000,000 cycles)

Real-world example:

#![allow(unused)]
fn main() {
// Without cache: Every request hits database (100ms each)
fn get_user_profile(id: u64) -> User {
    database.query("SELECT * FROM users WHERE id = ?", id)  // 100ms
}
// 1000 requests = 100 seconds total

// With cache: First request hits DB, subsequent hits cache (0.1ms)
fn get_user_profile_cached(id: u64) -> User {
    if let Some(user) = cache.get(id) {
        return user;  // 0.1ms - 1000x faster!
    }
    let user = database.query("SELECT * FROM users WHERE id = ?", id);
    cache.put(id, user.clone());
    user
}
// 1000 requests for same user = 100ms + 999 × 0.1ms = 200ms total
// Speedup: 500x faster
}

Cache Fundamentals

1. Cache Hit vs Cache Miss

Cache Hit: Requested data is found in the cache

• Benefit: Fast access (microseconds)
• Example: Browser loading an image already in cache

Cache Miss: Requested data is NOT in cache, must fetch from slower storage

• Cost: Slow access (milliseconds to seconds)
• Example: First time loading a webpage image

Hit Rate: The percentage of requests served from cache

Hit Rate = Hits / (Hits + Misses)
Example: 900 hits, 100 misses → Hit Rate = 900/1000 = 90%

Why hit rate matters:

• 90% hit rate: 90% of requests take 0.1ms, 10% take 100ms → Average: 10.09ms
• 99% hit rate: 99% take 0.1ms, 1% take 100ms → Average: 1.099ms
• 9x improvement from 90% to 99% hit rate!

2. Cache Capacity Limits

Caches must have bounded size to avoid consuming all memory. This creates the cache eviction problem: when the cache is full and a new item needs to be stored, which existing item should be removed?

Without eviction (unbounded cache):

#![allow(unused)]
fn main() {
// Memory grows without bound - will eventually crash!
let cache = HashMap::new();
loop {
    let data = fetch_from_api();
    cache.insert(data.id, data);  // Grows forever
}
// After 1M entries of 1KB each = 1GB memory used
// After 10M entries = 10GB memory used → OOM crash
}

With eviction (bounded cache):

#![allow(unused)]
fn main() {
let cache = LRUCache::new(1000);  // Maximum 1000 entries
loop {
    let data = fetch_from_api();
    cache.put(data.id, data);
    // When cache reaches 1000 entries, least recently used item is removed
}
// Memory: Always ≤ 1000 entries (predictable, safe)
}

Cache Eviction Policies

When a cache is full, an eviction policy determines which item to remove. Different policies optimize for different access patterns.

Common Eviction Policies

Comparison Example:

Cache capacity: 3 items
Access sequence: A, B, C, D, A, E

┌─────────┬──────────┬────────────┬───────────────┬────────────┐
│ Access  │ FIFO     │ LRU        │ LFU           │ Random     │
├─────────┼──────────┼────────────┼───────────────┼────────────┤
│ A       │ [A]      │ [A]        │ [A:1]         │ [A]        │
│ B       │ [A,B]    │ [A,B]      │ [A:1,B:1]     │ [A,B]      │
│ C       │ [A,B,C]  │ [A,B,C]    │ [A:1,B:1,C:1] │ [A,B,C]    │
│ D       │ [B,C,D]  │ [B,C,D]    │ [B:1,C:1,D:1] │ [A,C,D]    │
│         │ (evict A)│ (evict A)  │ (evict A)     │ (evict B)  │
│ A       │ [B,C,D]  │ [B,D,A]    │ [C:1,D:1,A:1] │ [A,C,D]    │
│         │ MISS     │ (evict C)  │ (evict B)     │ MISS       │
│         │          │ HIT via A  │               │            │
│ E       │ [C,D,E]  │ [D,A,E]    │ [D:1,A:1,E:1] │ [A,E,D]    │
│         │ (evict B)│ (evict B)  │ (evict C)     │ (evict C)  │
└─────────┴──────────┴────────────┴───────────────┴────────────┘

Hit rates for this sequence:
- FIFO: 0% (0 hits, 6 misses)
- LRU: 16.7% (1 hit, 5 misses)  ← Best for this pattern
- LFU: 0% (0 hits, 6 misses)
- Random: 16.7% (1 hit, 5 misses) - depends on random choice

Deep Dive: The LRU Algorithm

LRU (Least Recently Used) evicts the item that hasn’t been accessed for the longest time. It’s based on the assumption that recently accessed data is more likely to be accessed again soon.

Why LRU Works Well

Temporal Locality Principle: If data was accessed recently, it’s likely to be accessed again soon.

Real-world examples:

1. Web browser cache: Recently viewed images/pages are likely to be viewed again
2. Database query cache: Same queries run repeatedly (dashboards, APIs)
3. File system cache: Editing a file → repeated reads/writes to same blocks
4. Game asset cache: Current level assets used repeatedly; old level assets not needed

How LRU Tracking Works

Core idea: Maintain access order, with most recently used at one end and least recently used at the other.

Initial state (capacity: 3):
Cache: []
Order: []

Access A:
Cache: {A: "data_a"}
Order: [A]  ← LRU                                   MRU →

Access B:
Cache: {A: "data_a", B: "data_b"}
Order: [A, B]  ← LRU                                MRU →

Access C:
Cache: {A: "data_a", B: "data_b", C: "data_c"}
Order: [A, B, C]  ← LRU                             MRU →

Access A again (move to most recent):
Cache: {A: "data_a", B: "data_b", C: "data_c"}
Order: [B, C, A]  ← LRU                             MRU →
       └─ Now B is least recently used

Access D (cache full, evict B):
Cache: {A: "data_a", C: "data_c", D: "data_d"}
Order: [C, A, D]  ← LRU                             MRU →
       └─ B was removed (least recently used)

LRU Operations

Every cache operation updates the access order:

1. get(key):

   • If found: Move key to most recent position, return value (HIT)
   • If not found: Return None (MISS)

2. put(key, value):

   • If key exists: Update value, move to most recent
   • If cache full: Remove least recent item, insert new item as most recent
   • If cache not full: Insert new item as most recent

Time complexity requirements:

• get(): O(1) - Must be fast for cache to be useful
• put(): O(1) - Including eviction
• Update order: O(1) - Move item to most recent position

Implementation Strategies

Strategy 1: HashMap + VecDeque (This project uses this)

#![allow(unused)]
fn main() {
struct LRUCache<K, V> {
    data: HashMap<K, V>,      // Fast lookup: O(1)
    order: VecDeque<K>,       // Track access order
}

// Get operation:
// 1. Lookup in HashMap: O(1)
// 2. Find key in VecDeque: O(n) ← SLOW!
// 3. Remove from current position: O(n)
// 4. Push to back: O(1)
// Total: O(n) - not ideal, but simple
}

Trade-off: Simple to implement, but updating order is O(n) because we need to find and remove the key from the VecDeque.

Strategy 2: HashMap + Doubly-Linked List (Optimal, used in production)

#![allow(unused)]
fn main() {
struct LRUCache<K, V> {
    data: HashMap<K, *mut Node<K, V>>,  // Value + pointer to node
    order: DoublyLinkedList<K, V>,      // Actual order
}

struct Node<K, V> {
    key: K,
    value: V,
    prev: *mut Node<K, V>,
    next: *mut Node<K, V>,
}

// Get operation:
// 1. Lookup in HashMap: O(1) - gives us pointer to node
// 2. Remove node from list: O(1) - just update pointers
// 3. Insert at tail: O(1)
// Total: O(1) ← OPTIMAL
}

Trade-off: O(1) operations, but requires unsafe code for pointer manipulation in Rust.

Real-World Cache Examples

1. CPU Caches (Hardware)

L1 Cache: 32-64 KB per core, ~4 CPU cycles latency L2 Cache: 256-512 KB per core, ~12 cycles L3 Cache: 8-32 MB shared, ~40 cycles RAM: Gigabytes, ~100 cycles

// Without L1 cache:
for i in 0..1000 {
    sum += array[i];  // Each access: 100 cycles (RAM)
}
// Total: 100,000 cycles

// With L1 cache (after first access):
for i in 0..1000 {
    sum += array[i];  // First: 100 cycles, rest: 4 cycles
}
// Total: 100 + 999×4 = 4,096 cycles (24x faster!)

2. Web Browser Cache

Browsers cache images, CSS, JavaScript, and HTML to avoid re-downloading.

First visit to website:
- Download: 2MB of assets (images, CSS, JS)
- Time: 2 seconds on 10 Mbps connection

Second visit (with cache):
- Check cache: 50 files, all HITs
- Time: 50ms to verify freshness
- Speedup: 40x faster

Eviction: LRU-based, typically 50-500 MB capacity

3. Database Query Cache

#![allow(unused)]
fn main() {
// MySQL query cache example
// First execution:
let result = db.query("SELECT * FROM users WHERE age > 18");
// Time: 100ms (disk I/O, query execution)
// Cache: Store query → result mapping

// Second execution (same query):
let result = db.query("SELECT * FROM users WHERE age > 18");
// Time: 0.1ms (cache HIT)
// Speedup: 1000x faster
}

Eviction: LRU with automatic invalidation when table is modified

4. CDN (Content Delivery Network)

CDNs cache website content geographically close to users.

User in Sydney requests image from US-based server:

Without CDN:
- Round trip: 200ms (speed of light limit!)
- Transfer: 50ms
- Total: 250ms

With CDN (cached in Sydney):
- Round trip: 10ms (local server)
- Transfer: 5ms
- Total: 15ms
- Speedup: 16x faster

Eviction: Mix of LRU and TTL (Time-To-Live)

5. Operating System Page Cache

OS caches disk blocks in RAM to speed up file access.

Reading a 1GB file:

First read (cold cache):
- Disk: 1GB at 100 MB/s = 10 seconds

Second read (warm cache):
- RAM: 1GB at 10 GB/s = 0.1 seconds
- Speedup: 100x faster

Eviction: LRU-based (Linux uses LRU with active/inactive lists)

Performance Characteristics

Memory Usage

#![allow(unused)]
fn main() {
// Memory = (capacity × item_size) + overhead

// Example: LRU cache with capacity 10,000
struct Entry {
    key: String,    // ~24 bytes (avg)
    value: User,    // ~200 bytes
}

// HashMap: ~224 bytes per entry
// VecDeque: ~8 bytes per key (pointer/index)
// Total per entry: ~232 bytes
// Total memory: 10,000 × 232 = 2.32 MB
}

Time Complexity

Why VecDeque is O(n):

#![allow(unused)]
fn main() {
// Must find and remove key from middle of VecDeque
order.retain(|k| k != key);  // O(n) - scans entire VecDeque
order.push_back(key);         // O(1)
}

Why LinkedList is O(1):

#![allow(unused)]
fn main() {
// HashMap stores pointer to node, can remove directly
let node = map.get(key);      // O(1)
list.remove(node);            // O(1) - just update pointers
list.push_back(node);         // O(1)
}

Cache Hit Rate Impact

Measurement: How hit rate affects average latency

Cache latency: 0.1ms
Database latency: 100ms

Hit Rate    Avg Latency    Calculation
50%         50.05ms        0.5×0.1 + 0.5×100
70%         30.07ms        0.7×0.1 + 0.3×100
90%         10.09ms        0.9×0.1 + 0.1×100
95%         5.095ms        0.95×0.1 + 0.05×100
99%         1.099ms        0.99×0.1 + 0.01×100

Insight: Going from 90% → 99% hit rate = 9x improvement!

When to Use LRU vs Other Policies

Use LRU When:

✅ Access patterns show temporal locality

• Web sessions (users browse multiple pages)
• Database queries (dashboards run same queries repeatedly)
• File editing (same files accessed multiple times)

✅ Recent access predicts future access

• News website (recent articles accessed more)
• E-commerce (viewed products likely to be viewed again)

✅ Memory is limited

• Need automatic eviction with bounded size
• Predictable memory usage is critical

Avoid LRU When:

❌ Sequential scans (each item accessed once)

#![allow(unused)]
fn main() {
// LRU performs poorly here
for i in 0..1_000_000 {
    cache.get(i);  // Each item accessed once, never again
}
// Every access is a MISS, cache constantly evicts
// Better: No cache, or MRU policy
}

❌ Popular items accessed infrequently

• Video streaming (popular movies accessed monthly)
• Better: LFU (Least Frequently Used)

❌ Need time-based expiration

• Session tokens (expire after 30 minutes)
• Better: TTL (Time-To-Live) cache

Rust Programming Concepts for This Project

This project requires understanding several Rust-specific concepts that enable safe and efficient cache implementation. These concepts address challenges that don’t exist in garbage-collected languages.

Interior Mutability: The Core Challenge

The Problem: Rust’s borrow checker normally requires &mut self to modify data. But caches need to update internal state (access tracking, statistics) during read operations that only have &self.

#![allow(unused)]
fn main() {
// This doesn't work - get() only has &self, can't modify!
impl Cache {
    fn get(&self, key: &K) -> Option<V> {
        self.hits += 1;  // ❌ Error: cannot mutate through &self
        // ...
    }
}

// Requiring &mut self doesn't work either - prevents sharing!
impl Cache {
    fn get(&mut self, key: &K) -> Option<V> {
        self.hits += 1;  // ✅ Compiles
        // ...
    }
}

let cache = Cache::new();
let hits = cache.get(&"key1");  // ❌ Error: need mutable borrow
let misses = cache.get(&"key2"); // Can't have multiple mutable refs!
}

The Solution: Interior mutability - types that provide mutable access through shared references (&self).

Cell: Zero-Cost Interior Mutability for Copy Types

What It Is: A container that allows mutating the value inside through &self, but only for types that implement Copy (integers, booleans, small structs).

How It Works:

#![allow(unused)]
fn main() {
use std::cell::Cell;

let counter = Cell::new(0);
counter.set(counter.get() + 1);  // Mutate through &self!
println!("{}", counter.get());   // 1
}

Key Properties:

• Zero runtime cost: Just moves bytes around
• Only for Copy types: Can’t use with String, Vec, HashMap
• No borrowing: Values are copied in/out, never borrowed
• Not thread-safe: Only works in single-threaded code

Why We Use It: Perfect for counters (hits, misses) - they’re just usize values.

Limitations:

#![allow(unused)]
fn main() {
let cache_data = Cell::new(HashMap::new());
// ❌ Error: HashMap doesn't implement Copy
}

RefCell: Runtime-Checked Interior Mutability

What It Is: Like Cell, but works with any type. Enforces borrow rules at runtime instead of compile time.

How It Works:

#![allow(unused)]
fn main() {
use std::cell::RefCell;
use std::collections::HashMap;

let cache = RefCell::new(HashMap::new());

// Borrow for reading
{
    let data = cache.borrow();  // Returns Ref<HashMap>
    println!("{:?}", data.get(&"key"));
}  // Borrow released here

// Borrow for writing
{
    let mut data = cache.borrow_mut();  // Returns RefMut<HashMap>
    data.insert("key", "value");
}  // Borrow released here
}

Key Properties:

• Works with any type: HashMap, Vec, custom structs, etc.
• Runtime borrow checking: Panics if borrow rules violated
• Small overhead: Maintains borrow counters (~2-3 CPU instructions)
• Not thread-safe: Panics if used across threads

Borrow Rules (checked at runtime):

• Multiple readers OR one writer: Can have many borrow() or one borrow_mut(), not both
• Borrows must be released: The Ref/RefMut guards must drop before next borrow

Because of the runtime borrow checking is a good practice to release the borrow as soon as possible by calling drop() or by shrinking the scope.

Common Pitfalls:

#![allow(unused)]
fn main() {
let cache = RefCell::new(HashMap::new());
let data = cache.borrow();          // Acquire read borrow
cache.borrow_mut().insert(1, 2);    // ❌ PANIC: already borrowed!
drop(data);                          // Must release first
cache.borrow_mut().insert(1, 2);    // ✅ Now it works
}

Why We Use It: Our cache needs to store HashMap<K, V> and VecDeque<K> - both require RefCell for interior mutability.

Thread Safety: From RefCell to Mutex

The Problem: RefCell is NOT thread-safe. If two threads access it simultaneously, you get undefined behavior (data races).

#![allow(unused)]
fn main() {
let cache = RefCell::new(HashMap::new());
let cache_ref = &cache;

// Thread 1
std::thread::spawn(move || {
    cache_ref.borrow_mut().insert(1, 100);  // ❌ DATA RACE!
});

// Thread 2 (simultaneously)
cache.borrow_mut().insert(2, 200);  // ❌ DATA RACE!
}

The Solution: Mutex<T> - thread-safe interior mutability using OS-level locks.

Mutex: Thread-Safe Interior Mutability

What It Is: A mutual exclusion lock that ensures only one thread can access the data at a time.

How It Works:

#![allow(unused)]
fn main() {
use std::sync::Mutex;

let cache = Mutex::new(HashMap::new());

// Acquire lock (blocks if another thread holds it)
let mut data = cache.lock().unwrap();  // Returns MutexGuard
data.insert("key", "value");
// Lock automatically released when guard drops
}

Key Properties:

• Thread-safe: Safe to share between threads
• Blocking: If locked, other threads wait
• Significant overhead: System call (~20-100ns vs 0.2ns for RefCell)
• Poisoning: If thread panics while holding lock, mutex is “poisoned”

Performance Impact:

Operation          RefCell     Mutex      Slowdown
Simple increment   0.2ns       20ns       100x
HashMap lookup     10ns        30ns       3x
Complex operation  100ns       150ns      1.5x

Why We Need It: To make the cache usable from multiple threads safely.

Arc: Shared Ownership Across Threads

The Problem: Can’t share &Cache across threads because threads might outlive the original owner.

#![allow(unused)]
fn main() {
let cache = LRUCache::new(100);
std::thread::spawn(|| {
    cache.put(1, 2);  // ❌ Error: cache may not live long enough
});
}

The Solution: Arc<T> (Atomic Reference Counted) - shared ownership with atomic counters.

How It Works:

#![allow(unused)]
fn main() {
use std::sync::Arc;

let cache = Arc::new(LRUCache::new(100));
let cache_clone = Arc::clone(&cache);  // Increment ref count

std::thread::spawn(move || {
    cache_clone.put(1, 2);  // ✅ Works! Thread owns a clone
});

cache.get(&1);  // ✅ Original still valid
// Last Arc drops -> cache is freed
}

Key Properties:

• Atomic counters: Thread-safe reference counting
• Shared ownership: Multiple owners, freed when last one drops
• Clone is cheap: Just increments counter (~5-10ns)
• Immutable by default: Need Arc<Mutex<T>> or Arc<RwLock<T>> for mutation

Why We Need It: Threads need independent ownership of the cache.

Generics: Type-Agnostic Data Structures

The Problem: We want our cache to work with any key/value types, not just String → i32.

The Solution: Generic type parameters <K, V>.

How It Works:

#![allow(unused)]
fn main() {
struct LRUCache<K, V> {
    data: HashMap<K, V>,
    // ...
}

impl<K, V> LRUCache<K, V>
where
    K: Eq + std::hash::Hash + Clone,
    V: Clone,
{
    fn new(capacity: usize) -> Self { /* ... */ }
    fn get(&self, key: &K) -> Option<V> { /* ... */ }
}

// Use with any types that satisfy the trait bounds:
let int_cache: LRUCache<i32, String> = LRUCache::new(100);
let str_cache: LRUCache<String, Vec<u8>> = LRUCache::new(50);
}

Trait Bounds Explained:

• K: Eq + Hash: Keys must be comparable and hashable (required for HashMap)
• K: Clone: Need to copy keys into VecDeque for order tracking
• V: Clone: Need to return cloned values (can’t give away ownership)

Why We Use It: Makes the cache reusable for any data types.

Understanding Trait Bounds

This project uses several trait bounds. Here’s what they mean:

Type Requirements Summary:

#![allow(unused)]
fn main() {
// Milestone 1-4 (single-threaded with RefCell):
K: Eq + Hash + Clone
V: Clone

// Milestone 5 (thread-safe with Mutex):
K: Eq + Hash + Clone + Send
V: Clone + Send
}

Performance Trade-offs: RefCell vs Mutex

Understanding when to use each is critical:

Decision Guide:

1. Need to share across threads? → Must use Arc<Mutex<T>>
2. Single thread + Copy type? → Use Cell<T>
3. Single thread + non-Copy type? → Use RefCell<T>

Why Multiple Data Structures?

The Challenge: LRU requires both fast lookup AND ordered access tracking.

Why We Use Both:

• HashMap: Stores actual key-value pairs, enables O(1) lookup
• VecDeque: Tracks access order (back = most recent, front = least recent)

Synchronization Challenge:

#![allow(unused)]
fn main() {
struct LRUCache<K, V> {
    data: RefCell<HashMap<K, V>>,    // The actual cache data
    order: RefCell<VecDeque<K>>,     // The access order
}

// Every operation must keep them in sync!
fn put(&self, key: K, value: V) {
    let mut data = self.data.borrow_mut();
    let mut order = self.order.borrow_mut();

    data.insert(key.clone(), value);
    order.push_back(key);  // Must stay synchronized!
}
}

Why VecDeque Instead of Vec:

• VecDeque supports O(1) removal from front (LRU eviction)
• Vec would require O(n) shifting when removing front element

Connection to This Project

This project implements an LRU cache with the following progression:

1. Milestone 1-2: Learn interior mutability patterns (Cell, RefCell)
2. Milestone 3: Implement LRU eviction logic with HashMap + VecDeque
3. Milestone 4: Add statistics tracking (hit rate, miss rate)
4. Milestone 5: Make thread-safe with Mutex for concurrent access

Key learning points:

• O(n) is acceptable for learning: The VecDeque approach is simpler to understand
• Statistics matter: Can’t optimize what you don’t measure
• Thread safety has costs: Mutex is ~50-100x slower than RefCell
• Algorithm affects concurrency: LRU requires write-on-read (updating order), limiting parallelism

Building the Project

Milestone 1: Basic Statistics Tracker

LRU Caches Need Metrics: In production, an LRU cache without metrics is blind. You need to know: - Hit rate (hits / total accesses) - Is the cache effective? - Miss rate - Should you increase capacity? - Whether the cache is worth the memory cost

The Core Challenge: How do we increment counters through &self instead of &mut self? This milestone teaches you the solution: Cell<T>.

Goal: Create a simple counter

Architecture

Structs:

• StatsTracker - manages the counters
  • Field: hits - counts the hits
  • Field: misses - counts the misses

Functions:

• new(value: T) -> StatsTracker< - Allocates and initializes
• record_hit - Count the hits
• record_miss - Count the misses
• get_stats - Returns both

Starter Code:

#![allow(unused)]
fn main() {
use std::cell::Cell;

struct StatsTracker {
    hits: Cell<usize>,
    misses: Cell<usize>,
}

impl StatsTracker {
    fn new() -> Self {
        // TODO: Initialize with zero hits and misses
        todo!()
    }

    fn record_hit(&self) {
        // TODO: Increment hits using Cell::get and Cell::set
        todo!()
    }

    fn record_miss(&self) {
        // TODO: Increment misses
        todo!()
    }

    fn get_stats(&self) -> (usize, usize) {
        // TODO: Return (hits, misses)
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_stats_tracker() {
        let tracker = StatsTracker::new();
        assert_eq!(tracker.get_stats(), (0, 0));

        tracker.record_hit();
        tracker.record_hit();
        assert_eq!(tracker.get_stats(), (2, 0));

        tracker.record_miss();
        assert_eq!(tracker.get_stats(), (2, 1));
    }

    #[test]
    fn test_multiple_references() {
        let tracker = StatsTracker::new();
        let ref1 = &tracker;
        let ref2 = &tracker;

        ref1.record_hit();
        ref2.record_miss();

        assert_eq!(tracker.get_stats(), (1, 1));
    }
}
}

Check Your Understanding:

• Why can we call record_hit(&self) without &mut self?
• What is Cell<T> and why is it useful here??
• Why do we need Cell::get() before incrementing?

Why Milestone 1 Isn’t Enough

Limitation: Cell<T> only works with Copy types (like usize, bool, i32). For caching, we need to store complex data structures like HashMap<K, V>, which don’t implement Copy.

What we’re adding: RefCell<T> allows interior mutability for any type, not just Copy types. Trade-off: Cell has zero overhead, while RefCell performs runtime borrow checking.

Improvement:

• Capability: Can now wrap collections (HashMap, Vec, etc.)
• Cost: Small runtime overhead for borrow checking (~1-2 CPU cycles)
• Safety: Panics if borrow rules violated at runtime vs compile errors with plain borrows

Milestone 2: Simple HashMap Cache (No Eviction Yet)

Goal: Create a cache using RefCell<HashMap> that can insert and retrieve values.

Architecture:

• Structs: SimpleCache
  • Field: data: RefCell<HashMap<K, V>>

Functions:

• new() -> SimpleCache<K, V> - Allocates and initializes
• get(&self, key: &K) - return a value if present
• put(&self, key: K, value: V) - insert the key-value pair
• len(&self) - return number of items in cache

Starter Code:

#![allow(unused)]
fn main() {
use std::cell::RefCell;
use std::collections::HashMap;

struct SimpleCache<K, V> {
    data: RefCell<HashMap<K, V>>,
}

impl<K, V> SimpleCache<K, V>
where
    K: Eq + std::hash::Hash,
    V: Clone,
{
    fn new() -> Self {
        // TODO: Create cache with empty HashMap wrapped in RefCell
        todo!()
    }

    fn get(&self, key: &K) -> Option<V> {
        // TODO: Use borrow() to get read access to HashMap
        // Return cloned value if present
        todo!()
    }

    fn put(&self, key: K, value: V) {
        // TODO: Use borrow_mut() to get write access to HashMap
        // Insert the key-value pair
        todo!()
    }

    fn len(&self) -> usize {
        // TODO: Return number of items in cache
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_simple_cache() {
        let cache = SimpleCache::new();
        assert_eq!(cache.len(), 0);

        cache.put("key1", "value1");
        assert_eq!(cache.len(), 1);

        assert_eq!(cache.get(&"key1"), Some("value1"));
        assert_eq!(cache.get(&"key2"), None);
    }

    #[test]
    fn test_update_existing() {
        let cache = SimpleCache::new();
        cache.put("key", "value1");
        cache.put("key", "value2");

        assert_eq!(cache.len(), 1);
        assert_eq!(cache.get(&"key"), Some("value2"));
    }

    #[test]
    #[should_panic]
    fn test_borrow_violation() {
        let cache: SimpleCache<i32, i32> = SimpleCache::new();
        cache.put(1, 100);

        // This should panic: holding borrow across another borrow_mut
        let data = cache.data.borrow();
        cache.put(2, 200);  // This will panic!
        drop(data);
    }
}
}

Check Your Understanding:

• What’s the difference between borrow() and borrow_mut()?
• When is the borrow automatically released?
• Why did the test_borrow_violation panic?
• Why do we need V: Clone?

Why Milestone 2 Isn’t Enough

Limitation: Our cache grows unbounded! A cache without eviction will eventually consume all memory. In production, this causes OOM (Out Of Memory) kills.

What we’re adding:

• Capacity limits - Prevent unbounded memory growth
• LRU eviction policy - When full, remove least recently used item
• Access tracking - VecDeque tracks access order (most recent at back)

Improvement:

• Memory: Bounded memory usage (capacity × item_size)
• Predictability: Cache size never exceeds capacity
• Algorithm: O(1) eviction (remove front of VecDeque)
• Complexity: Need to manage two data structures in sync (HashMap + VecDeque)

Milestone 3: LRU Cache with Fixed Capacity

Add capacity limit and eviction logic. Use VecDeque to track access order.

Architecture struct LRUCache

#![allow(unused)]
fn main() {
struct LRUCache<K, V> {
  capacity: usize,
  data: RefCell<HashMap<K, V>>,
  order: RefCell<VecDeque<K>>,  // Most recent at back
}
}

functions (different implementations)

• new() -> LRUCache<K, V> - Allocates and initializes
• get(&self, key: &K) - return a value if present
• put(&self, key: K, value: V) - insert the key-value pair
• len(&self) - return number of items in cache

Starter Code:

#![allow(unused)]
fn main() {
use std::cell::RefCell;
use std::collections::{HashMap, VecDeque};

struct LRUCache<K, V> {
    capacity: usize,
    data: RefCell<HashMap<K, V>>,
    order: RefCell<VecDeque<K>>,  // Most recent at back
}

impl<K, V> LRUCache<K, V>
where
    K: Eq + std::hash::Hash + Clone,
    V: Clone,
{
    fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "Capacity must be greater than 0");
        // TODO: Initialize with given capacity
        todo!()
    }

    fn get(&self, key: &K) -> Option<V> {
        let data = self.data.borrow();
        if let Some(value) = data.get(key) {
            // TODO: Update access order - move key to back of VecDeque
            // Hint: First remove the key from its current position,
            // then push it to the back
            drop(data);  // Release borrow before mutating order
            let mut order = self.order.borrow_mut();
            // ... your code here ...
            // Return cloned value
            todo!()
        } else {
            None
        }
    }

    fn put(&self, key: K, value: V) {
        let mut data = self.data.borrow_mut();

        // Case 1: Key already exists - update value and move to back
        if data.contains_key(&key) {
            // TODO: Update value in HashMap
            // TODO: Move key to back in order VecDeque
            todo!()
        }
        // Case 2: At capacity - evict LRU item first
        else if data.len() >= self.capacity {
            // TODO: Remove front item from order (least recently used)
            // TODO: Remove that key from HashMap
            // TODO: Insert new key-value
            // TODO: Add new key to back of order
            todo!()
        }
        // Case 3: Under capacity - just insert
        else {
            // TODO: Insert new key-value
            // TODO: Add key to back of order
            todo!()
        }
    }

    fn len(&self) -> usize {
        self.data.borrow().len()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_lru_basic() {
        let cache = LRUCache::new(2);
        cache.put("a", 1);
        cache.put("b", 2);

        assert_eq!(cache.get(&"a"), Some(1));
        assert_eq!(cache.get(&"b"), Some(2));
        assert_eq!(cache.len(), 2);
    }

    #[test]
    fn test_lru_eviction() {
        let cache = LRUCache::new(2);
        cache.put("a", 1);
        cache.put("b", 2);
        cache.put("c", 3);  // Should evict "a"

        assert_eq!(cache.get(&"a"), None);  // "a" was evicted
        assert_eq!(cache.get(&"b"), Some(2));
        assert_eq!(cache.get(&"c"), Some(3));
        assert_eq!(cache.len(), 2);
    }

    #[test]
    fn test_lru_access_order() {
        let cache = LRUCache::new(2);
        cache.put("a", 1);
        cache.put("b", 2);

        // Access "a" to make it more recent
        assert_eq!(cache.get(&"a"), Some(1));

        // Insert "c" - should evict "b" (now least recent)
        cache.put("c", 3);

        assert_eq!(cache.get(&"a"), Some(1));
        assert_eq!(cache.get(&"b"), None);  // "b" was evicted
        assert_eq!(cache.get(&"c"), Some(3));
    }

    #[test]
    fn test_update_existing() {
        let cache = LRUCache::new(2);
        cache.put("a", 1);
        cache.put("a", 10);  // Update

        assert_eq!(cache.get(&"a"), Some(10));
        assert_eq!(cache.len(), 1);
    }

    #[test]
    fn test_capacity_one() {
        let cache = LRUCache::new(1);
        cache.put("a", 1);
        cache.put("b", 2);

        assert_eq!(cache.get(&"a"), None);
        assert_eq!(cache.get(&"b"), Some(2));
    }
}
}

Check Your Understanding:

• Why do we need to drop(data) before modifying order?
• What happens if we try to hold both borrows simultaneously?
• How does VecDeque help us track LRU order?
• Why do we check contains_key before checking capacity?

Why Milestone 3 Isn’t Enough

Limitation: We have no visibility into cache performance! Without metrics, we can’t answer:

• Is the cache effective? (high hit rate = good, low = wasting memory)
• Should we increase capacity? (too many misses)
• Is it worth the memory cost? (hit rate analysis)

What we’re adding: the StatsTracker

• Hit/Miss tracking - Measure cache effectiveness
• Statistics API - Query performance metrics
• Persistent metrics - Stats survive cache clears

Improvement:

• Observability: Can measure cache effectiveness (hit rate = hits / (hits + misses))
• Optimization guidance: Low hit rate → increase capacity or change eviction policy
• Production monitoring: Export metrics to Prometheus/Grafana
• Cost: Minimal—just two Cell<usize> increments per access

Milestone 4: Add Statistics Tracking

Integrate the stats tracker from Milestone 1.

Architecture: struct: Modify your LRUCache to include a field StatsTracker field and update functions:

• get() to record hits/misses.
• stats() wrapper of get_stats()
• clear() clear data and order

New method to add:

#![allow(unused)]
fn main() {
fn stats(&self) -> (usize, usize) {
   todo!()
}

fn clear(&self) {
    // Don't clear stats - they persist across clears
    todo!()
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_stats_tracking() {
    let cache = LRUCache::new(2);
    cache.put("a", 1);
    cache.put("b", 2);

    cache.get(&"a");  // Hit
    cache.get(&"b");  // Hit
    cache.get(&"c");  // Miss

    let (hits, misses) = cache.stats();
    assert_eq!(hits, 2);
    assert_eq!(misses, 1);
}

#[test]
fn test_clear() {
    let cache = LRUCache::new(2);
    cache.put("a", 1);
    cache.get(&"a");
    cache.get(&"b");  // miss

    cache.clear();
    assert_eq!(cache.len(), 0);

    let (hits, misses) = cache.stats();
    assert_eq!(hits, 1);  // Stats persist
    assert_eq!(misses, 1);
}
}

Check Your Understanding:

• Why don’t we clear stats when clearing the cache?
• Could we use Cell<(usize, usize)> instead of separate Cell fields?

Why Milestone 4 Isn’t Enough

Critical Limitation: RefCell is NOT thread-safe! If two threads access it simultaneously, your program exhibits undefined behavior (data races, memory corruption).

Why we need thread safety:

• Web servers handle concurrent requests across multiple threads
• Game engines run rendering, physics, and AI on different threads
• Microservices need to share caches across async tasks

What we’re adding:

• Mutex<T> instead of RefCell<T> - OS-level locking for thread safety
• Arc<T> - Atomic reference counting for sharing across threads
• AtomicUsize for stats - Thread-safe counters

Performance Changes:

• Speed: Mutex is ~50-100x slower than RefCell (10-20ns vs 0.2ns)
• Why: System calls, kernel context switches, CPU cache invalidation
• Parallelism: Multiple threads can now safely access cache (but serialized by lock)
• Contention: Under high concurrent load, threads wait for locks (reduced throughput)

When it’s worth it: When you have concurrent access. Single-threaded? Stick with RefCell.

Milestone 5: Thread-Safe Version with Mutex

Create a thread-safe version using Mutex instead of RefCell.

Architecture:

• Use self.inner.lock().unwrap() to get a MutexGuard at the beginning of the function
• The guard automatically releases when dropped
• For thread-safety, StatsTracker instead of Cell<usize>we needs AtomicUsize
• Use Relaxed as Ordering

Starter Code:

#![allow(unused)]
fn main() {
use std::sync::{Arc, Mutex};
use std::collections::{HashMap, VecDeque};

struct ThreadSafeLRUCache<K, V> {
    capacity: usize,
    inner: Mutex<CacheInner<K, V>>,
    // Stats need atomic operations or separate mutex
    stats: StatsTracker,  // From Milestone 1 - uses Cell (NOT thread-safe!)
}

struct CacheInner<K, V> {
    data: HashMap<K, V>,
    order: VecDeque<K>,
}

// TODO: Implement similar methods but using use the mutex guard instead of refcell borrows
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_thread_safe_basic() {
    let cache = Arc::new(ThreadSafeLRUCache::new(10));

    let cache_clone = Arc::clone(&cache);
    let handle = std::thread::spawn(move || {
        cache_clone.put("thread_key", 42);
    });

    handle.join().unwrap();
    assert_eq!(cache.get(&"thread_key"), Some(42));
}

#[test]
fn test_concurrent_access() {
    let cache = Arc::new(ThreadSafeLRUCache::new(100));
    let mut handles = vec![];

    for i in 0..10 {
        let cache_clone = Arc::clone(&cache);
        let handle = std::thread::spawn(move || {
            for j in 0..10 {
                cache_clone.put(i * 10 + j, i * 100 + j);
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    assert_eq!(cache.len(), 100);
}
}

Check Your Understanding:

• What’s the difference between Mutex and RefCell?
• Why do we need Arc to share the cache between threads?
• What happens if a thread panics while holding the lock?
• Why can’t we use Cell<usize> for stats in the thread-safe version?

Arena-Based Expression Parser

Problem Statement

Build a parser for arithmetic expressions, that uses arena (bump) allocation. This demonstrates how arena allocation can speed up programs that create many small objects. We will go from simple expression enums to lexer to parser

Key Learning Points:

• ASTs represent program structure as trees
• Lexers simplify parsing by handling character-level details
• Recursive descent is an intuitive parsing technique
• Grammar structure encodes operator precedence
• Arena allocation can speed up tree construction

Use Cases

When you need this pattern:

1. Compiler frontends: Lexer tokens, AST nodes, symbol table entries
2. Web request handlers: Per-request temporary objects (template AST, JSON parsing)
3. Game engines: Per-frame allocations (particle systems, AI pathfinding nodes)
4. Database query execution: Query plan nodes, temporary expression trees
5. Text editors: Syntax tree for incremental parsing
6. JSON/XML parsers: DOM nodes, parsing state

Understanding Parsers: ASTs, Expressions, Lexers, and Recursive Descent

Before diving into the implementation, let’s understand the fundamental concepts that make parsers work. This project implements a complete parser pipeline from scratch, giving you hands-on experience with concepts used in every compiler, interpreter, and language tool.

What is a Parser?

A parser is a program that reads text (source code, JSON, configuration files, etc.) and converts it into a structured representation that computers can work with. Every programming language, database query language, and markup language needs a parser.

The fundamental problem: Computers can’t directly understand text like "2 + 3 * 4". They need this converted into a tree structure that represents the operations and their precedence.

Example transformation:

Text input: "2 + 3 * 4"

Parser converts to tree:
        (+)
       /   \
      2    (*)
          /   \
         3     4

This tree says: "First multiply 3 and 4, then add 2 to the result"
Result: 2 + 12 = 14 (not 20!)

Abstract Syntax Trees (ASTs)

An Abstract Syntax Tree (AST) is a tree representation of the source code. Each node in the tree represents a construct in the code.

Why “Abstract”?

• The tree abstracts away syntactic details like parentheses, whitespace, and semicolons
• It captures meaning (semantics), not just form (syntax)
• Example: (2+3) and 2+3 produce the same AST even though the text is different

AST vs Parse Tree:

Input: "2 + 3"

Parse Tree (concrete, includes all syntax):
    Expr
     |
    Term
     |
   Factor  '+'  Factor
     |            |
    '2'          '3'

AST (abstract, only meaning):
    (+)
   /   \
  2     3

AST Structure for Arithmetic Expressions:

#![allow(unused)]
fn main() {
// Our AST nodes
enum Expr {
    Literal(i64),              // A number: 42
    BinOp {                     // Binary operation: left op right
        op: OpType,             // +, -, *, /
        left: &Expr,           // Left sub-expression
        right: &Expr,          // Right sub-expression
    }
}
}

Example ASTs:

Expression: "5"
AST: Literal(5)

Expression: "2 + 3"
AST:
    BinOp {
        op: Add,
        left: Literal(2),
        right: Literal(3)
    }

Expression: "2 + 3 * 4"
AST:
    BinOp {
        op: Add,
        left: Literal(2),
        right: BinOp {
            op: Mul,
            left: Literal(3),
            right: Literal(4)
        }
    }

Expression: "(2 + 3) * 4"
AST:
    BinOp {
        op: Mul,
        left: BinOp {
            op: Add,
            left: Literal(2),
            right: Literal(3)
        },
        right: Literal(4)
    }

Key AST Properties:

1. Recursive Structure: Trees can be arbitrarily nested

   • 1 + 2 is a tree
   • (1 + 2) * (3 + 4) is a tree containing two smaller trees

2. Evaluation by Tree Walk: To evaluate an expression, walk the tree recursively:

   #![allow(unused)]
   fn main() {
   fn eval(expr: &Expr) -> i64 {
       match expr {
           Expr::Literal(n) => *n,  // Base case
           Expr::BinOp { op, left, right } => {
               let l = eval(left);   // Recursive call
               let r = eval(right);  // Recursive call
               apply_op(op, l, r)
           }
       }
   }
   }

3. Precedence is Encoded in Structure: Higher-precedence operations are deeper in the tree

   • In 2 + 3 * 4, the multiplication is a child of addition
   • The multiplication must evaluate first (depth-first)

What are Expressions?

An expression is a combination of values, variables, and operators that can be evaluated to produce a value.

Expression Examples:

42                    → Evaluates to 42
2 + 3                 → Evaluates to 5
2 + 3 * 4             → Evaluates to 14
(2 + 3) * 4           → Evaluates to 20
((1 + 2) * 3) - 4     → Evaluates to 5

Not expressions (these are statements, they don’t produce values):

let x = 5;            // Variable declaration
if x > 0 { ... }      // Conditional statement
while true { ... }    // Loop statement

Expression Components:

1. Literals: Concrete values like 42, 3.14, "hello"

2. Operators: Symbols that combine values like +, -, *, /

3. Operands: The values operators work on

4. Precedence: Rules for which operators bind tighter

   • * and / bind tighter than + and -
   • 2 + 3 * 4 = 2 + (3 * 4), not (2 + 3) * 4

5. Associativity: When operators have equal precedence, which direction to evaluate

   • Left associative: 10 - 5 - 2 = (10 - 5) - 2 = 3
   • Right associative: 2 ^ 3 ^ 2 = 2 ^ (3 ^ 2) = 512 (in languages with exponentiation)

Operator Precedence Table (for this project):

Highest: ( )         Parentheses (force evaluation order)
         * /         Multiplication and Division
Lowest:  + -         Addition and Subtraction

Examples:
2 + 3 * 4     = 2 + (3 * 4) = 14
8 / 4 / 2     = (8 / 4) / 2 = 1    (left associative)
2 + 3 - 1     = (2 + 3) - 1 = 4    (left associative)
(2 + 3) * 4   = 5 * 4 = 20         (parens override precedence)

Why Expressions Matter:

Every programming language has expressions:

• JavaScript: x + y, foo() && bar(), a ? b : c
• Python: x + y, [i*2 for i in range(10)], a if cond else b
• Rust: x + y, Some(42), vec![1, 2, 3]
• SQL: price * quantity, UPPER(name), age > 18 AND active = true

Understanding how to parse expressions is fundamental to working with any language.

What is a Lexer (Tokenizer)?

A lexer (also called tokenizer or scanner) is the first stage of parsing. It breaks raw text into meaningful chunks called tokens.

The Lexer’s Job:

Input:  "(2 + 3) * 4"    ← Raw string of characters
Output: [LeftParen, Number(2), Plus, Number(3), RightParen, Star, Number(4), End]
                         ↑ Tokens

Why We Need Lexers:

1. Simplification: The parser doesn’t have to worry about:

   • Skipping whitespace
   • Reading multi-character numbers
   • Handling comments
   • Unicode vs ASCII

2. Separation of Concerns:

   • Lexer handles character-level details
   • Parser handles structural details

3. Performance: Can optimize lexer separately (e.g., SIMD for digit scanning)

4. Reusability: Same token stream can feed different parsers

Token Types:

#![allow(unused)]
fn main() {
enum Token {
    Number(i64),        // 42, 123, 9876
    Plus,               // +
    Minus,              // -
    Star,               // *
    Slash,              // /
    LeftParen,          // (
    RightParen,         // )
    End,                // End of input
}
}

Lexer Algorithm:

function next_token():
    1. Skip whitespace (spaces, tabs, newlines)
    2. Look at current character:
       - If digit: read_number() → Token::Number(n)
       - If '+': return Token::Plus
       - If '-': return Token::Minus
       - If '*': return Token::Star
       - If '/': return Token::Slash
       - If '(': return Token::LeftParen
       - If ')': return Token::RightParen
       - If end of input: return Token::End
       - Otherwise: ERROR (unexpected character)
    3. Advance position past the token
    4. Return the token

Example Tokenization:

Input: "10 + 5 * 2"

Step-by-step:
Position 0: '1' is digit → read_number() reads "10" → Token::Number(10)
Position 2: ' ' is space → skip
Position 3: '+' → Token::Plus
Position 4: ' ' is space → skip
Position 5: '5' is digit → read_number() reads "5" → Token::Number(5)
Position 6: ' ' is space → skip
Position 7: '*' → Token::Star
Position 8: ' ' is space → skip
Position 9: '2' is digit → read_number() reads "2" → Token::Number(2)
Position 10: End of input → Token::End

Result: [Number(10), Plus, Number(5), Star, Number(2), End]

Reading Multi-Character Tokens:

#![allow(unused)]
fn main() {
fn read_number() -> i64 {
    let mut num = 0;
    while current char is digit {
        num = num * 10 + (char - '0');  // Build number digit by digit
        advance();
    }
    return num;
}
}

Example: “123” Start: num = 0 See ‘1’: num = 010 + 1 = 1 See ‘2’: num = 110 + 2 = 12 See ‘3’: num = 12*10 + 3 = 123 See ’ ’: not a digit, stop Return 123

Lexer State:

#![allow(unused)]
fn main() {
struct Lexer {
    input: Vec<char>,     // Input text as characters
    position: usize,      // Current position in input
}
}

Why Vec instead of &str?

• Easy indexing by character (not byte)
• Handles multi-byte Unicode correctly
• Simple position counter

What is Recursive Descent Parsing?

Recursive descent is a parsing technique where:

1. Each grammar rule becomes a function
2. Functions call each other recursively to match nested structures
3. The call stack mirrors the parse tree structure

Our Grammar (for arithmetic expressions):

Expr   → Term (('+' | '-') Term)*      // Lowest precedence
Term   → Factor (('*' | '/') Factor)*  // Medium precedence
Factor → Number | '(' Expr ')'         // Highest precedence

Reading the Grammar:

• → means “is defined as”
• | means “or”
• * means “zero or more”
• () groups elements

Translation to Functions:

#![allow(unused)]
fn main() {
// Expr → Term (('+' | '-') Term)*
fn parse_expr() -> Expr {
    let mut left = parse_term();      // Start with a Term
    while current token is '+' or '-' {
        let op = consume operator;
        let right = parse_term();
        left = BinOp(op, left, right);
    }
    return left;
}

// Term → Factor (('*' | '/') Factor)*
fn parse_term() -> Expr {
    let mut left = parse_factor();    // Start with a Factor
    while current token is '*' or '/' {
        let op = consume operator;
        let right = parse_factor();
        left = BinOp(op, left, right);
    }
    return left;
}

// Factor → Number | '(' Expr ')'
fn parse_factor() -> Expr {
    if current token is Number(n) {
        consume token;
        return Literal(n);
    }
    if current token is '(' {
        consume '(';
        let expr = parse_expr();     // Recursive call!
        expect ')';
        return expr;
    }
    error("Expected number or '('");
}
}

How Precedence Works:

The grammar encodes precedence through nesting depth:

• Factor (deepest) = highest precedence
• Term (middle) = medium precedence
• Expr (top) = lowest precedence

Example Parse: 2 + 3 * 4

Tokens: [Number(2), Plus, Number(3), Star, Number(4), End]

parse_expr():
  left = parse_term():
    left = parse_factor():
      See Number(2) → return Literal(2)
    See '+' (not '*' or '/') → return Literal(2)

  See '+' → consume it

  right = parse_term():
    left = parse_factor():
      See Number(3) → return Literal(3)
    See '*' → consume it
    right = parse_factor():
      See Number(4) → return Literal(4)
    left = BinOp(Mul, Literal(3), Literal(4))
    No more '*' or '/' → return BinOp(Mul, 3, 4)

  left = BinOp(Add, Literal(2), BinOp(Mul, 3, 4))

  No more '+' or '-' → return result

Result AST:
    Add
   /   \
  2    Mul
      /   \
     3     4

Why Three Levels?

This ensures 3 * 4 is fully parsed before returning to the addition:

• parse_expr() calls parse_term() for “3 * 4”
• parse_term() consumes both “3” and “* 4” as a unit
• Returns Mul(3, 4) as a single node
• parse_expr() then builds Add(2, Mul(3, 4))

Example Parse: (2 + 3) * 4

Tokens: [LeftParen, Number(2), Plus, Number(3), RightParen, Star, Number(4), End]

parse_expr():
  left = parse_term():
    left = parse_factor():
      See '(' → consume it

      Recursive call to parse_expr():  ← RECURSION!
        left = parse_term():
          left = parse_factor():
            See Number(2) → return Literal(2)
          No '*' or '/' → return Literal(2)
        See '+' → consume it
        right = parse_term():
          left = parse_factor():
            See Number(3) → return Literal(3)
          No '*' or '/' → return Literal(3)
        left = BinOp(Add, Literal(2), Literal(3))
        No more '+' or '-' → return Add(2, 3)

      Expect ')' → found it, consume
      return Add(2, 3)  ← Returns from recursive call

    See '*' → consume it
    right = parse_factor():
      See Number(4) → return Literal(4)
    left = BinOp(Mul, Add(2, 3), Literal(4))
    No more '*' or '/' → return Mul(Add(2, 3), 4)

  No '+' or '-' → return result

Result AST:
     Mul
    /   \
  Add    4
 /   \
2     3

Key Insight: The parentheses forced parse_factor() to recursively call parse_expr(), which parsed the entire 2 + 3 before returning. This is how parentheses override precedence!

The Complete Parser Pipeline

Putting it all together:

Step 1: LEXER (Character → Tokens)
Input:  "(2 + 3) * 4"
Output: [LeftParen, Number(2), Plus, Number(3), RightParen, Star, Number(4), End]

Step 2: PARSER (Tokens → AST)
Input:  [LeftParen, Number(2), Plus, Number(3), RightParen, Star, Number(4), End]
Output:      Mul
            /   \
          Add    4
         /   \
        2     3

Step 3: EVALUATOR (AST → Result)
Input:  AST tree
Process:
  - Evaluate Add(2, 3) → 5
  - Evaluate Mul(5, 4) → 20
Output: 20

Why This Separation?

1. Lexer handles messy character-level details
2. Parser focuses on structure and meaning
3. Evaluator (or code generator, or interpreter) uses the clean AST

Each stage is simpler and more testable because of this separation!

Rust Programming Concepts for This Project

This project requires understanding several advanced Rust concepts related to memory management, lifetimes, and unsafe code. These concepts enable building high-performance systems that would be difficult or impossible in garbage-collected languages.

Lifetimes: Expressing Object Dependencies

The Problem: Rust needs to know how long references live to prevent dangling pointers. When we build a tree of references, we need to express that all the references share the same lifetime.

#![allow(unused)]
fn main() {
// This doesn't compile - lifetime unclear
struct TreeNode {
    left: &TreeNode,   // ❌ Error: missing lifetime
    right: &TreeNode,  // ❌ Error: missing lifetime
}

// This works - all references tied to 'tree lifetime
struct TreeNode<'tree> {
    left: &'tree TreeNode<'tree>,
    right: &'tree TreeNode<'tree>,
}
}

What is a Lifetime?

A lifetime is a compile-time annotation that tells Rust how long a reference is valid. It’s not a runtime concept—it exists purely for the compiler’s static analysis.

Lifetime Notation:

#![allow(unused)]
fn main() {
// 'arena is a lifetime parameter
// Read as: "apostrophe arena"
fn alloc<'arena>(&'arena self, value: T) -> &'arena T

// Multiple lifetimes
fn example<'a, 'b>(x: &'a i32, y: &'b i32) -> &'a i32
}

The Arena Lifetime Pattern:

In this project, all AST nodes live in an arena, and all references point into that arena:

#![allow(unused)]
fn main() {
#[derive(Debug, PartialEq)]
enum Expr<'arena> {
    Literal(i64),
    BinOp {
        op: OpType,
        left: &'arena Expr<'arena>,   // Reference valid for 'arena lifetime
        right: &'arena Expr<'arena>,  // Same lifetime
    },
}

struct Arena {
    storage: RefCell<Vec<u8>>,
}

impl Arena {
    fn alloc<'arena, T>(&'arena self, value: T) -> &'arena T {
        // Allocate T in arena, return reference with 'arena lifetime
        // The reference is valid as long as the arena exists
    }
}
}

Key Insight: The 'arena lifetime connects three things:

1. The arena itself - must live as long as 'arena
2. All allocated objects - stored in the arena
3. All references to objects - can’t outlive the arena

Why This Works:

#![allow(unused)]
fn main() {
{
    let arena = Arena::new_with_capacity(4 * 1024);           // Arena created
    let expr = build_tree(&arena);      // AST built in arena
    let result = expr.eval();           // Can use AST
    // arena dropped here, all references invalidated
}
// Can't use expr here - compiler prevents it!
}

What Lifetimes Prevent:

#![allow(unused)]
fn main() {
let dangling_ref = {
    let arena = Arena::new_with_capacity(4 * 1024);
    let expr = arena.alloc(Expr::Literal(42));
    expr  // ❌ Error: expr references arena, which is about to be dropped
};
// If this compiled, we'd have a dangling pointer!
}

Lifetime Elision (when you don’t see lifetimes):

Sometimes Rust infers lifetimes:

#![allow(unused)]
fn main() {
// Written:
fn first(x: &i32, y: &i32) -> &i32 { x }

// Compiler sees:
fn first<'a, 'b>(x: &'a i32, y: &'b i32) -> &'a i32 { x }
}

Why We Need Explicit Lifetimes for Arena:

Self-referential structures require explicit lifetime annotations because Rust can’t infer the relationship:

#![allow(unused)]
fn main() {
// Compiler can't infer these relationships automatically
enum Expr<'arena> {
    BinOp {
        left: &'arena Expr<'arena>,   // Must be explicit
        right: &'arena Expr<'arena>,
    }
}
}

RefCell: Interior Mutability for Arena

The Problem: The arena’s alloc() method takes &self (shared reference), but needs to modify the internal Vec<u8> storage.

#![allow(unused)]
fn main() {
impl Arena {
    fn alloc<T>(&self, value: T) -> &mut T {
        // Need to mutate storage, but only have &self!
        self.storage.push(value);  // ❌ Error: can't mutate through &self
    }
}
}

Why &self Instead of &mut self?

We need multiple references into the arena simultaneously:

#![allow(unused)]
fn main() {
let arena = Arena::new_with_capacity(4 * 1024);
let two = arena.alloc(Expr::Literal(2));      // Borrow 1
let three = arena.alloc(Expr::Literal(3));    // Borrow 2
let sum = arena.alloc(Expr::BinOp {
    op: Add,
    left: two,     // Still using borrow 1
    right: three,  // Still using borrow 2
});
}

With &mut self, we could only have one allocation at a time!

The Solution: RefCell:

#![allow(unused)]
fn main() {
use std::cell::RefCell;

struct Arena {
    storage: RefCell<Vec<u8>>,  // Interior mutability
}

impl Arena {
    fn alloc<T>(&self, value: T) -> &mut T {
        let mut storage = self.storage.borrow_mut();  // Get mutable borrow
        // ... modify storage ...
        // Borrow released when `storage` drops at end of function
    }
}
}

How RefCell Works:

• Compile-time: Allows mutation through &self
• Runtime: Tracks borrows dynamically, panics if rules violated
• Cost: Small overhead (~2-3 CPU cycles) for borrow checking

Borrow Rules (enforced at runtime):

• Multiple readers OR one writer
• Not both simultaneously

Example of RefCell Panic:

#![allow(unused)]
fn main() {
let arena = Arena::new_with_capacity(4 * 1024);
let storage1 = arena.storage.borrow_mut();  // Acquire write lock
let storage2 = arena.storage.borrow_mut();  // ❌ PANIC: already borrowed!
}

Why Our Code Is Safe:

Each alloc() call borrows, does its work, and releases before the next borrow:

#![allow(unused)]
fn main() {
fn alloc(&self, value: T) -> &mut T {
    {
        let mut storage = self.storage.borrow_mut();  // Borrow
        // ... work ...
    }  // Borrow released here

    // Return reference (points into arena, not into RefCell)
}
}

The returned reference points to data in the arena’s buffer, not the RefCell itself, so we can have many of them simultaneously.

Result Type: Structured Error Handling

The Problem: Parsing can fail in many ways—invalid syntax, unexpected tokens, division by zero. We need to propagate errors up the call stack with context.

#![allow(unused)]
fn main() {
// Bad: Using panic for expected failures
fn eval(expr: &Expr) -> i64 {
    match expr {
        Expr::BinOp { op: Div, right, .. } if right.eval() == 0 => {
            panic!("Division by zero");  // ❌ Too harsh!
        }
        // ...
    }
}

// Good: Using Result
fn eval(expr: &Expr) -> Result<i64, String> {
    match expr {
        Expr::BinOp { op: Div, left, right } => {
            let r = right.eval()?;  // Propagate error if any
            if r == 0 {
                return Err("Division by zero".to_string());
            }
            Ok(left.eval()? / r)
        }
        // ...
    }
}
}

Result Type Basics:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),      // Success case with value
    Err(E),     // Failure case with error
}
}

The ? Operator: Syntactic sugar for error propagation

#![allow(unused)]
fn main() {
// Without ?
let left_val = match left.eval() {
    Ok(v) => v,
    Err(e) => return Err(e),  // Propagate error
};

// With ? (equivalent)
let left_val = left.eval()?;
}

Our Error Types:

#![allow(unused)]
fn main() {
// Simple string errors (fine for learning project)
Result<i64, String>
Result<&'arena Expr<'arena>, String>
Result<Vec<Token>, String>

// Examples:
Err("Expected number, found '+'"to_string())
Err("Division by zero".to_string())
Err("Unmatched parenthesis".to_string())
}

Error Propagation in Parsing:

#![allow(unused)]
fn main() {
fn parse_expr(&mut self) -> Result<&'arena Expr<'arena>, String> {
    let left = self.parse_term()?;  // If error, return immediately

    while matches!(self.peek(), Token::Plus | Token::Minus) {
        let op = self.consume_op()?;
        let right = self.parse_term()?;
        left = self.builder.binary(op, left, right);
    }

    Ok(left)
}
}

If any nested call returns Err, it bubbles up through all the ? operators automatically!

Pattern Matching: Structural Decomposition

Pattern matching is Rust’s way of deconstructing enums and extracting data. This project uses it extensively.

Basic Enum Matching:

#![allow(unused)]
fn main() {
match expr {
    Expr::Literal(n) => Ok(*n),  // Extract the number
    Expr::BinOp { op, left, right } => {  // Extract all fields
        // Use op, left, right
    }
}
}

Matching Tokens in Parser:

#![allow(unused)]
fn main() {
match self.peek() {
    Token::Number(n) => {
        let n = *n;  // Copy the value
        self.advance();
        Ok(self.builder.literal(n))
    }
    Token::LeftParen => {
        self.advance();
        let expr = self.parse_expr()?;
        self.expect(Token::RightParen)?;
        Ok(expr)
    }
    token => Err(format!("Unexpected token: {:?}", token)),
}
}

Guards and Nested Patterns:

#![allow(unused)]
fn main() {
match token {
    Token::Plus | Token::Minus => OpType::Additive,  // Match either
    Token::Star | Token::Slash => OpType::Multiplicative,
    _ => unreachable!(),  // All other cases impossible here
}
}

Destructuring in Let Bindings:

#![allow(unused)]
fn main() {
let Expr::BinOp { op, left, right } = expr else {
    panic!("Expected binary operation");
};
}

—\

Arena Allocation: The Core Performance Technique

The Traditional Allocation Problem:

#![allow(unused)]
fn main() {
// Each Box::new() calls malloc() - expensive!
let expr = Box::new(BinOp {
    op: Add,
    left: Box::new(Literal(2)),      // malloc #1
    right: Box::new(Literal(3)),     // malloc #2
});                                   // malloc #3

// For expression (1+2)*(3+4):
// - 7 nodes = 7 malloc calls
// - Each malloc: ~50-100ns
// - Total: ~525ns just for allocation
}

The Arena Solution:

An arena allocator (also called bump allocator) pre-allocates a large chunk of memory and hands out pieces by incrementing a pointer.

#![allow(unused)]
fn main() {
struct Arena {
    storage: RefCell<Vec<u8>>,  // Big buffer of bytes
}

impl Arena {
    fn alloc<T>(&self, value: T) -> &mut T {
        // 1. Calculate size and alignment
        // 2. Bump pointer forward
        // 3. Write value at new position
        // 4. Return reference
        // Total: ~2-5ns (25x faster than malloc!)
    }
}
}

How Arena Allocation Works:

Initial state:
┌─────────────────────────────────────────┐
│ [empty buffer, 4096 bytes]              │
└─────────────────────────────────────────┘
 ↑
 position = 0

After alloc(42i64):
┌─────────────────────────────────────────┐
│ [42][empty space...]                    │
└─────────────────────────────────────────┘
     ↑
     position = 8 (size of i64)

After alloc(100i32):
┌─────────────────────────────────────────┐
│ [42][100][empty space...]               │
└─────────────────────────────────────────┘
         ↑
         position = 12 (8 + 4)

After alloc(Expr::Literal(5)):
┌─────────────────────────────────────────┐
│ [42][100][Literal(5)][empty space...]   │
└─────────────────────────────────────────┘
                     ↑
                     position = 12 + sizeof(Expr)

Key Characteristics:

1. Fast Allocation: Just pointer arithmetic and write

   #![allow(unused)]
   fn main() {
   // Pseudocode for allocation:
   let start = current_position;
   current_position += size;
   write_value_at(start, value);
   return reference_to(start);
   }

2. No Individual Deallocation: Can’t free single objects

   #![allow(unused)]
   fn main() {
   let arena = Arena::new_with_capacity(4 * 1024);
   let x = arena.alloc(42);
   // No way to free just x!
   // Drop arena → everything freed at once
   }

3. Perfect for Phase-Based Allocation: Allocate many objects, use them, discard all at once

   #![allow(unused)]
   fn main() {
   fn parse(input: &str) -> Result<i64, String> {
       let arena = Arena::new_with_capacity(4 * 1024);        // Create arena
       let ast = parse_to_ast(input, &arena);  // Allocate many nodes
       let result = eval(ast);          // Use AST
       Ok(result)
       // arena dropped here → all nodes freed instantly
   }
   }

4. Better Cache Locality: Objects allocated sequentially are stored sequentially

   Box allocations (scattered in memory):
   Node1 @ 0x1000, Node2 @ 0x5000, Node3 @ 0x2000  ← Cache misses!
   
   Arena allocations (contiguous):
   Node1 @ 0x1000, Node2 @ 0x1018, Node3 @ 0x1030  ← Cache hits!
   

Performance Comparison:

When to Use Arena Allocation:

✅ Good fit:

• Parsing (ASTs, JSON, XML)
• Compilers (IR nodes, symbol tables)
• Game engines (per-frame objects)
• Request handlers (per-request temps)
• Any “allocate many, free all” pattern

❌ Bad fit:

• Long-lived objects with individual lifecycles
• Objects that need to be freed independently
• Incremental data structures (growing over time)

Memory Alignment: Why It Matters

The Problem: CPUs require certain types to be stored at addresses that are multiples of their size. Misaligned access can crash (ARM) or be slow (x86).

#![allow(unused)]
fn main() {
// Good: u64 at address 0x1000 (8-byte aligned)
// Bad:  u64 at address 0x1001 (not 8-byte aligned) → CRASH or 2x slower!
}

Alignment Requirements:

Why Alignment in Arena Allocation:

When we bump allocate, we must ensure each allocation is properly aligned:

#![allow(unused)]
fn main() {
fn alloc<T>(&self, value: T) -> &mut T {
    let size = std::mem::size_of::<T>();
    let align = std::mem::align_of::<T>();  // e.g., 8 for u64

    let current_len = self.storage.borrow().len();

    // Calculate padding needed for alignment
    let padding = (align - (current_len % align)) % align;
    let start = current_len + padding;  // Now aligned!

    // ... allocate at start ...
}
}

Example Calculation:

Current position: 13 (after allocating u8 at 12)
Want to allocate u64 (needs 8-byte alignment)

current_len = 13
align = 8
current_len % align = 13 % 8 = 5
padding = (8 - 5) % 8 = 3

start = 13 + 3 = 16 (divisible by 8 ✓)

Memory layout:
┌────────────────────────────────────┐
│ [prev][X][X][X][u64 goes here...]  │
└────────────────────────────────────┘
        ^pad^    ^16 (aligned)

The Modulo Formula:

#![allow(unused)]
fn main() {
let padding = (align - (current_len % align)) % align;
}

Why the second % align? Handle the case when already aligned:

current_len = 16, align = 8
16 % 8 = 0  (already aligned)
(8 - 0) % 8 = 0  (no padding needed) ✓

Without the second %:
(8 - 0) = 8  (would add unnecessary padding!) ✗

Unsafe Rust: Working with Raw Pointers

Why We Need Unsafe:

Rust’s safety guarantees rely on the borrow checker. But arena allocation requires operations the borrow checker can’t verify:

• Converting raw bytes to typed references
• Writing to uninitialized memory
• Extending reference lifetimes

The Unsafe Operations We Use:

1. std::ptr::write: Write a value to a raw pointer without reading the old value (for uninitialized memory)

#![allow(unused)]
fn main() {
unsafe {
    std::ptr::write(ptr, value);  // Write value to ptr
    // Doesn't call Drop on old value (because there isn't one!)
}
}

vs. normal assignment:

#![allow(unused)]
fn main() {
*ptr = value;  // Reads old value, calls Drop, then writes new value
}

2. Raw pointer casting: Convert between pointer types

#![allow(unused)]
fn main() {
let byte_ptr: *mut u8 = &mut storage[start];
let typed_ptr: *mut T = byte_ptr as *mut T;  // Cast to correct type
}

3. Dereferencing raw pointers: Access data through raw pointer

#![allow(unused)]
fn main() {
unsafe {
    let reference: &mut T = &mut *typed_ptr;  // Create reference
}
}

Our Arena Allocation (with unsafe):

#![allow(unused)]
fn main() {
fn alloc<T>(&self, value: T) -> &mut T {
    let mut storage = self.storage.borrow_mut();

    // Safe: size and alignment calculation
    let size = std::mem::size_of::<T>();
    let align = std::mem::align_of::<T>();

    // Safe: calculating aligned position
    let current_len = storage.len();
    let padding = (align - (current_len % align)) % align;
    let start = current_len + padding;

    // Safe: resizing buffer
    storage.resize(start + size, 0);

    // UNSAFE: Casting bytes to typed pointer
    let ptr = &mut storage[start] as *mut u8 as *mut T;

    unsafe {
        // UNSAFE: Writing to uninitialized memory
        std::ptr::write(ptr, value);

        // UNSAFE: Creating reference from raw pointer
        &mut *ptr
    }
}
}

Why Each unsafe Is Safe (programmer reasoning):

1. Casting: We ensured start is aligned for T, so ptr is valid
2. std::ptr::write: We resized storage to have space, so ptr points to valid memory
3. Creating reference: The memory contains a valid T (we just wrote it), and the lifetime is tied to the arena

The Contract:

When you write unsafe, you’re telling the compiler: “I’ve verified these safety properties manually. Trust me.”

What Could Go Wrong (if we make mistakes):

#![allow(unused)]
fn main() {
// Bug 1: Forget to align → CRASH
let ptr = &mut storage[current_len] as *mut u8 as *mut T;  // Not aligned!

// Bug 2: Not enough space → CORRUPTION
// storage.resize(start + size, 0);  // Forgot this line!
unsafe { std::ptr::write(ptr, value); }  // Writes past end of buffer!

// Bug 3: Use after free → UNDEFINED BEHAVIOR
let expr = {
    let arena = Arena::new_with_capacity(4 * 1024);
    arena.alloc(Expr::Literal(42))
};  // arena dropped, but expr still references it!
}

Guidelines for Unsafe Code:

1. Minimize unsafe blocks: Keep them small and well-commented
2. Document invariants: Explain why the unsafe code is safe
3. Test thoroughly: Unsafe bugs can be silent (corruption, not crashes)
4. Use tools: Miri can detect some undefined behavior

Performance Concepts: Why Arena Wins

Cache Locality:

Modern CPUs have a memory hierarchy. Accessing RAM is ~100x slower than L1 cache. Arena allocation keeps related objects close together in memory.

Box allocations:
Node1 @ 0x1000 → Node2 @ 0x8000 → Node3 @ 0x2000
Each access: likely cache miss (~100 cycles)

Arena allocations:
Node1 @ 0x1000 → Node2 @ 0x1018 → Node3 @ 0x1030
All in same cache line (~4 cycles after first load)

Allocation Overhead:

#![allow(unused)]
fn main() {
// Box<T>: Global allocator
Box::new(value)
  → lock allocator mutex (~10ns)
  → find free block (~20ns)
  → update metadata (~10ns)
  → unlock mutex (~10ns)
  Total: ~50-100ns

// Arena: Bump allocator
arena.alloc(value)
  → calculate position (~1ns)
  → write value (~1ns)
  → return reference (~1ns)
  Total: ~2-5ns

Speedup: 25x per allocation!
}

Deallocation Overhead:

#![allow(unused)]
fn main() {
// Box<T>: Individual drops
drop(box1);  // ~50ns
drop(box2);  // ~50ns
drop(box3);  // ~50ns
// ... thousands of drops

// Arena: Bulk free
drop(arena);  // ~10ns total
// OS reclaims entire buffer at once
}

When running the benchmarks (available in the Complete Code Example)

=== Performance Comparison: Box vs Arena ===
Box allocation   : 276.513458ms
Arena allocation : 125.069875ms
Arena speedup    : 2.21x faster
============================================


=== Bulk Deallocation Benchmark ===
Building 10000 trees with 2047 nodes each

Box (alloc + 2047 deallocations/tree): 470.23ms
Arena (reused, O(1) reset):          197.782541ms
Arena speedup: 2.38x faster
===================================

Connection to This Project

In this project, you’ll implement the complete pipeline:

1. Milestone 1-2: Define AST types (Expr enum)
2. Milestone 3-4: Optimize AST allocation with arena (bump allocator)
3. Milestone 5: Build the lexer to convert text to tokens
4. Milestone 6: Implement recursive descent parser
5. Milestone 7: Compare performance with traditional allocation

Build The Project

Milestone 1: Define AST Types

Create the expression tree data structures that represent arithmetic expressions.

Architecture:

• enum: Expr - Expression Type

  • field: Literal - literal number
  • field: BinOp - needs to store: the operator and left and right sub-expressions

• enum: OpType - Operator Type

  • field: Add - addition
  • field: Sub - subtraction
  • field: Mul - multiplication
  • field: Div - division

functions:

• eval() method on OpType that takes two numbers and returns the result
  • Handle division by zero by returning a Result<i64, String>
• eval() method on Expr that recursively evaluates the expression tree
  • For binary operations, evaluate both sides first, then apply the operator

Design Hints:

• Think about what variants your Expr enum needs
• Consider what data each variant should hold
• Remember that references in the tree need a lifetime annotation
• Binary operations need to store three pieces of information

Implementation Hints:

• Use pattern matching to handle different expression types
• For recursive evaluation, use the ? operator to propagate errors
• Return appropriate error messages for invalid operations

Starter Code:

#![allow(unused)]
fn main() {
#[derive(Debug, PartialEq)]
enum Expr<'arena> {
   // TODO: literal, binary expression
}

#[derive(Debug, PartialEq, Clone, Copy)]
enum OpType {
    // TODO: basic math operators
}

impl OpType {
    fn eval(&self, left: i64, right: i64) -> Result<i64, String> {
        match self {
           // TODO: calculate 
        }
    }
}
}

Add evaluation:

#![allow(unused)]
fn main() {
impl<'arena> Expr<'arena> {
    fn eval(&self) -> Result<i64, String> {
        match self {
            // TODO:  recursive call of eval() on left and right
        }
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_literal_eval() {
    let expr = Expr::Literal(42);
    assert_eq!(expr.eval(), Ok(42));
}

#[test]
fn test_binop_eval() {
    let left = Expr::Literal(10);
    let right = Expr::Literal(5);
    let expr = Expr::BinOp {
        op: OpType::Add,
        left: &left,
        right: &right,
    };
    assert_eq!(expr.eval(), Ok(15));
}

#[test]
fn test_nested_eval() {
    // (2 + 3) * 4 = 20
    let two = Expr::Literal(2);
    let three = Expr::Literal(3);
    let four = Expr::Literal(4);

    let add = Expr::BinOp {
        op: OpType::Add,
        left: &two,
        right: &three,
    };

    let mul = Expr::BinOp {
        op: OpType::Mul,
        left: &add,
        right: &four,
    };

    assert_eq!(mul.eval(), Ok(20));
}

#[test]
fn test_division_by_zero() {
    let ten = Expr::Literal(10);
    let zero = Expr::Literal(0);
    let expr = Expr::BinOp {
        op: OpType::Div,
        left: &ten,
        right: &zero,
    };
    assert!(expr.eval().is_err());
}
}

Check Your Understanding:

• What does the 'arena lifetime mean?
• Why do we use &'arena Expr<'arena> instead of Box<Expr>?
• How does the recursive eval() work?

Why Milestone 1 Isn’t Enough

Limitation: We’ve defined the types, but how do we actually create these AST nodes? Using stack allocation limits us to small, fixed-size trees. We need heap allocation.

What we’re adding: First, we’ll implement the traditional Box approach to understand the baseline, later on we will optimize with arena allocation.

Milestone 2: Box-Based Expression Trees

Implement expressions using Box<Expr> the traditional heap allocation.

Architecture:

• Each AST node gets its own heap allocation via Box::new()
• Each node has its own drop when the tree is freed
• This is the “normal” approach used in many programming languages

Design Changes: Instead of using references with lifetimes for left and right, we’ll use Box pointers. And we will use the builder pattern to simplify AST node creation.

solution

#![allow(unused)]
fn main() {
#[derive(Debug, PartialEq)]
enum BoxExpr {
    // TODO: literal, binary operator
}

impl BoxExpr {
    fn eval(&self) -> Result<i64, String> {
        match self {
            // TODO:  recursive call of eval() on left and right
        }
    }
}
}

Builder Pattern:

#![allow(unused)]
fn main() {
struct BoxExprBuilder;

impl BoxExprBuilder {
    fn literal(n: i64) -> Box<BoxExpr> {
        todo!()
    }

    fn binary(op: OpType, left: Box<BoxExpr>, right: Box<BoxExpr>) -> Box<BoxExpr> {
        todo!()
    }

    fn add(left: Box<BoxExpr>, right: Box<BoxExpr>) -> Box<BoxExpr> {
        todo!()
    }

    fn sub(left: Box<BoxExpr>, right: Box<BoxExpr>) -> Box<BoxExpr> {
        todo!()
    }

    fn mul(left: Box<BoxExpr>, right: Box<BoxExpr>) -> Box<BoxExpr> {
        todo!()
    }

    fn div(left: Box<BoxExpr>, right: Box<BoxExpr>) -> Box<BoxExpr> {
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_box_expr_literal() {
    let expr = BoxExprBuilder::literal(42);
    assert_eq!(expr.eval(), Ok(42));
}

#[test]
fn test_box_expr_addition() {
    let expr = BoxExprBuilder::add(
        BoxExprBuilder::literal(10),
        BoxExprBuilder::literal(5),
    );
    assert_eq!(expr.eval(), Ok(15));
}

#[test]
fn test_box_expr_nested() {
    // Build: (2 + 3) * 4 = 20
    let expr = BoxExprBuilder::mul(
        BoxExprBuilder::add(
            BoxExprBuilder::literal(2),
            BoxExprBuilder::literal(3),
        ),
        BoxExprBuilder::literal(4),
    );
    assert_eq!(expr.eval(), Ok(20));
}

#[test]
fn test_box_expr_complex() {
    // Build: ((10 - 5) * 2) + (8 / 4) = 12
    let expr = BoxExprBuilder::add(
        BoxExprBuilder::mul(
            BoxExprBuilder::sub(
                BoxExprBuilder::literal(10),
                BoxExprBuilder::literal(5),
            ),
            BoxExprBuilder::literal(2),
        ),
        BoxExprBuilder::div(
            BoxExprBuilder::literal(8),
            BoxExprBuilder::literal(4),
        ),
    );
    assert_eq!(expr.eval(), Ok(12));
}
}

Check Your Understanding:

• How many heap allocations occur for the expression (2 + 3) * 4?
• What happens when a Box<BoxExpr> goes out of scope?
• Why does the builder consume (take ownership of) the Box parameters?
• What are the performance implications of many small allocations?

Why Milestone 2 Isn’t Enough

Performance Problem: Every single AST node requires a separate heap allocation with Box::new(). Let’s analyze the cost:

Allocation Overhead:

• Expression (1+2)*(3+4) = 7 nodes
• Each Box::new(): ~50-100ns (involves malloc, locks, metadata)
• Total allocation time: 7 × 75ns = 525ns just for allocations
• Parsing 10,000 expressions: 70,000 allocations = 5.25ms

Memory Fragmentation:

• Nodes scattered across heap memory
• Poor cache locality (next node likely in different cache line)
• Each allocation has ~16 bytes overhead for allocator metadata

What we’re adding: Arena allocator - bump allocation strategy: How it works at a glance:

1. Reserve a big chunk of memory (e.g., 4 KB).
2. Keep an offset (the “bump” pointer) into that chunk.
3. To allocate T, round the offset up to align_of::<T>(), ensure there’s room, then return a pointer/reference to that slot and advance the offset by size_of::<T>().
4. When the arena goes out of scope, the whole chunk is freed at once.

`Why use it for ASTs and similar graphs:

• Many small nodes created together and dropped together at the end of parsing/evaluation.
• Significantly fewer calls to the global allocator → better performance and cache locality.`

Improvements:

• Speed: Allocation is pointer increment (~2-5ns) vs malloc (~75ns) = 25x faster
• Memory: Better cache locality (nodes allocated sequentially)
• Simplicity: No individual frees—drop arena, free everything
• Alignment: Must handle properly (u8 at any address, u64 needs 8-byte alignment)

Complexity trade-off: Can’t free individual objects. Only works when all objects have same lifetime.

Milestone 3: Simple Bump Allocator

Implement a basic arena that can allocate objects.

Architecture

• struct: Arena
  • field: storage: RefCell<Vec> functions:
• new()
• alloc()

Starter Code:

#![allow(unused)]
fn main() {
use std::cell::RefCell;
use std::ptr::NonNull;

struct Arena {
    // TODO: storage
}

impl Arena {
    fn new() -> Self {
        Arena {
            // refcell -> vec -> 4k = 4096
        }
    }

    fn alloc<T>(&self, value: T) -> &mut T {
        let mut storage = self.storage.borrow_mut();

        // TODO: Calculate size and alignment using std::mem functions
        let size = todo!("Get size of T");
        let align = todo!("Get alignment of T");

        // TODO: Get current position in storage
        let current_len = todo!();

        // TODO: Calculate aligned position
        // Hint: padding = (align - (current_len % align)) % align
        let padding = todo!();
        let start = todo!("current_len + padding");

        // TODO: Ensure we have space in storage
        // Hint: Use storage.resize(start + size, 0)

        // TODO: Get pointer to allocated space
        // Hint: &mut storage[start] as *mut u8 as *mut T
        let ptr = todo!();

        unsafe {
            // TODO: Write value to allocated space using std::ptr::write
            // TODO: Return mutable reference with arena lifetime
        }
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_arena_alloc_int() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let x = arena.alloc(42);
    assert_eq!(*x, 42);
}

#[test]
fn test_arena_multiple_allocs() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let x = arena.alloc(1);
    let y = arena.alloc(2);
    let z = arena.alloc(3);

    assert_eq!(*x, 1);
    assert_eq!(*y, 2);
    assert_eq!(*z, 3);
}

#[test]
fn test_arena_alloc_string() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let s = arena.alloc(String::from("hello"));
    assert_eq!(s, "hello");
}

#[test]
fn test_arena_alignment() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let _byte = arena.alloc(1u8);
    let num = arena.alloc(1234u64);  // Needs 8-byte alignment

    let ptr = num as *const u64 as usize;
    assert_eq!(ptr % 8, 0, "u64 should be 8-byte aligned");
}
}

Check Your Understanding:

• Why do we need alignment?
• What does std::ptr::write do?
• Why is the function marked unsafe?
• What lifetime does the returned reference have?

Milestone 4: Build Expressions in Arena

Use the arena allocator to create expression trees with the builder pattern.

Now that we have a working arena allocator (Milestone 3), we need a clean API to use it. Directly calling arena.alloc() everywhere would be verbose and error-prone. The Builder Pattern provides a fluent, type-safe interface for constructing expression trees.

What We’re Building:

The ExprBuilder wraps the arena and provides convenient methods like literal(), add(), mul() that hide the allocation details. Compare:

#![allow(unused)]
fn main() {
// Without builder (verbose, easy to mess up lifetimes):
let two = arena.alloc(Expr::Literal(2));
let three = arena.alloc(Expr::Literal(3));
let sum = arena.alloc(Expr::BinOp {
    op: OpType::Add,
    left: two,
    right: three,
});

// With builder (clean, fluent):
let two = builder.literal(2);
let three = builder.literal(3);
let sum = builder.add(two, three);
}

Design Decisions:

1. Builder holds &'arena Arena: The builder doesn’t own the arena—it just borrows it. This allows multiple builders to share one arena if needed.

2. All methods return &'arena Expr<'arena>: Every expression we allocate lives in the arena, and the lifetime annotation ensures they can’t outlive it.

3. Convenience methods (add, mul, etc.): These wrap the generic binary() method, making expression construction more readable.

The Lifetime Dance:

Notice the signature: fn literal(&self, n: i64) -> &'arena Expr<'arena>. We take &self (short borrow of builder), but return &'arena (long-lived reference tied to arena’s lifetime). This works because:

• The builder holds &'arena Arena
• We allocate in that arena
• The returned reference lives as long as the arena, not the builder

Architecture

• Struct: ExprBuilder<'arena>
  • Fields: arena: &'arena Arena Functions:
• new(arena: &'arena Arena) -> Self - Creates builder wrapping arena
• literal(&self, n: i64) -> &'arena Expr<'arena> - Allocates literal expression
• binary(&self, op: OpType, left: &'arena Expr<'arena>, right: &'arena Expr<'arena>) -> &'arena Expr<'arena> - Generic binary operation
• add(...), sub(...), mul(...), div(...) - Convenience wrappers

Starter Code:

#![allow(unused)]
fn main() {
struct ExprBuilder<'arena> {
    arena: &'arena Arena,
}

impl<'arena> ExprBuilder<'arena> {
    fn new(arena: &'arena Arena) -> Self {
        // TODO: Create ExprBuilder with reference to arena
        todo!()
    }

    fn literal(&self, n: i64) -> &'arena Expr<'arena> {
        // TODO: Allocate Expr::Literal(n) in arena and return reference
        todo!()
    }

    fn binary(
        &self,
        op: OpType,
        left: &'arena Expr<'arena>,
        right: &'arena Expr<'arena>,
    ) -> &'arena Expr<'arena> {
        // TODO: Allocate Expr::BinOp in arena with given op, left, right
        todo!()
    }

    fn add(
        &self,
        left: &'arena Expr<'arena>,
        right: &'arena Expr<'arena>,
    ) -> &'arena Expr<'arena> {
        // TODO: Call binary() with OpType::Add
        todo!()
    }

    // TODO: Add methods for sub, mul, div following the same pattern
    fn sub(&self, left: &'arena Expr<'arena>, right: &'arena Expr<'arena>) -> &'arena Expr<'arena> {
        todo!()
    }

    fn mul(&self, left: &'arena Expr<'arena>, right: &'arena Expr<'arena>) -> &'arena Expr<'arena> {
        todo!()
    }

    fn div(&self, left: &'arena Expr<'arena>, right: &'arena Expr<'arena>) -> &'arena Expr<'arena> {
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_builder() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let builder = ExprBuilder::new(&arena);

    // Build: (2 + 3) * 4
    let two = builder.literal(2);
    let three = builder.literal(3);
    let four = builder.literal(4);

    let sum = builder.add(two, three);
    let product = builder.mul(sum, four);

    assert_eq!(product.eval(), Ok(20));
}

#[test]
fn test_complex_expression() {
    let arena = Arena::new_with_capacity(4 * 1024);
    let builder = ExprBuilder::new(&arena);

    // Build: ((10 - 5) * 2) + (8 / 4)
    let expr = builder.add(
        builder.mul(
            builder.sub(builder.literal(10), builder.literal(5)),
            builder.literal(2)
        ),
        builder.div(builder.literal(8), builder.literal(4))
    );

    assert_eq!(expr.eval(), Ok(12)); // (5 * 2) + 2 = 12
}
}

Check Your Understanding:

• Why does the builder need a reference to the arena?
• Can expressions outlive the arena?
• How many heap allocations happen for a 3-node tree?

Milestone 5: Lexer (Tokenizer)

Transform raw text input into a stream of tokens that the parser can work with.

So far, we’ve been manually constructing expression trees using the builder. But real parsers work with text input like "(2 + 3) * 4". The lexer (also called tokenizer or scanner) is the first stage of parsing that breaks this text into meaningful chunks called tokens.

The Two-Stage Pipeline:

Text → Lexer → Tokens → Parser → AST
"2+3"  →       [Num(2), Plus, Num(3)]  →  BinOp{Add, 2, 3}

Separating lexing from parsing is a fundamental compiler design pattern because:

1. Separation of concerns: Lexing handles character-level details (whitespace, digits), parsing handles structure (precedence, grammar)
2. Simplification: Parser doesn’t worry about whitespace or number parsing
3. Reusability: Same token stream can feed multiple parsers
4. Performance: Can optimize lexer separately (e.g., SIMD for digit scanning)

What We’re Building:

A Lexer that walks through input text character-by-character and identifies:

• Numbers: Sequences of digits like 123, 0, 9876
• Operators: +, -, *, /
• Parentheses: (, )
• Whitespace: Skipped (not significant in arithmetic)
• End of input: Special End token

The Lexer State:

#![allow(unused)]
fn main() {
struct Lexer {
    input: Vec<char>,   // Input text as characters
    position: usize,    // Current position in input
}
}

We convert the string to Vec<char> because:

• Easy indexing by character (not byte)
• Handles multi-byte Unicode properly (though our grammar is ASCII-only)
• Simple position counter tracks where we are

functions:

• peek() - Look at current character without moving forward
• advance() - Move position forward by one character
• skip_whitespace() - Skip spaces, tabs, newlines
• read_number() - Consume consecutive digits and build an integer
• next_token() - Return the next token from input
• tokenize() - Convert entire input to Vec<Token>

Example Tokenization:

#![allow(unused)]
fn main() {
Input: "(10 + 5) * 2"

Steps:
1. Skip nothing, see '(' → Token::LeftParen, advance
2. Skip space, see '1' → read_number() → Token::Number(10), advance twice
3. Skip space, see '+' → Token::Plus, advance
4. Skip space, see '5' → read_number() → Token::Number(5), advance
5. Skip nothing, see ')' → Token::RightParen, advance
6. Skip space, see '*' → Token::Star, advance
7. Skip space, see '2' → read_number() → Token::Number(2), advance
8. At end → Token::End

Output: [LeftParen, Number(10), Plus, Number(5), RightParen, Star, Number(2), End]
}

Error Handling:

The lexer must detect invalid characters:

#![allow(unused)]
fn main() {
Input: "2 & 3"  // '&' is not a valid operator
Result: Err("Unexpected character '&'")
}

Returning Result<Token, String> allows propagating errors up to the caller.

Starter Code:

#![allow(unused)]
fn main() {
#[derive(Debug, PartialEq, Clone)]
enum Token {
    Number(i64),
    Plus,
    Minus,
    Star,
    Slash,
    LeftParen,
    RightParen,
    End,
}

struct Lexer {
    input: Vec<char>,
    position: usize,
}

impl Lexer {
    fn new(input: &str) -> Self {
        // TODO: Create Lexer with input converted to Vec<char> and position 0
    }

    fn peek(&self) -> Option<char> {
        // TODO: Return the character at current position (or None if at end)
    }

    fn advance(&mut self) {
        // TODO: Increment position by 1
    }

    fn skip_whitespace(&mut self) {
        // TODO: Loop while current character is whitespace
        // Hint: Use peek() and ch.is_whitespace(), call advance() for each whitespace
        todo!()
    }

    fn read_number(&mut self) -> i64 {
        // TODO: Build up a number by reading consecutive digits
        // Hint: Start with num = 0, for each digit: num = num * 10 + digit_value
        // Use ch.is_ascii_digit() to check, convert with (ch as i64 - '0' as i64)
        todo!()
    }

    fn next_token(&mut self) -> Result<Token, String> {
        // TODO: Skip whitespace first
        todo!();

        // TODO: Match on peek() to determine token type
        // - None → Token::End
        // - '0'..='9' → Token::Number(self.read_number())
        // - '+' → advance and return Token::Plus
        // - '-' → advance and return Token::Minus
        // - '*' → advance and return Token::Star
        // - '/' → advance and return Token::Slash
        // - '(' → advance and return Token::LeftParen
        // - ')' → advance and return Token::RightParen
        // - anything else → Err with message
        todo!()
    }

    fn tokenize(&mut self) -> Result<Vec<Token>, String> {
        // TODO: Create empty Vec for tokens
        // TODO: Loop calling next_token() until Token::End
        // TODO: Push each token to Vec (including End token), then break
        // TODO: Return Ok(tokens)
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_lexer_numbers() {
    let mut lexer = Lexer::new("123 456");
    assert_eq!(lexer.next_token(), Ok(Token::Number(123)));
    assert_eq!(lexer.next_token(), Ok(Token::Number(456)));
    assert_eq!(lexer.next_token(), Ok(Token::End));
}

#[test]
fn test_lexer_operators() {
    let mut lexer = Lexer::new("+ - * /");
    assert_eq!(lexer.next_token(), Ok(Token::Plus));
    assert_eq!(lexer.next_token(), Ok(Token::Minus));
    assert_eq!(lexer.next_token(), Ok(Token::Star));
    assert_eq!(lexer.next_token(), Ok(Token::Slash));
}

#[test]
fn test_lexer_expression() {
    let mut lexer = Lexer::new("(2 + 3) * 4");
    let tokens = lexer.tokenize().unwrap();
    assert_eq!(tokens, vec![
        Token::LeftParen,
        Token::Number(2),
        Token::Plus,
        Token::Number(3),
        Token::RightParen,
        Token::Star,
        Token::Number(4),
        Token::End,
    ]);
}

#[test]
fn test_lexer_error() {
    let mut lexer = Lexer::new("2 & 3");
    assert!(lexer.tokenize().is_err());
}
}

Check Your Understanding:

• Why do we skip whitespace?
• How does read_number() build up the number?
• What happens if we forget to advance() after a token?

Milestone 6: Recursive Descent Parser

Transform the token stream from the lexer into an Abstract Syntax Tree (AST) stored in the arena, respecting operator precedence and parentheses.

The parser is the brain of the compiler—it understands the structure and meaning of code. While the lexer breaks text into tokens, the parser answers questions like:

• Does 2 + 3 * 4 mean (2 + 3) * 4 or 2 + (3 * 4)? (Answer: second one, multiplication binds tighter)
• Are the parentheses balanced in ((1 + 2) * 3? (Answer: no, missing closing paren)
• Is + + 3 valid? (Answer: no, can’t have two operators in a row)

Complete Pipeline:

Text → Lexer → Tokens → Parser → AST → Evaluator → Result
"2+3*4" →  [Num(2), Plus, Num(3), Star, Num(4)]  →
           BinOp{Add, 2, BinOp{Mul, 3, 4}}  →  14

Recursive Descent Parsing:

We’ll implement a recursive descent parser, which means:

1. Each grammar rule becomes a function
2. Functions call each other recursively to match nested structures
3. The call stack mirrors the parse tree structure

This is one of the simplest and most intuitive parsing techniques. Other approaches (LR, LALR, Pratt parsing) are more powerful but complex.

The Grammar and Operator Precedence:

Our grammar has three levels to encode operator precedence:

Expr   → Term (('+' | '-') Term)*      // Lowest precedence: addition/subtraction
Term   → Factor (('*' | '/') Factor)*  // Medium precedence: multiplication/division
Factor → Number | '(' Expr ')'         // Highest precedence: atoms and parens

Why three levels? This encodes the precedence rules:

• Factor (highest): Numbers and parenthesized expressions bind tightest
• Term (medium): * and / bind tighter than + and -
• Expr (lowest): + and - bind loosest

How Precedence Works:

For 2 + 3 * 4:

parse_expr() calls:
  parse_term() for "2"
    parse_factor() returns Literal(2)
  Sees '+', continues
  parse_term() for "3 * 4"
    parse_factor() returns Literal(3)
    Sees '*', continues
    parse_factor() returns Literal(4)
    Returns Mul(3, 4)
  Returns Add(2, Mul(3, 4))

Notice: parse_term() consumed 3 * 4 as a unit before returning to parse_expr(). This is how multiplication binds tighter than addition!

Parsing Strategy for Each Level:

1. parse_expr(): Parse a term, then loop consuming + or - operators

   2 + 3 - 4  →  Sub(Add(2, 3), 4)
   

2. parse_term(): Parse a factor, then loop consuming * or / operators

   2 * 3 / 4  →  Div(Mul(2, 3), 4)
   

3. parse_factor(): Parse atomic elements

   • If number: return literal
   • If (: recursively parse expression, expect )
   • Otherwise: error

Architecture:

#![allow(unused)]
fn main() {
struct Parser<'arena> {
    tokens: Vec<Token>,           // All tokens from lexer
    position: usize,              // Current position in token stream
    builder: ExprBuilder<'arena>, // For allocating AST nodes in arena
}
}

functions:

• peek() - Look at current token without advancing
• advance() - Move to next token
• expect(token) - Verify current token matches expected, advance, or error
• parse_factor() - Parse numbers and parenthesized expressions
• parse_term() - Parse multiplication and division
• parse_expr() - Parse addition and subtraction
• parse() - Entry point that parses and verifies we consumed all tokens

Detailed Example: Parsing (2 + 3) * 4:

Tokens: [LeftParen, Number(2), Plus, Number(3), RightParen, Star, Number(4), End]

parse() calls parse_expr():
  parse_expr() calls parse_term():
    parse_term() calls parse_factor():
      See '(' → advance, call parse_expr() recursively:
        parse_expr() calls parse_term():
          parse_term() calls parse_factor():
            See Number(2) → return Literal(2)
          No '*' or '/', return Literal(2)
        See '+', advance, call parse_term():
          parse_term() calls parse_factor():
            See Number(3) → return Literal(3)
          No '*' or '/', return Literal(3)
        Build Add(Literal(2), Literal(3))
      Expect ')' → found it, advance
      Return Add(2, 3)
    See '*', advance, call parse_factor():
      See Number(4) → return Literal(4)
    Build Mul(Add(2, 3), Literal(4))
  No '+' or '-', return Mul(...)
parse() verifies Token::End

Result: Mul(Add(2, 3), 4)

Error Handling:

The parser must catch:

• Unexpected tokens: 2 + + 3 (two operators)
• Missing operands: 2 + (nothing after +)
• Unbalanced parens: (2 + 3 (missing closing paren)
• Trailing input: 2 + 3 4 (unexpected 4 at end)

All parse functions return Result<&'arena Expr<'arena>, String> to propagate errors.

Why Recursive Descent?

Advantages:

• Simple: Each grammar rule = one function
• Clear error messages: Know exactly where parsing failed
• Debuggable: Can step through and see call stack
• Hand-optimizable: Can add special cases for performance
• No external tools: No parser generator needed

Disadvantages:

• Left recursion: Can’t handle grammars like Expr → Expr '+' Term (infinite loop)
• Backtracking: Inefficient for ambiguous grammars (not our case)
• Grammar restrictions: Not all grammars work

The Connection to Arena Allocation:

Notice: The parser allocates many AST nodes while parsing. With arena allocation:

• Each node: 1 arena bump (~3ns)
• Total for (2+3)*4: 5 nodes = ~15ns allocation time
• With Box: 5 mallocs = ~375ns

For complex expressions with hundreds of nodes, the arena speedup is dramatic!

Grammar:

Expr   → Term (('+' | '-') Term)*
Term   → Factor (('*' | '/') Factor)*
Factor → Number | '(' Expr ')'

Starter Code:

#![allow(unused)]
fn main() {
struct Parser<'arena> {
    tokens: Vec<Token>,
    position: usize,
    builder: ExprBuilder<'arena>,
}

impl<'arena> Parser<'arena> {
    fn new(tokens: Vec<Token>, arena: &'arena Arena) -> Self {
        // TODO:`Create Parser
    }

    fn peek(&self) -> &Token {
        // TODO: Give position or END
    }

    fn advance(&mut self) {
        // TODO: increment
    }

    fn expect(&mut self, expected: Token) -> Result<(), String> {
        // TODO: if current is expected, advance and return Ok, else return Err
    }

    // Factor → Number | '(' Expr ')'
    fn parse_factor(&mut self) -> Result<&'arena Expr<'arena>, String> {
        match self.peek() {
            Token::Number(n) => {
                todo!()
            }
            Token::LeftParen => {
                todo!()
            }
            token => Err(format!("Expected number or '(', found {:?}", token)),
        }
    }

    // Term → Factor (('*' | '/') Factor)*
    fn parse_term(&mut self) -> Result<&'arena Expr<'arena>, String> {
        let mut left = self.parse_factor()?;

        loop {
            match self.peek() {
                Token::Star => {
                    todo!()
                }
                Token::Slash => {
                    todo!()
                }
                _ => break,
            }
        }

        Ok(left)
    }

    // Expr → Term (('+' | '-') Term)*
    fn parse_expr(&mut self) -> Result<&'arena Expr<'arena>, String> {
        // TODO: Similar to parse_term but for + and -
        // Start with parse_term(), then loop handling + and -
        todo!()
    }

    fn parse(&mut self) -> Result<&'arena Expr<'arena>, String> {
        let expr = self.parse_expr()?;
        if self.peek() != &Token::End {
            return Err(format!("Unexpected token: {:?}", self.peek()));
        }
        Ok(expr)
    }
}

// Helper function
fn parse_and_eval(input: &str) -> Result<i64, String> {
    let arena = Arena::new_with_capacity(4 * 1024);
    let mut lexer = Lexer::new(input);
    let tokens = lexer.tokenize()?;
    let mut parser = Parser::new(tokens, &arena);
    let expr = parser.parse()?;
    expr.eval()
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_parse_number() {
    assert_eq!(parse_and_eval("42"), Ok(42));
}

#[test]
fn test_parse_addition() {
    assert_eq!(parse_and_eval("2 + 3"), Ok(5));
}

#[test]
fn test_parse_precedence() {
    assert_eq!(parse_and_eval("2 + 3 * 4"), Ok(14)); // Not 20!
}

#[test]
fn test_parse_parentheses() {
    assert_eq!(parse_and_eval("(2 + 3) * 4"), Ok(20));
}

#[test]
fn test_parse_complex() {
    assert_eq!(parse_and_eval("(10 - 5) * 2 + 8 / 4"), Ok(12));
}

#[test]
fn test_parse_nested() {
    assert_eq!(parse_and_eval("((1 + 2) * (3 + 4)) / (5 - 2)"), Ok(7));
}

#[test]
fn test_parse_error() {
    assert!(parse_and_eval("2 + + 3").is_err());
    assert!(parse_and_eval("(2 + 3").is_err());  // Unclosed paren
}
}

Check Your Understanding:

• Why does the grammar have three levels (Expr, Term, Factor)?
• How does this handle operator precedence?
• Why do we parse Factor in Term and Term in Expr?
• When do we create nodes in the arena?

Milestone 7: Performance Comparison

Compare arena allocation vs Box allocation using the implementations from Milestones 2 and 3.

Benchmark Code:

use std::time::Instant;

fn benchmark_arena() {
    let start = Instant::now();
    for _ in 0..10000 {
        let arena = Arena::new_with_capacity(4 * 1024);
        // Build expression: (1+2)*(3+4)+(5-2)*7
        let builder = ExprBuilder::new(&arena);
        let expr = builder.add(
            builder.mul(
                builder.add(builder.literal(1), builder.literal(2)),
                builder.add(builder.literal(3), builder.literal(4)),
            ),
            builder.mul(
                builder.sub(builder.literal(5), builder.literal(2)),
                builder.literal(7),
            ),
        );
        let _ = expr.eval();
    }
    let duration = start.elapsed();
    println!("Arena: {:?}", duration);
}

fn benchmark_box() {
    let start = Instant::now();
    for _ in 0..10000 {
        // Build same expression with Box
        let expr = BoxExprBuilder::add(
            BoxExprBuilder::mul(
                BoxExprBuilder::add(BoxExprBuilder::literal(1), BoxExprBuilder::literal(2)),
                BoxExprBuilder::add(BoxExprBuilder::literal(3), BoxExprBuilder::literal(4)),
            ),
            BoxExprBuilder::mul(
                BoxExprBuilder::sub(BoxExprBuilder::literal(5), BoxExprBuilder::literal(2)),
                BoxExprBuilder::literal(7),
            ),
        );
        let _ = expr.eval();
    }
    let duration = start.elapsed();
    println!("Box: {:?}", duration);
}

fn main() {
    println!("Benchmarking expression allocation...");
    benchmark_box();
    benchmark_arena();
}

Expected Results: Arena should be 2-5x faster depending on expression

String Interning

Problem Statement

Build a string interning system that stores unique strings once and reuses them. This demonstrates Clone-on-Write (Cow) patterns, zero-copy optimization, and a critical Rust pattern: escaping the borrow checker with raw pointers.

Understanding String Interning

What is String Interning?

String interning is a memory optimization technique where only one copy of each distinct string value is stored in memory. When you need the same string multiple times, instead of creating duplicate copies, you reuse a reference to the single stored instance.

Simple Example:

#![allow(unused)]
fn main() {
// Without interning (memory waste)
let name1 = String::from("Alice");  // Allocation #1
let name2 = String::from("Alice");  // Allocation #2 (duplicate!)
let name3 = String::from("Alice");  // Allocation #3 (duplicate!)
// Memory used: 3 allocations, 15 bytes total (5 bytes × 3)

// With interning (memory efficient)
let mut interner = StringInterner::new();
let name1 = interner.intern("Alice");  // Allocation #1
let name2 = interner.intern("Alice");  // Reuse! No allocation
let name3 = interner.intern("Alice");  // Reuse! No allocation
// Memory used: 1 allocation, 5 bytes, plus 3 pointers (24 bytes total on 64-bit)
}

Core Concepts

1. Single Storage

Each unique string is stored exactly once in a central repository (the “intern pool”).

Intern Pool:
┌─────────────┐
│ "Alice"     │ ← Stored once
│ "Bob"       │ ← Stored once
│ "Charlie"   │ ← Stored once
└─────────────┘

References:
name1 → "Alice"
name2 → "Alice"  (same pointer)
name3 → "Bob"
name4 → "Alice"  (same pointer)

2. Identity-Based Equality

Since identical strings have the same memory address, equality checks become pointer comparisons.

#![allow(unused)]
fn main() {
// String comparison: O(n) - must compare each character
if "Alice" == "Alice" {  // Checks: A==A, l==l, i==i, c==c, e==e
    // 5 comparisons
}

// Interned string comparison: O(1) - just compare pointers
if ptr1 == ptr2 {  // Single pointer comparison
    // 1 comparison
}
}

3. Deduplication

When you try to intern a string that already exists, the interner returns the existing instance.

#![allow(unused)]
fn main() {
let mut interner = StringInterner::new();

let s1 = interner.intern("hello");  // New: stores "hello"
let s2 = interner.intern("world");  // New: stores "world"
let s3 = interner.intern("hello");  // Duplicate: returns existing "hello"

// s1 and s3 point to the same memory!
}

Real-World Examples

String Interning in Practice

1. Java String Pool

String s1 = "hello";        // Interned automatically
String s2 = "hello";        // Reuses interned string
assert(s1 == s2);           // true (same object)

String s3 = new String("hello");  // Not interned
assert(s1 == s3);                 // false (different objects)

2. Python String Interning

s1 = "hello"
s2 = "hello"
assert(s1 is s2)  # True - Python interns short strings automatically

3. Rust Compiler (rustc)

• Interns all identifiers, keywords, and string literals
• Symbol table uses interned strings for fast lookup
• Reduces memory usage by ~15-20% during compilation

4. V8 JavaScript Engine

• Interns property names for objects
• Enables fast property lookup (pointer comparison)
• Critical for performance in property-heavy code

Rust Programming Concepts for This Project

This project requires understanding several Rust-specific concepts related to smart pointers, borrowing patterns, and type system features. These concepts enable building memory-efficient systems with zero-cost abstractions.

The Borrow Checker Problem with String Interning

Before we dive into the implementation, let’s understand a critical challenge that makes string interning tricky in Rust.

The Naive Approach (Doesn’t Work):

impl StringInterner {
    fn intern(&mut self, s: &str) -> &str {
        // Returns a reference tied to &mut self
        self.strings.get(s).unwrap()
    }
}

fn main() {
    let mut interner = StringInterner::new();

    let s1 = interner.intern("hello");  // Borrows interner mutably
    let s2 = interner.intern("hello");  // ❌ ERROR: interner already borrowed!

    // Can't even compare them!
    if s1 == s2 { }  // Still borrowing
}

Why Does This Fail?

The signature fn intern(&mut self, s: &str) -> &str means:

• The returned &str borrows from self
• As long as s1 exists, interner is borrowed
• You cannot call intern() again while s1 is alive

This is the borrow checker doing its job—preventing data races and dangling references. But it makes string interning practically useless!

The Solution: Raw Pointers

#![allow(unused)]
fn main() {
let s1 = interner.intern("hello") as *const str;
let s2 = interner.intern("hello") as *const str;

// Now both calls work!
assert!(std::ptr::eq(s1, s2));  // Same pointer!
}

By casting to *const str, we:

1. Convert the borrowed &str to a raw pointer
2. The borrow ends at the end of the statement
3. We can call intern() again immediately

Understanding *const str: Raw Pointers to String Slices

A raw pointer *const str is Rust’s “escape hatch” from the borrow checker. Let’s understand what it is and why we need it.

What is *const str?

#![allow(unused)]
fn main() {
// &str is a "fat pointer": pointer + length
// *const str is also a "fat pointer": pointer + length, but without borrow tracking

let s: &str = "hello";           // Borrowed reference with lifetime
let ptr: *const str = s;         // Raw pointer, no lifetime tracking

// Or explicitly cast:
let ptr: *const str = s as *const str;
}

Memory Layout:

&str (borrowed reference):
┌──────────────────────┬──────────────┐
│ pointer (8 bytes)    │ len (8 bytes)│ + lifetime tracking by compiler
└──────────────────────┴──────────────┘

*const str (raw pointer):
┌──────────────────────┬──────────────┐
│ pointer (8 bytes)    │ len (8 bytes)│  NO lifetime tracking
└──────────────────────┴──────────────┘

Key Properties of *const str:

Why *const str Solves Our Problem:

#![allow(unused)]
fn main() {
fn intern(&mut self, s: &str) -> &str {
    // Returns &str tied to &mut self
    self.strings.get(s).unwrap()
}

// Without casting - DOESN'T COMPILE:
let s1 = interner.intern("hello");     // Borrow starts
let s2 = interner.intern("hello");     // ❌ Can't borrow again!
//       ^^^^^^^^ still borrowed here

// With casting - WORKS:
let s1 = interner.intern("hello") as *const str;  // Borrow ends at semicolon
let s2 = interner.intern("hello") as *const str;  // New borrow, no conflict
// Both s1 and s2 are now *const str - the borrow checker ignores them
}

The Conversion Flow:

#![allow(unused)]
fn main() {
interner.intern("hello")     // Step 1: Returns &str (borrows interner)
    as *const str            // Step 2: Convert to raw pointer
;                            // Step 3: Borrow ends here!

// Next line: interner is no longer borrowed
}

Safety Considerations for *const str

Converting to *const str is not unsafe (the conversion itself is safe). However, using the raw pointer requires care:

Safe Operations (no unsafe needed):

#![allow(unused)]
fn main() {
let s1 = interner.intern("hello") as *const str;
let s2 = interner.intern("hello") as *const str;

// Pointer comparison - SAFE
assert!(std::ptr::eq(s1, s2));

// Checking for null - SAFE
assert!(!s1.is_null());

// Storing in a Vec - SAFE
let mut pointers: Vec<*const str> = vec![s1, s2];
}

Unsafe Operations (require unsafe block):

#![allow(unused)]
fn main() {
let ptr = interner.intern("hello") as *const str;

// Dereferencing - UNSAFE
unsafe {
    let s: &str = &*ptr;  // Convert back to reference
    println!("{}", s);
}
}

When is Dereferencing Safe?

The pointer is valid as long as:

1. The interner hasn’t been dropped
2. The interner hasn’t reallocated (for Vec-based storage)
3. The string hasn’t been removed from the interner

#![allow(unused)]
fn main() {
// SAFE: Interner still exists, no reallocation
let ptr = interner.intern("hello") as *const str;
unsafe { println!("{}", &*ptr); }  // ✅ OK

// DANGEROUS: Interner dropped
let ptr = interner.intern("hello") as *const str;
drop(interner);
unsafe { println!("{}", &*ptr); }  // ❌ UNDEFINED BEHAVIOR!

// DANGEROUS: Potential reallocation (for Vec-based storage)
let ptr = interner.intern("hello") as *const str;
for i in 0..1000 {
    interner.intern(&format!("string{}", i));  // May reallocate!
}
unsafe { println!("{}", &*ptr); }  // ❌ MIGHT BE DANGLING!
}

HashSet-Based Storage is Safer:

Using HashSet<Box<str>> instead of Vec<String> is safer because:

• Each string is in its own heap allocation (Box<str>)
• Strings don’t move when the HashSet grows
• Only the bucket pointers move, not the strings themselves

#![allow(unused)]
fn main() {
// HashSet<Box<str>> - strings are stable
let ptr = interner.intern("hello") as *const str;
interner.intern("world");  // HashSet grows, but "hello" doesn't move
unsafe { println!("{}", &*ptr); }  // ✅ Still safe!
}

Cow: Clone-on-Write Smart Pointer

The Core Problem: Many functions sometimes need to modify their input, sometimes don’t. How do you avoid unnecessary allocations in the “no modification needed” case?

Wrong Approaches:

#![allow(unused)]
fn main() {
// Approach 1: Always allocate (wasteful)
fn process(input: &str) -> String {
    input.to_string()  // Allocates even if unchanged!
}

// Approach 2: Try to return reference (doesn't compile)
fn process(input: &str) -> &str {
    if needs_modification(input) {
        return modified_string;  // ❌ Where does modified_string live?
    }
    input
}
}

The Solution: Cow<'a, B>

#![allow(unused)]
fn main() {
pub enum Cow<'a, B: ?Sized + 'a>
where
    B: ToOwned,
{
    Borrowed(&'a B),           // Zero-copy: points to existing data
    Owned(<B as ToOwned>::Owned),  // Allocated: owns the data
}
}

For strings, this becomes:

• Cow::Borrowed(&str) - Zero-copy reference to string
• Cow::Owned(String) - Heap-allocated string

Key Characteristics:

1. Lifetime Parameter 'a: The borrowed variant holds a reference, so we need to track its lifetime

   #![allow(unused)]
   fn main() {
   fn process<'a>(input: &'a str) -> Cow<'a, str> {
       Cow::Borrowed(input)  // Lifetime of output tied to input
   }
   }

2. Trait Bound B: ToOwned: The borrowed type must be convertible to an owned type

   #![allow(unused)]
   fn main() {
   // For str:
   impl ToOwned for str {
       type Owned = String;
       fn to_owned(&self) -> String { /* ... */ }
   }
   }

3. Smart Deref: Cow<str> dereferences to &str, so you can use it like a string

   #![allow(unused)]
   fn main() {
   let cow: Cow<str> = Cow::Borrowed("hello");
   println!("{}", cow.len());  // Works! Derefs to &str
   assert_eq!(&*cow, "hello"); // Explicit deref
   }

4. Lazy Allocation: Only allocate when mutation is needed

   #![allow(unused)]
   fn main() {
   let cow = Cow::Borrowed("test");
   let owned = cow.into_owned();  // Allocates String only now
   }

Performance Impact:

#![allow(unused)]
fn main() {
// Without Cow (always allocate)
fn normalize(s: &str) -> String {
    s.trim().to_string()  // 100% allocation rate
}

// With Cow (allocate only when needed)
fn normalize(s: &str) -> Cow<str> {
    let trimmed = s.trim();
    if trimmed.len() == s.len() {
        Cow::Borrowed(s)  // 0% allocation for clean input
    } else {
        Cow::Owned(trimmed.to_string())  // Allocate only when trimmed
    }
}
}

If 90% of inputs are already clean:

• Without Cow: 100% allocations (10,000 inputs = 10,000 allocations)
• With Cow: 10% allocations (10,000 inputs = 1,000 allocations)
• Result: 10x fewer allocations

Box vs String: Choosing the Right String Type

Rust has multiple string types. Understanding when to use each is crucial for this project.

The Three Main String Types:

Why Box for Interning?

#![allow(unused)]
fn main() {
// String has 3 fields
struct String {
    ptr: *mut u8,      // 8 bytes
    len: usize,        // 8 bytes
    capacity: usize,   // 8 bytes - WASTED for interning!
}

// Box<str> has 2 fields (same as &str)
struct BoxStr {
    ptr: *const u8,    // 8 bytes
    len: usize,        // 8 bytes
}
}

Key Insight: Interned strings never grow, so capacity field is waste. Box<str> saves 8 bytes per string!

Memory Comparison:

#![allow(unused)]
fn main() {
// With String (24 bytes each + string data)
let strings: Vec<String> = vec![
    String::from("hello"),  // 24 + 5 = 29 bytes
    String::from("world"),  // 24 + 5 = 29 bytes
];
// Total: 58 bytes + Vec overhead

// With Box<str> (16 bytes each + string data)
let strings: Vec<Box<str>> = vec![
    Box::from("hello"),  // 16 + 5 = 21 bytes
    Box::from("world"),  // 16 + 5 = 21 bytes
];
// Total: 42 bytes + Vec overhead
// Savings: 16 bytes (27% less!)
}

For 10,000 interned strings averaging 20 bytes each:

• With String: 10,000 × (24 + 20) = 440 KB
• With Box<str>: 10,000 × (16 + 20) = 360 KB
• Savings: 80 KB (18% reduction)

Converting Between Types:

#![allow(unused)]
fn main() {
// str → String
let s: String = "hello".to_string();
let s: String = "hello".to_owned();
let s: String = String::from("hello");

// str → Box<str>
let b: Box<str> = Box::from("hello");
let b: Box<str> = "hello".into();

// String → Box<str> (drops capacity)
let s = String::from("hello");
let b: Box<str> = s.into_boxed_str();

// Box<str> → String (realloc with capacity)
let b: Box<str> = Box::from("hello");
let s: String = b.into();
}

HashSet and Hashing: Fast Lookup Data Structure

What is a HashSet?

A HashSet<T> is a collection that:

• Stores unique values (no duplicates)
• Provides O(1) average-case lookup, insert, remove
• Uses hashing to achieve speed

How Hashing Works:

1. Hash the value: "hello" → hash("hello") → 5863208
2. Index into buckets: 5863208 % bucket_count → bucket 24
3. Store/lookup in bucket 24

Visual Example:

HashSet<&str> with 8 buckets:
┌─────────┬──────────────┐
│ Bucket 0│              │
│ Bucket 1│ "world" ───┐ │
│ Bucket 2│              │
│ Bucket 3│ "hello" ───┤ │  (hash("hello") % 8 = 3)
│ Bucket 4│              │
│ Bucket 5│ "foo" ─────┤ │
│ Bucket 6│              │
│ Bucket 7│ "bar" ─────┘ │
└─────────┴──────────────┘

Key HashSet Operations:

#![allow(unused)]
fn main() {
use std::collections::HashSet;

let mut set = HashSet::new();

// Insert (returns true if new, false if duplicate)
assert!(set.insert("hello"));   // true - new
assert!(!set.insert("hello"));  // false - duplicate

// Contains (O(1) average)
assert!(set.contains("hello"));

// Get (returns reference to stored value)
let stored: &str = set.get("hello").unwrap();

// Remove
set.remove("hello");

// Iterate
for s in &set {
    println!("{}", s);
}
}

The Magic of HashSet::get():

This is crucial for string interning!

#![allow(unused)]
fn main() {
let mut set: HashSet<Box<str>> = HashSet::new();
set.insert(Box::from("hello"));

// Input: &str reference (temporary)
let input: &str = "hello";

// get() returns: reference to the Box<str> INSIDE the set!
let stored: &Box<str> = set.get(input).unwrap();

// We can then return a &str pointing INTO that Box
let interned: &str = stored.as_ref();
}

Why This Works for Interning:

#![allow(unused)]
fn main() {
fn intern(&mut self, s: &str) -> &str {
    // 1. Check if already stored
    if !self.strings.contains(s) {
        self.strings.insert(Box::from(s));  // Allocate and store
    }

    // 2. Return reference to stored value (not input!)
    // This reference lives as long as the HashSet
    self.strings.get(s).unwrap().as_ref()
}
}

The lifetime magic:

• Input s: &str has a short lifetime
• Returned &str has the lifetime of &self
• The string lives in the HashSet, so it outlives the input

Generational Indices: Safe Handles Without Lifetimes

The Problem: Raw pointers (*const str) work, but they’re inherently unsafe. References (&str) carry lifetime annotations that infect everything:

#![allow(unused)]
fn main() {
struct Compiler<'intern> {
    identifiers: Vec<&'intern str>,  // ❌ Lifetime everywhere
    interner: &'intern StringInterner,
}
}

This makes code complex and limits flexibility (can’t easily serialize, send between threads, etc.).

The Solution: Generational Indices (also called “slot map pattern”)

Replace references with Copy handles that contain an index and a generation:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
struct Symbol {
    index: usize,     // Which slot?
    generation: u32,  // Which version of that slot?
}
}

How It Works:

Storage:
  slots: Vec<Slot>
  free_list: Vec<usize>

Slot:
  data: Option<T>     // None = free slot
  generation: u32     // Increments on reuse

Symbol:
  index: usize        // Points to slot
  generation: u32     // Must match slot's generation

Example:

#![allow(unused)]
fn main() {
let mut interner = SymbolInterner::new();

// 1. Allocate "hello" → slot 0
let sym1 = interner.intern("hello");
// sym1 = Symbol{index: 0, generation: 0}
// slots[0] = Slot{data: Some("hello"), generation: 0}

// 2. Remove "hello"
interner.remove(sym1);
// slots[0] = Slot{data: None, generation: 1}  ← generation incremented!
// free_list = [0]

// 3. Try to use old symbol → returns None!
assert_eq!(interner.resolve(sym1), None);
// sym1 has gen=0, but slot has gen=1 → mismatch!

// 4. Allocate "world" → reuses slot 0
let sym2 = interner.intern("world");
// sym2 = Symbol{index: 0, generation: 1}
// slots[0] = Slot{data: Some("world"), generation: 1}

// 5. Old symbol still doesn't work
assert_eq!(interner.resolve(sym1), None);  // Still gen=0
assert_eq!(interner.resolve(sym2), Some("world"));  // gen=1 matches
}

Benefits Over Raw Pointers:

Build the Project

In this project, you’re building a string interning system:

1. Intrinsic State: The string content itself (shared)
2. Extrinsic State: Where the string is used (not stored in interner)
3. Factory: The StringInterner struct manages the string pool
4. Optimization: Cow pattern enables zero-copy when strings are already interned

What You’ll Build:

#![allow(unused)]
fn main() {
pub struct StringInterner {
    pool: HashSet<Box<str>>,  // The flyweight pool for strings
}

impl StringInterner {
    pub fn intern(&mut self, s: &str) -> &str {
        // Store if new, return reference to stored string
    }
}

// Usage with raw pointers to escape borrow checker:
let s1 = interner.intern("hello") as *const str;
let s2 = interner.intern("hello") as *const str;
assert!(std::ptr::eq(s1, s2));  // Same pointer!
}

Performance Benefits:

1. Memory: 10-40% reduction in string memory for identifier-heavy workloads
2. Comparison: O(1) pointer equality vs O(n) string comparison
3. Hashing: Hash once, reuse hash value (important for HashMaps)
4. Cache: Fewer unique strings = better cache locality

Milestone 1: Understand Cow Basics

Learn how Cow (Clone-on-Write) works through hands-on examples that demonstrate zero-copy optimization.

Architecture:

functions:

• normalize_whitespace(text: &str) -> Cow<str>

  • Checks for double spaces or tabs
  • If found: replace with single spaces (allocate)
  • If not found: return original (zero-copy)

• maybe_escape_html(text: &str) -> Cow<str>

  • Checks for <, >, & characters
  • If found: escape to <, >, & (allocate)
  • If not found: return original (zero-copy)

Starter Code:

#![allow(unused)]
fn main() {
use std::borrow::Cow;

// Exercise 1: Function that sometimes modifies input
fn normalize_whitespace(text: &str) -> Cow<str> {
    if text.contains("  ") || text.contains('\t') {
        // Need to modify - return Owned
    } else {
        // No modification needed - return Borrowed
    }
}

// Exercise 2: Function that might escape HTML
// replace: '&' -> &amp;  '<' -> &lt;  '>' -> &gt;
fn maybe_escape_html(text: &str) -> Cow<str> {
    if text.contains('<') || text.contains('>') || text.contains('&') {
        // TODO replace
    } else {
        // TODO
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_normalize_no_change() {
    let result = normalize_whitespace("hello world");
    assert!(matches!(result, Cow::Borrowed(_)));
    assert_eq!(result, "hello world");
}

#[test]
fn test_normalize_with_change() {
    let result = normalize_whitespace("hello  world");
    assert!(matches!(result, Cow::Owned(_)));
    assert_eq!(result, "hello world");
}

#[test]
fn test_escape_no_html() {
    let result = maybe_escape_html("hello");
    assert!(matches!(result, Cow::Borrowed(_)));
}

#[test]
fn test_escape_with_html() {
    let result = maybe_escape_html("<div>");
    assert!(matches!(result, Cow::Owned(_)));
    assert_eq!(result, "&lt;div&gt;");
}
}

Check Your Understanding:

• When should you return Cow::Borrowed vs Cow::Owned?
• What’s the benefit of returning Cow vs always returning String?
• How can the caller use a Cow<str>?

Why Milestone 1 Isn’t Enough

Limitation: Cow shows us when to avoid allocations, but doesn’t actually store strings for reuse. Each call still checks/modifies independently.

The Real Problem: Consider processing 1 million log messages, many containing “ERROR: Connection timeout”. Without interning:

• Each occurrence: Parse, check, maybe allocate
• No sharing between occurrences
• Memory: Thousands of copies of “ERROR: Connection timeout”

What we’re adding: String Interning - global string pool:

• HashSet<Box> - stores unique strings once
• References - return &str pointing into the set
• Deduplication - automatic string reuse

Improvements:

• Memory: One allocation per unique string (not per occurrence)
• Comparison: ptr::eq() for equality (vs strcmp)
• Lifetime: Strings live as long as interner exists
• Cost: HashSet lookup + occasional allocation

Performance Numbers:

• Without interning: 1M strings × 25 bytes average = 25MB
• With interning (10K unique): 10K × 25 bytes = 250KB (100x savings!)
• Lookup overhead: ~50ns per intern call (hash + comparison)
• Win when: duplicates > ~2x per unique string

Milestone 2: Basic String Interner with Raw Pointers

Implement a string interner that stores each unique string once. Because intern() returns &str tied to &mut self, we must convert to *const str to use multiple interned strings together.

The Core Problem: Borrow Checker vs Practical Usage

#![allow(unused)]
fn main() {
// This is what we want to write:
let s1 = interner.intern("hello");
let s2 = interner.intern("hello");
assert!(std::ptr::eq(s1, s2));  // Compare pointers

// But this DOESN'T COMPILE because:
// - intern() takes &mut self
// - Returns &str tied to that borrow
// - Can't call intern() again while s1 exists!
}

The Solution: Cast to *const str

#![allow(unused)]
fn main() {
// This WORKS:
let s1 = interner.intern("hello") as *const str;
let s2 = interner.intern("hello") as *const str;
assert!(std::ptr::eq(s1, s2));  // ✅ Compiles and works!
}

Why Does This Work?

#![allow(unused)]
fn main() {
interner.intern("hello")  // Returns &str, borrows &mut self
    as *const str         // Converts to raw pointer (Copy, no borrow tracking)
;                         // Borrow of interner ENDS here

// Now interner is free to be borrowed again!
interner.intern("hello") as *const str;  // New borrow, no conflict
}

The key insight: as *const str “forgets” the borrow. The raw pointer is Copy and has no lifetime parameter, so the compiler stops tracking it.

Architecture:

struct:

#![allow(unused)]
fn main() {
struct StringInterner {
    strings: HashSet<Box<str>>,  // Set of unique strings
}
}

functions:

• new() -> Self - Create empty interner with empty HashSet
• intern(&mut self, s: &str) -> &str - Add string to set if new, return reference
• contains(&self, s: &str) -> bool - Check if string is interned
• len(&self) -> usize - Number of unique strings stored
• total_bytes(&self) -> usize - Total bytes used by all strings

The intern() Algorithm:

#![allow(unused)]
fn main() {
fn intern(&mut self, s: &str) -> &str {
    // 1. Check if string already in set
    if !self.strings.contains(s) {
        // 2. First time seeing this string - allocate and store
        self.strings.insert(Box::from(s));
    }
    // 3. Return reference to the string in the set
    self.strings.get(s).unwrap()
}
}

Key Insight: HashSet::get() returns a reference to the stored value, not the input! This is how we return &str with a longer lifetime.

Using Raw Pointers Safely:

#![allow(unused)]
fn main() {
let mut interner = StringInterner::new();

// Convert to *const str immediately to escape the borrow
let s1 = interner.intern("hello") as *const str;
let s2 = interner.intern("hello") as *const str;

// Pointer comparison is SAFE (no dereferencing)
assert!(std::ptr::eq(s1, s2));

// To actually USE the string, you need unsafe:
unsafe {
    let str1: &str = &*s1;  // Dereference raw pointer
    println!("{}", str1);
}
}

When is the Raw Pointer Valid?

The *const str is valid as long as:

1. The StringInterner hasn’t been dropped
2. The string hasn’t been removed from the interner
3. (With HashSet<Box>, individual strings don’t move even if HashSet grows)

#![allow(unused)]
fn main() {
// ✅ SAFE: Interner still exists
let ptr = interner.intern("hello") as *const str;
interner.intern("world");  // HashSet may grow, but "hello" doesn't move
unsafe { println!("{}", &*ptr); }  // Still valid!

// ❌ UNSAFE: Interner dropped
let ptr = interner.intern("hello") as *const str;
drop(interner);
unsafe { println!("{}", &*ptr); }  // UNDEFINED BEHAVIOR!
}

Starter Code:

#![allow(unused)]
fn main() {
use std::collections::HashSet;

struct StringInterner {
    strings: HashSet<Box<str>>,
}

impl StringInterner {
    fn new() -> Self {
        // TODO: Create new StringInterner with empty HashSet
        todo!()
    }

    fn intern(&mut self, s: &str) -> &str {
        // TODO: Check if string already in set
        // TODO: First time seeing this string - allocate and store
        // TODO: Return reference to the string in the set
        todo!()
    }

    fn contains(&self, s: &str) -> bool {
        // TODO: Check if strings HashSet contains s
        todo!()
    }

    fn len(&self) -> usize {
        // TODO: Return length of strings HashSet
        todo!()
    }

    fn total_bytes(&self) -> usize {
        // TODO: Sum up the length of all strings
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_intern_basic() {
    let mut interner = StringInterner::new();

    // Must cast to *const str to escape borrow checker!
    let s1 = interner.intern("hello") as *const str;
    let s2 = interner.intern("hello") as *const str;

    // Should be same pointer (no second allocation)
    assert!(std::ptr::eq(s1, s2));
    assert_eq!(interner.len(), 1);
}

#[test]
fn test_intern_different() {
    let mut interner = StringInterner::new();

    let s1 = interner.intern("hello") as *const str;
    let s2 = interner.intern("world") as *const str;

    assert!(!std::ptr::eq(s1, s2));
    assert_eq!(interner.len(), 2);
}

#[test]
fn test_contains() {
    let mut interner = StringInterner::new();
    interner.intern("hello");

    assert!(interner.contains("hello"));
    assert!(!interner.contains("world"));
}

#[test]
fn test_total_bytes() {
    let mut interner = StringInterner::new();
    interner.intern("hi");     // 2 bytes
    interner.intern("hello");  // 5 bytes

    assert_eq!(interner.total_bytes(), 7);
}

#[test]
fn test_pointer_stability() {
    let mut interner = StringInterner::new();

    // Get pointer to first string
    let ptr1 = interner.intern("first") as *const str;

    // Add many more strings (may cause HashSet to resize)
    for i in 0..100 {
        interner.intern(&format!("string{}", i));
    }

    // Original pointer should still be valid (Box<str> doesn't move)
    let ptr1_again = interner.intern("first") as *const str;
    assert!(std::ptr::eq(ptr1, ptr1_again));
}
}

Check Your Understanding:

• Why do we use Box<str> instead of String?
• Why must we cast to *const str after calling intern()?
• What makes the pointers equal for the same string?
• When is it safe to dereference the raw pointer?

Milestone 3: Add Statistics Tracking

Add comprehensive statistics to measure interner effectiveness and understand allocation patterns.

Since we’re working with raw pointers, we can’t easily communicate “did this allocate?” through the return type. Instead, we track aggregate statistics:

• Is the interner effective? High hit rate (lookups/total) = good reuse!
• Should we use interning? If allocation rate is too low, overhead might not be worth it
• Memory saved: Compare total_bytes vs. (allocations + lookups) × average_length

Architecture:

struct:

• InternerStats

#![allow(unused)]
fn main() {
struct InternerStats {
    total_strings: usize,   // Unique strings currently stored
    total_bytes: usize,     // Total bytes used by strings
    allocations: usize,     // How many new strings added
    lookups: usize,         // How many duplicate strings found
}
}

functions: The stats need to be updated in intern():

#![allow(unused)]
fn main() {
fn intern(&mut self, s: &str) -> &str {
    if !self.strings.contains(s) {
        // New string - record allocation
        self.strings.insert(Box::from(s));
        self.stats.total_strings += 1;
        self.stats.total_bytes += s.len();
        self.stats.allocations += 1;
    } else {
        // Duplicate - record lookup
        self.stats.lookups += 1;
    }
    self.strings.get(s).unwrap()
}
}

Hit Rate Calculation:

#![allow(unused)]
fn main() {
impl InternerStats {
    fn hit_rate(&self) -> f64 {
        let total = self.allocations + self.lookups;
        if total == 0 { 0.0 } else { self.lookups as f64 / total as f64 }
    }
}
}

A hit rate of 0.9 (90%) means 90% of intern() calls found an existing string—great reuse!

Performance Cost of Statistics:

Adding stats is cheap:

• Increment counters: ~1ns each (just memory writes)
• String length: already computed for HashSet
• No allocations, no complex computation

The cost is negligible compared to the HashSet lookup (~50ns)

Starter Code:

#![allow(unused)]
fn main() {
#[derive(Debug, Default, PartialEq)]
struct InternerStats {
    total_strings: usize,
    total_bytes: usize,
    allocations: usize,  // How many times we allocated
    lookups: usize,      // How many times we just returned existing
}

struct StringInterner {
    strings: HashSet<Box<str>>,
    stats: InternerStats,
}

impl StringInterner {
    fn new() -> Self {
        // TODO: Create StringInterner with empty HashSet and zero stats
        todo!()
    }

    fn intern(&mut self, s: &str) -> &str {
        // TODO: Check if string is not already interned
        if todo!("!self.strings.contains(s)") {
            // TODO: Insert string into HashSet
            todo!();
            // TODO: Update statistics: increment total_strings, add to total_bytes, increment allocations
            todo!();
        } else {
            // TODO: Increment lookups count (string was already interned)
            todo!();
        }

        // TODO: Return reference to interned string
        todo!()
    }

    fn statistics(&self) -> &InternerStats {
        // TODO: Return reference to stats
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_stats() {
    let mut interner = StringInterner::new();

    interner.intern("hello");  // allocation
    interner.intern("world");  // allocation
    interner.intern("hello");  // lookup

    let stats = interner.statistics();
    assert_eq!(stats.total_strings, 2);
    assert_eq!(stats.total_bytes, 10);  // 5 + 5
    assert_eq!(stats.allocations, 2);
    assert_eq!(stats.lookups, 1);
}

#[test]
fn test_stats_empty() {
    let interner = StringInterner::new();
    let stats = interner.statistics();
    assert_eq!(stats.total_strings, 0);
    assert_eq!(stats.allocations, 0);
}

#[test]
fn test_hit_rate() {
    let mut interner = StringInterner::new();

    interner.intern("a");  // alloc
    interner.intern("a");  // lookup
    interner.intern("a");  // lookup
    interner.intern("b");  // alloc

    let stats = interner.statistics();
    // 2 lookups / 4 total = 50% hit rate
    let hit_rate = stats.lookups as f64 / (stats.allocations + stats.lookups) as f64;
    assert!((hit_rate - 0.5).abs() < 0.001);
}
}

Check Your Understanding:

• Why track both allocations and lookups?
• How does hit rate help evaluate interner effectiveness?

Why Raw Pointers Aren’t Enough

Our interner with raw pointers has some critical limitations:

1. Unsafe to Dereference:

#![allow(unused)]
fn main() {
let ptr = interner.intern("hello") as *const str;

// Every time you want to USE the string:
let s: &str = unsafe { &*ptr };  // Unsafe block required!
}

2. No Stale Detection:

#![allow(unused)]
fn main() {
let ptr = interner.intern("hello") as *const str;
drop(interner);  // Interner gone!

// ptr is now dangling - no way to detect this!
unsafe { println!("{}", &*ptr); }  // UNDEFINED BEHAVIOR
}

3. Lifetime Not Tracked:

#![allow(unused)]
fn main() {
// Compiler can't help you catch bugs:
fn get_interned() -> *const str {
    let interner = StringInterner::new();
    interner.intern("hello") as *const str
    // interner dropped here! Pointer is dangling!
}
}

The Solution: Generational Indices

Instead of raw pointers, use a Symbol handle with an index and generation:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq)]
struct Symbol {
    index: usize,
    generation: u32,
}
}

Benefits:

• Safe API: No unsafe needed for normal usage
• Stale detection: Generation mismatch → returns None
• Serializable: Just two numbers, can save to disk
• Thread-safe: Copy, no lifetime complexity

Milestone 4: Symbol-Based Access with Generational Indices

Replace raw pointers with safe Symbol handles that detect stale references at runtime.

Architecture:

Instead of returning &str (which we cast to *const str), return a Symbol handle (no lifetime):

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq)]
struct Symbol {
    index: usize,      // Which slot in the interner?
    generation: u32,   // Which version of that slot?
}
}

Now your code looks like:

#![allow(unused)]
fn main() {
struct Compiler {
    identifiers: Vec<Symbol>,  // ✅ No lifetime!
    interner: SymbolInterner,  // ✅ Can own it
}

fn parse(source: &str, interner: &mut SymbolInterner) -> Result<Vec<Symbol>, Error> {
    // ✅ No lifetimes in return type!
}
}

The Core Idea:

#![allow(unused)]
fn main() {
struct Slot {
    string: Option<Box<str>>,  // None = slot is free
    generation: u32,           // Incremented each time slot is reused
}

struct SymbolInterner {
    slots: Vec<Slot>,           // All slots (some filled, some free)
    free_list: Vec<usize>,      // Indices of free slots to reuse
}
}

How It Works:

1. Allocate: Find free slot (or create new one), store string, return Symbol{index, generation}
2. Resolve: Look up slots[index], check generation matches, return Option<&str>
3. Remove: Set slots[index].string = None, increment generation, add index to free list
4. Reuse: Next allocation reuses freed slot with new generation number

Example Walkthrough:

#![allow(unused)]
fn main() {
let mut interner = SymbolInterner::new();

// 1. Intern "hello" → creates slot 0
let sym1 = interner.intern("hello");  // Symbol{index: 0, generation: 0}
assert_eq!(interner.resolve(sym1), Some("hello"));

// 2. Remove "hello" → frees slot 0, increments generation
interner.remove(sym1);
// slots[0] = Slot{string: None, generation: 1}
// free_list = [0]

// 3. Try to resolve old symbol → generation mismatch!
assert_eq!(interner.resolve(sym1), None);  // sym1 has gen=0, slot has gen=1

// 4. Intern "world" → reuses slot 0 with new generation
let sym2 = interner.intern("world");  // Symbol{index: 0, generation: 1}
assert_eq!(interner.resolve(sym2), Some("world"));

// 5. Old symbol still doesn't work
assert_eq!(interner.resolve(sym1), None);  // Still stale!
}

Comparison: Raw Pointers vs Symbols:

Starter Code:

#![allow(unused)]
fn main() {
#[derive(Debug, Copy, Clone, PartialEq)]
struct Symbol {
    index: usize,
    generation: u32,
}

struct Slot {
    string: Option<Box<str>>,
    generation: u32,
}

struct SymbolInterner {
    slots: Vec<Slot>,
    free_list: Vec<usize>,
}

impl SymbolInterner {
    fn new() -> Self {
        // TODO: Create SymbolInterner with empty slots and free_list
        todo!()
    }

    fn intern(&mut self, s: &str) -> Symbol {
        // TODO: Check if string already exists in slots
        // Hint: Loop through slots, check if slot.string matches s
        for (index, slot) in self.slots.iter().enumerate() {
            if let Some(existing) = &slot.string {
                if existing.as_ref() == s {
                    // TODO: Return Symbol with this index and generation
                    todo!()
                }
            }
        }

        // Not found - allocate new slot
        // TODO: Check if there's a free slot to reuse
        if let Some(index) = self.free_list.pop() {
            // TODO: Reuse freed slot
            // - Get mutable reference to slot at index
            // - Increment generation
            // - Set string to Some(Box::from(s))
            // - Return Symbol with index and new generation
            todo!()
        } else {
            // TODO: Allocate new slot at end of Vec
            // - Get index (current slots.len())
            // - Push new Slot with string and generation 0
            // - Return Symbol with index and generation 0
            todo!()
        }
    }

    fn resolve(&self, symbol: Symbol) -> Option<&str> {
        // TODO: Get slot at symbol.index
        // TODO: Check if generation matches
        // TODO: If matches, return string as Option<&str>, else None
        // Hint: self.slots.get(symbol.index).and_then(|slot| ...)
        todo!()
    }

    fn remove(&mut self, symbol: Symbol) {
        // TODO: Get mutable reference to slot at symbol.index
        // TODO: Check if generation matches
        // TODO: If matches:
        //   - Set string to None
        //   - Increment generation
        //   - Push index to free_list
        todo!()
    }

    fn clear(&mut self) {
        // TODO: Iterate through all slots
        // TODO: For each slot with a string:
        //   - Set string to None
        //   - Increment generation
        //   - Push index to free_list
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_symbol_intern() {
    let mut interner = SymbolInterner::new();

    let sym1 = interner.intern("hello");
    let sym2 = interner.intern("hello");

    // Same string should have same symbol
    assert_eq!(sym1, sym2);
    assert_eq!(interner.resolve(sym1), Some("hello"));
}

#[test]
fn test_symbol_resolve() {
    let mut interner = SymbolInterner::new();

    let sym = interner.intern("test");
    assert_eq!(interner.resolve(sym), Some("test"));
}

#[test]
fn test_stale_symbol() {
    let mut interner = SymbolInterner::new();

    let sym1 = interner.intern("test");
    interner.clear();

    // sym1 is now stale
    assert_eq!(interner.resolve(sym1), None);
}

#[test]
fn test_generation_reuse() {
    let mut interner = SymbolInterner::new();

    let sym1 = interner.intern("test");
    let index1 = sym1.index;
    let gen1 = sym1.generation;

    interner.remove(sym1);

    // Interning again should reuse slot but increment generation
    let sym2 = interner.intern("test");
    assert_eq!(sym2.index, index1);  // Same slot
    assert_ne!(sym2.generation, gen1);  // Different generation
}

#[test]
fn test_symbol_is_copy() {
    let mut interner = SymbolInterner::new();
    let sym = interner.intern("test");

    // Symbol is Copy - can use it multiple times without moving
    let sym_copy = sym;
    assert_eq!(interner.resolve(sym), Some("test"));
    assert_eq!(interner.resolve(sym_copy), Some("test"));
}
}

Check Your Understanding:

• Why use Symbols instead of raw pointers?
• How do generational indices detect stale references?
• What’s the advantage of reusing slots with free_list?
• Why is Symbol Copy but still safe?

Milestone 5: Performance Comparison

Goal: Measure the benefit of interning vs raw allocation.

Benchmark Code:

#![allow(unused)]
fn main() {
use std::time::Instant;

fn benchmark_with_interner() {
    let mut interner = StringInterner::new();
    let words = vec!["hello", "world", "foo", "bar", "hello", "world"];

    let start = Instant::now();
    for _ in 0..100000 {
        for word in &words {
            let _ = interner.intern(word);
        }
    }
    let duration = start.elapsed();

    let stats = interner.statistics();
    println!("With interner: {:?}", duration);
    println!("Stats: {:?}", stats);
    println!("Hit rate: {:.1}%",
        stats.lookups as f64 / (stats.allocations + stats.lookups) as f64 * 100.0);
}

fn benchmark_without_interner() {
    let words = vec!["hello", "world", "foo", "bar", "hello", "world"];
    let mut strings = Vec::new();

    let start = Instant::now();
    for _ in 0..100000 {
        for word in &words {
            strings.push(word.to_string());  // Always allocate
        }
        strings.clear();  // Clear to avoid OOM
    }
    let duration = start.elapsed();

    println!("Without interner: {:?}", duration);
    println!("Allocations: {}", 100_000 * words.len());
}
}

Expected Results:

• Interner: ~10-50ms, 4 allocations, 596 lookups (99.3% hit rate)
• Without: ~200-500ms, 600,000 allocations

When Does Interning Help Most?

• High duplication rate (many lookups, few allocations)
• Long strings (allocation cost dominates)
• Frequent equality comparisons (pointer compare vs string compare)

When Might Interning Hurt?

• All unique strings (100% allocation rate + hash overhead)
• Very short-lived strings (lookup cost exceeds benefit)
• Single-use strings that are never compared

Check Your Understanding:

• When does interning help most?
• When might interning hurt performance?
• What’s the memory trade-off?

Generic Data Structures with Const Generics

Problem Statement

Build a collection of generic data structures that leverage const generics for compile-time size guarantees and zero-cost abstractions. The library demonstrates how Rust’s generics enable writing reusable containers that compile to optimal machine code for each concrete type through monomorphization.

Use Cases:

• Embedded systems requiring fixed-size, stack-allocated collections
• High-performance applications needing predictable memory layout
• Real-time systems where dynamic allocation is prohibited
• Generic algorithm libraries working across multiple types
• Teaching compile-time guarantees and zero-cost abstractions

Why It Matters

Generic data structures with const generics demonstrate Rust’s type system strengths:

Compile-Time Size Guarantees:

• Without const generics: Vec<T> uses heap allocation, dynamic size, runtime overhead
• With const generics: Stack<T, 1024> uses stack allocation, fixed size, zero runtime cost
• Memory layout: Known at compile time, enables better optimization and cache locality

Zero-Cost Abstractions:

• Generic code monomorphizes to specialized machine code per type
• Stack<i32, 100> and Stack<String, 100> are completely different compiled types
• No vtable lookups, no boxing, no dynamic dispatch
• Performance identical to hand-written specialized code

Type Safety:

• Bounds checking at compile time (const generics)
• Trait bounds enforce required operations (Ord, Clone, Default)
• Invalid states prevented by the type system (e.g., pushing to full stack)

Performance Impact:

• Dynamic allocation (Vec): 50-100ns per allocation, unpredictable latency
• Fixed-size (Stack<T, N>): 0ns allocation (stack), predictable latency
• Cache efficiency: Contiguous stack allocation vs scattered heap pointers
• Optimization: Compiler can inline and optimize with known sizes

Understanding Generic Programming in Rust

Before implementing the data structures, let’s understand the powerful concepts that make Rust’s generics unique and performant.

What are Generics?

Generics allow you to write code that works with multiple types without knowing the specific type at the time of writing. Instead of writing separate implementations for Stack<i32>, Stack<String>, Stack<MyStruct>, you write one generic implementation Stack<T> that works for any type T.

The Problem Without Generics:

#![allow(unused)]
fn main() {
// Have to write separate implementations for each type!
struct StackInt {
    data: Vec<i32>,
}

struct StackString {
    data: Vec<String>,
}

struct StackPoint {
    data: Vec<Point>,
}

// And repeat all methods for each type... horrible code duplication!
}

With Generics:

#![allow(unused)]
fn main() {
// Write once, use with any type!
struct Stack<T> {
    data: Vec<T>,
}

// Same implementation works for all types
let int_stack: Stack<i32> = Stack::new();
let string_stack: Stack<String> = Stack::new();
let point_stack: Stack<Point> = Stack::new();
}

Monomorphization: Zero-Cost Abstractions

Monomorphization is Rust’s technique for achieving zero-cost abstractions with generics. The compiler generates specialized machine code for each concrete type you use.

How It Works:

#![allow(unused)]
fn main() {
// You write this once:
struct Stack<T> {
    data: Vec<T>,
}

impl<T> Stack<T> {
    fn push(&mut self, value: T) { ... }
    fn pop(&mut self) -> Option<T> { ... }
}

// You use it with different types:
let int_stack: Stack<i32> = Stack::new();
let string_stack: Stack<String> = Stack::new();

// Compiler generates TWO separate implementations:
struct Stack_i32 {        struct Stack_String {
    data: Vec<i32>,           data: Vec<String>,
}                         }

impl Stack_i32 {          impl Stack_String {
    fn push(&mut self, value: i32) { ... }
    fn pop(&mut self) -> Option<i32> { ... }
}                         }
}

Key Insight: At runtime, there is no generic Stack<T>. The compiler has generated completely specialized versions like Stack_i32 and Stack_String. Each has optimal machine code for that specific type.

Performance Implications:

Generic code in Rust:
- NO vtable lookups (unlike trait objects)
- NO boxing/unboxing
- NO type checking at runtime
- SAME performance as hand-written specialized code
- Compiler can inline aggressively

Example:
stack.push(42);  // For Stack<i32>, compiles to direct memory write
                 // No indirection, no dynamic dispatch, just raw speed

Trade-off:

• Pro: Maximum runtime performance, zero overhead
• Con: Larger binary size (more code for each type)
• Con: Longer compile times (compiler generates more code)

Comparison with Other Languages:

C++ Templates:  Similar monomorphization approach
Java Generics:  Type erasure - generics removed at runtime, uses Object
C# Generics:    Hybrid - value types specialized, reference types shared
Go:            Just added generics (Go 1.18+), uses dictionary passing

Const Generics: Compile-Time Constants

Const generics allow you to parameterize types by values (not just types). This enables compile-time size guarantees.

Without Const Generics (old approach):

#![allow(unused)]
fn main() {
// Had to use associated constants or separate types
struct Stack<T> {
    data: Vec<T>,  // Heap allocated, dynamic size
}

// Or use macros to generate fixed-size variants
array_stack!(ArrayStack10, 10);
array_stack!(ArrayStack20, 20);
// Ugly and limited!
}

With Const Generics:

#![allow(unused)]
fn main() {
struct Stack<T, const N: usize> {
    data: [T; N],  // Fixed size, known at compile time!
}

// Can use any size!
let small: Stack<i32, 10> = Stack::new();
let big: Stack<i32, 1000> = Stack::new();
let huge: Stack<i32, 100000> = Stack::new();
}

Benefits:

1. Compile-Time Size Guarantees:

   #![allow(unused)]
   fn main() {
   let stack: Stack<i32, 100>;
   // Compiler KNOWS this is exactly 400 bytes (100 * 4 bytes)
   // Can allocate on stack instead of heap
   // Can optimize memory layout
   }

2. Zero Runtime Cost:

   #![allow(unused)]
   fn main() {
   // Size is known at compile time
   impl<T, const N: usize> Stack<T, N> {
       fn capacity(&self) -> usize {
           N  // This is a compile-time constant!
              // No memory load, just immediate value
       }
   }
   }

3. Type Safety with Sizes:

   #![allow(unused)]
   fn main() {
   fn process_exactly_10<T>(stack: Stack<T, 10>) {
       // Can ONLY call with 10-element stack
       // Compile error if you pass Stack<T, 5> or Stack<T, 20>
   }
   }

MaybeUninit: Safe Uninitialized Memory

The Problem: Fixed-size arrays [T; N] require all elements to be initialized immediately. But for a data structure like Stack, we want to allocate space without initializing all elements.

Unsafe Approach (Don’t do this):

#![allow(unused)]
fn main() {
struct Stack<T, const N: usize> {
    data: [T; N],  // ERROR: Can't create this without N values of T!
    len: usize,
}

// How to create empty stack? Can't!
// Would need N default values, but T might not have Default
}

MaybeUninit Solution:

#![allow(unused)]
fn main() {
use std::mem::MaybeUninit;

struct Stack<T, const N: usize> {
    data: [MaybeUninit<T>; N],  // ✓ Can create without initializing!
    len: usize,                  // Track how many are initialized
}
}

What is MaybeUninit?

MaybeUninit<T> is a wrapper that can hold either:

• An initialized value of type T
• Uninitialized memory (garbage bytes)

It’s the safe way to work with uninitialized memory in Rust.

Key Operations:

#![allow(unused)]
fn main() {
// 1. Create uninitialized memory
let mut uninit: MaybeUninit<i32> = MaybeUninit::uninit();
// This is just raw memory, contains garbage

// 2. Write a value into it
uninit.write(42);  // Now contains 42

// 3. Read the value (UNSAFE - you must know it's initialized!)
let value: i32 = unsafe { uninit.assume_init_read() };

// 4. Get a reference (UNSAFE - you must know it's initialized!)
let reference: &i32 = unsafe { uninit.assume_init_ref() };

// 5. Drop an initialized value (UNSAFE - you must know it's initialized!)
unsafe { uninit.assume_init_drop() };
}

Why Unsafe?

Reading uninitialized memory is undefined behavior:

#![allow(unused)]
fn main() {
let uninit: MaybeUninit<i32> = MaybeUninit::uninit();
// Contains random garbage bytes, could be anything!

let value = unsafe { uninit.assume_init() };
// UNDEFINED BEHAVIOR! Reading garbage as an i32
// Could crash, could produce random numbers, could summon demons
}

Safe Pattern in Stack:

#![allow(unused)]
fn main() {
impl<T, const N: usize> Stack<T, N> {
    fn push(&mut self, value: T) {
        // Only write to uninitialized slots
        if self.len < N {
            self.data[self.len].write(value);  // Safe: writing to uninit
            self.len += 1;
        }
    }

    fn pop(&mut self) -> Option<T> {
        if self.len > 0 {
            self.len -= 1;
            // Safe: we KNOW data[len] is initialized (len tracks this!)
            Some(unsafe { self.data[self.len].assume_init_read() })
        } else {
            None
        }
    }
}
}

The Safety Invariant: We maintain len to track which elements are initialized. Elements 0..len are initialized, len..N are uninitialized.

Memory Layout Example:

Stack<i32, 5> with len=3 after pushing 10, 20, 30:

[  10  |  20  |  30  |  ??  |  ??  ]
  ↑      ↑      ↑      ↑      ↑
data[0] data[1] data[2] data[3] data[4]
                 len=3
   <--initialized--> <--uninitialized-->

Safe to read: data[0], data[1], data[2]
UNSAFE to read: data[3], data[4] (garbage!)

Why Not Use Option?

#![allow(unused)]
fn main() {
// Why not this?
struct Stack<T, const N: usize> {
    data: [Option<T>; N],  // Each element is Option
}
}

Answer: Memory waste!

Option<i32> = 8 bytes (4 for i32, 4 for discriminant)
MaybeUninit<i32> = 4 bytes (just the i32)

For Stack<i32, 100>:
- With Option: 100 * 8 = 800 bytes
- With MaybeUninit: 100 * 4 = 400 bytes + 8 bytes for len = 408 bytes

Nearly 2x more memory with Option!

Plus, Option<T> requires T to be valid, so you still can’t have “truly” uninitialized memory.

Trait Bounds: Constraining Generic Types

Trait bounds specify what operations a generic type must support. They’re like contracts: “To use T in this code, T must implement these traits.”

The Problem Without Bounds:

#![allow(unused)]
fn main() {
struct BinaryHeap<T> {
    data: Vec<T>,
}

impl<T> BinaryHeap<T> {
    fn push(&mut self, value: T) {
        self.data.push(value);
        // ERROR: How do we compare values to maintain heap property?
        // if self.data[i] > self.data[parent]  // ← Can't do this!
        //    T might not have comparison!
    }
}
}

Solution: Add Trait Bounds:

#![allow(unused)]
fn main() {
struct BinaryHeap<T: Ord> {  // ← Bound: T must implement Ord
    data: Vec<T>,
}

impl<T: Ord> BinaryHeap<T> {
    fn push(&mut self, value: T) {
        self.data.push(value);
        // ✓ Now we can compare!
        if self.data[i] > self.data[parent] {
            // Works because T: Ord guarantees > operator
        }
    }
}
}

Common Trait Bounds:

#![allow(unused)]
fn main() {
// 1. Ord - Total ordering (can compare any two values)
fn sort<T: Ord>(items: &mut [T]) {
    // Can use <, >, ==, etc.
}

// 2. Clone - Can be duplicated
fn duplicate<T: Clone>(value: &T) -> T {
    value.clone()
}

// 3. Copy - Can be bitwise copied (implicit clone)
fn double<T: Copy>(value: T) -> (T, T) {
    (value, value)  // Both use same value, but T is Copy
}

// 4. Default - Has a default value
fn create_with_default<T: Default>() -> T {
    T::default()
}

// 5. Debug - Can be formatted with {:?}
fn print_debug<T: Debug>(value: &T) {
    println!("{:?}", value);
}

// 6. Display - Can be formatted with {}
fn print<T: Display>(value: &T) {
    println!("{}", value);
}
}

Multiple Bounds:

#![allow(unused)]
fn main() {
// Require BOTH Ord and Copy
fn find_max<T: Ord + Copy>(items: &[T]) -> Option<T> {
    items.iter().copied().max()
}

// Alternative syntax (where clause)
fn find_max<T>(items: &[T]) -> Option<T>
where
    T: Ord + Copy,
{
    items.iter().copied().max()
}
}

Why Ord vs PartialOrd?

#![allow(unused)]
fn main() {
// PartialOrd: Partial ordering (some values can't be compared)
// Example: f32, f64 (NaN is not comparable to anything)
assert!(f32::NAN < 1.0);  // false
assert!(f32::NAN > 1.0);  // false
assert!(f32::NAN == f32::NAN);  // false

// Ord: Total ordering (ALL values can be compared)
// Example: i32, String, custom types
// For BinaryHeap, we NEED total ordering
// Can't have heap property if some elements are incomparable!

impl<T: Ord> BinaryHeap<T> {  // Must be Ord, not PartialOrd
    // Heap needs to compare ANY two elements
    // If using PartialOrd, what if comparison returns None?
}
}

Conditional Implementation:

#![allow(unused)]
fn main() {
// Implement Debug ONLY when T implements Debug
impl<T: Debug, const N: usize> Debug for Stack<T, N> {
    fn fmt(&self, f: &mut Formatter) -> Result {
        f.debug_list()
            .entries(/* iterate and format T values */)
            .finish()
    }
}

// This means:
let stack_i32: Stack<i32, 10> = Stack::new();
println!("{:?}", stack_i32);  // ✓ Works, i32: Debug

let stack_fn: Stack<fn(), 10> = Stack::new();
println!("{:?}", stack_fn);  // ✗ ERROR: fn() doesn't implement Debug
}

Associated Types vs Generic Parameters

Generic Type Parameters (<T>):

#![allow(unused)]
fn main() {
trait Iterator<T> {  // T is generic parameter
    fn next(&mut self) -> Option<T>;
}

// Problem: Could implement Iterator multiple times!
impl Iterator<i32> for MyType { ... }
impl Iterator<String> for MyType { ... }

// Which one to call?
let mut iter = MyType::new();
iter.next();  // Returns i32 or String???
}

Associated Types:

#![allow(unused)]
fn main() {
trait Iterator {
    type Item;  // Associated type, not generic parameter
    fn next(&mut self) -> Option<Self::Item>;
}

// Can ONLY implement Iterator once per type
impl Iterator for MyType {
    type Item = i32;  // Pick specific type
    fn next(&mut self) -> Option<i32> { ... }
}

// Clear: MyType yields i32
let mut iter = MyType::new();
let item: Option<i32> = iter.next();
}

When to Use Each:

Use Generic Parameters when:

• Multiple implementations possible for the same type
• Caller chooses the type

#![allow(unused)]
fn main() {
trait From<T> {  // Can implement From<i32>, From<String>, etc.
    fn from(value: T) -> Self;
}
}

Use Associated Types when:

• Only one implementation makes sense
• Implementation chooses the type

#![allow(unused)]
fn main() {
trait Iterator {
    type Item;  // Iterator determines what it yields
}

trait Container {
    type Item;  // Container determines what it stores
}
}

Generic Associated Types (GATs)

Generic Associated Types allow associated types to themselves be generic. This is advanced but powerful.

The Problem Without GATs:

#![allow(unused)]
fn main() {
trait Container<T> {
    type Iter: Iterator<Item = T>;  // Error: lifetime issue

    fn iter(&self) -> Self::Iter;  // How long does iterator live?
}
}

With GATs:

#![allow(unused)]
fn main() {
trait Container<T> {
    type Iter<'a>: Iterator<Item = &'a T>  // GAT: generic over lifetime!
    where
        Self: 'a,
        T: 'a;

    fn iter(&self) -> Self::Iter<'_>;  // Returns iterator borrowing self
}

impl<T, const N: usize> Container<T> for Stack<T, N> {
    type Iter<'a> = StackIter<'a, T, N>  // Concrete type for this lifetime
    where
        T: 'a;

    fn iter(&self) -> Self::Iter<'_> {
        StackIter { stack: self, index: 0 }
    }
}
}

Why This Matters: Allows iterators that borrow from the container, which is how Rust’s standard library works.

Type-State Pattern with Zero-Sized Types

Type-state pattern uses the type system to encode state machine states, preventing invalid transitions at compile time.

Zero-Sized Types (ZSTs) are types that compile to nothing:

#![allow(unused)]
fn main() {
struct Empty;  // No fields
struct Ready;  // No fields

// These have ZERO size at runtime!
assert_eq!(std::mem::size_of::<Empty>(), 0);
assert_eq!(std::mem::size_of::<Ready>(), 0);
}

Using ZSTs for Type-State:

#![allow(unused)]
fn main() {
struct Builder<T, State> {
    value: Option<T>,
    _state: PhantomData<State>,  // ZST marker, zero runtime cost
}

impl<T> Builder<T, Empty> {
    fn new() -> Self {
        Builder { value: None, _state: PhantomData }
    }

    fn with_value(self, value: T) -> Builder<T, Ready> {
        Builder { value: Some(value), _state: PhantomData }
    }
}

impl<T> Builder<T, Ready> {
    fn build(self) -> T {  // Only Ready state can build!
        self.value.unwrap()
    }
}

// Usage:
let builder = Builder::new();  // Builder<T, Empty>
// builder.build();  // ✗ COMPILE ERROR: build() not on Empty

let builder = builder.with_value(42);  // Builder<i32, Ready>
let value = builder.build();  // ✓ OK: build() available on Ready
}

Benefits:

• Compile-time safety: Invalid state transitions impossible
• Zero runtime cost: State marker compiles away completely
• Self-documenting: API makes valid usage clear

Real-World Example:

#![allow(unused)]
fn main() {
// File builder with type-states
let file = FileBuilder::new()  // Builder<Unopened>
    .path("/tmp/data.txt")     // Builder<Unopened>
    .open()                     // Builder<Opened> - state change!
    .write(b"data")            // Builder<Opened>
    .close();                   // File - final state

// Can't write before opening (compile error)
// Can't open twice (compile error)
// Can't close before opening (compile error)
}

Connection to This Project

In this project, you’ll use all these concepts:

1. Generics: Stack<T, N>, RingBuffer<T, N>, BinaryHeap<T, N>
2. Monomorphization: Compiler generates specialized code for each type
3. Const Generics: const N: usize for compile-time sizes
4. MaybeUninit: Safe uninitialized memory management
5. Trait Bounds: T: Ord for heap, T: Clone for builder
6. Associated Types: Container::Iter<'a> for iterators
7. GATs: Lifetime-parameterized associated types
8. Type-State: Builder pattern with Empty, Configured, Ready states
9. ZSTs: State markers with zero runtime cost

Key Learning Points:

• Generic code achieves zero-cost abstraction through monomorphization
• Const generics enable compile-time size guarantees
• MaybeUninit provides safe low-level memory control
• Trait bounds make generic code type-safe
• Type-state pattern prevents invalid operations at compile time

Build the Project

Milestone 1: Generic Fixed-Size Stack with Const Generics

Goal: Implement a generic stack Stack<T, const N: usize> backed by a fixed-size array.

Concepts:

• Const generic parameters (const N: usize)
• MaybeUninit<T> for uninitialized memory
• Generic type parameter <T> with trait bounds
• Monomorphization and zero-cost abstractions
• Compile-time capacity checks

Implementation Steps:

1. Define the Stack<T, const N: usize> struct:

   • Use [MaybeUninit<T>; N] for storage (allows uninitialized elements)
   • Add len: usize field to track the number of elements
   • Derive Debug only when T: Debug

2. Implement new() constructor:

   • Initialize storage with MaybeUninit::uninit_array()
   • Set len to 0
   • Return Self { storage, len }

3. Implement push(&mut self, value: T) -> Result<(), T>:

   • Check if self.len < N (capacity check)
   • If full, return Err(value) (ownership back to caller)
   • Use MaybeUninit::write() to initialize the slot at self.len
   • Increment self.len
   • Return Ok(())

4. Implement pop(&mut self) -> Option<T>:

   • Check if self.len > 0
   • If empty, return None
   • Decrement self.len
   • Use MaybeUninit::assume_init_read() to read the value
   • Return Some(value)

5. Implement peek(&self) -> Option<&T>:

   • Check if self.len > 0
   • If empty, return None
   • Get reference to self.storage[self.len - 1]
   • Use MaybeUninit::assume_init_ref() to get &T
   • Return Some(&value)

6. Implement Drop for cleanup:

   • Loop from 0..self.len
   • Call MaybeUninit::assume_init_drop() on each element
   • This ensures T’s destructor runs for all pushed elements

Starter Code:

#![allow(unused)]
fn main() {
use std::mem::MaybeUninit;

pub struct Stack<T, const N: usize> {
    // TODO: Add storage field using MaybeUninit<T>
    // Hint: [MaybeUninit<T>; N]

    // TODO: Add len field to track number of elements
}

impl<T, const N: usize> Stack<T, N> {
    pub fn new() -> Self {
        // TODO: Initialize storage with MaybeUninit::uninit_array()
        // TODO: Set len to 0
        todo!()
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        // TODO: Check if stack is full (len >= N)
        // If full, return Err(value)
        // TODO: Write value to storage[len] using MaybeUninit::write()
        // TODO: Increment len
        // TODO: Return Ok(())
        todo!()
    }

    pub fn pop(&mut self) -> Option<T> {
        // TODO: Check if stack is empty (len == 0)
        // If empty, return None
        // TODO: Decrement len
        // TODO: Read value from storage[len] using assume_init_read()
        // TODO: Return Some(value)
        todo!()
    }

    pub fn peek(&self) -> Option<&T> {
        // TODO: Check if stack is empty
        // If empty, return None
        // TODO: Get reference to storage[len - 1]
        // Use assume_init_ref() to get &T
        // TODO: Return Some(&value)
        todo!()
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn is_full(&self) -> bool {
        self.len == N
    }

    pub fn capacity(&self) -> usize {
        N
    }
}

impl<T, const N: usize> Drop for Stack<T, N> {
    fn drop(&mut self) {
        // TODO: Loop from 0..self.len
        // For each index, call assume_init_drop() on storage[i]
        // This ensures T's destructor runs
        todo!()
    }
}

// Only implement Debug when T implements Debug
impl<T: std::fmt::Debug, const N: usize> std::fmt::Debug for Stack<T, N> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_list()
            .entries((0..self.len).map(|i| unsafe {
                self.storage[i].assume_init_ref()
            }))
            .finish()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_new_stack_is_empty() {
        let stack: Stack<i32, 10> = Stack::new();
        assert_eq!(stack.len(), 0);
        assert!(stack.is_empty());
        assert_eq!(stack.capacity(), 10);
    }

    #[test]
    fn test_push_and_pop() {
        let mut stack: Stack<i32, 5> = Stack::new();

        assert_eq!(stack.push(1), Ok(()));
        assert_eq!(stack.push(2), Ok(()));
        assert_eq!(stack.push(3), Ok(()));
        assert_eq!(stack.len(), 3);

        assert_eq!(stack.pop(), Some(3));
        assert_eq!(stack.pop(), Some(2));
        assert_eq!(stack.pop(), Some(1));
        assert_eq!(stack.pop(), None);
    }

    #[test]
    fn test_push_when_full() {
        let mut stack: Stack<i32, 3> = Stack::new();

        assert_eq!(stack.push(1), Ok(()));
        assert_eq!(stack.push(2), Ok(()));
        assert_eq!(stack.push(3), Ok(()));
        assert!(stack.is_full());

        // Should return the value back since stack is full
        assert_eq!(stack.push(4), Err(4));
    }

    #[test]
    fn test_peek() {
        let mut stack: Stack<String, 5> = Stack::new();

        assert_eq!(stack.peek(), None);

        stack.push("hello".to_string()).unwrap();
        stack.push("world".to_string()).unwrap();

        assert_eq!(stack.peek(), Some(&"world".to_string()));
        assert_eq!(stack.len(), 2); // peek doesn't modify
    }

    #[test]
    fn test_drop_calls_destructor() {
        use std::sync::Arc;

        let value = Arc::new(42);
        assert_eq!(Arc::strong_count(&value), 1);

        {
            let mut stack: Stack<Arc<i32>, 5> = Stack::new();
            stack.push(Arc::clone(&value)).unwrap();
            stack.push(Arc::clone(&value)).unwrap();
            assert_eq!(Arc::strong_count(&value), 3);
        } // stack dropped here

        // Should be back to 1 (destructors ran)
        assert_eq!(Arc::strong_count(&value), 1);
    }

    #[test]
    fn test_different_types() {
        // Test with i32
        let mut stack_i32: Stack<i32, 10> = Stack::new();
        stack_i32.push(42).unwrap();
        assert_eq!(stack_i32.pop(), Some(42));

        // Test with String
        let mut stack_str: Stack<String, 10> = Stack::new();
        stack_str.push("test".to_string()).unwrap();
        assert_eq!(stack_str.pop(), Some("test".to_string()));

        // Test with custom struct
        #[derive(Debug, PartialEq)]
        struct Point { x: i32, y: i32 }

        let mut stack_point: Stack<Point, 10> = Stack::new();
        stack_point.push(Point { x: 1, y: 2 }).unwrap();
        assert_eq!(stack_point.pop(), Some(Point { x: 1, y: 2 }));
    }
}
}

Check Your Understanding:

1. Why do we use MaybeUninit<T> instead of Option<T> for storage?
2. What would happen if we didn’t implement Drop for types that allocate?
3. How does the compiler generate different code for Stack<i32, 100> vs Stack<String, 100>?

Milestone 2: Generic Ring Buffer with Circular Queuing

Goal: Implement a generic ring buffer RingBuffer<T, const N: usize> with circular indexing and FIFO behavior.

Concepts:

• Circular buffer algorithm with modulo arithmetic
• Distinguishing full vs empty states
• Generic constraints with Default trait
• Iterator implementation for generic types
• Compile-time capacity validation

Implementation Steps:

1. Define the RingBuffer<T, const N: usize> struct:

   • Use [MaybeUninit<T>; N] for storage
   • Add head: usize (read position)
   • Add tail: usize (write position)
   • Add len: usize (number of elements, distinguishes full from empty)

2. Implement new() and push(&mut self, value: T) -> Result<(), T>:

   • In push: write to storage[tail], increment tail with (tail + 1) % N
   • If buffer is full (len == N), decide: overwrite oldest or return error
   • Implementation choice: overwrite and advance head (circular behavior)

3. Implement pop(&mut self) -> Option<T>:

   • Check if empty (len == 0)
   • Read from storage[head], increment head with (head + 1) % N
   • Decrement len

4. Implement IntoIterator for consuming iteration:

   • Create iterator struct RingBufferIter<T, const N: usize>
   • Implement Iterator trait with next() calling pop()

5. Handle edge cases:

   • Empty buffer: head == tail && len == 0
   • Full buffer: head == tail && len == N
   • Wraparound: indices wrap using modulo

Starter Code:

#![allow(unused)]
fn main() {
use std::mem::MaybeUninit;

pub struct RingBuffer<T, const N: usize> {
    storage: [MaybeUninit<T>; N],
    head: usize,    // Read position
    tail: usize,    // Write position
    len: usize,     // Number of elements
}

impl<T, const N: usize> RingBuffer<T, N> {
    pub fn new() -> Self {
        // TODO: Initialize with MaybeUninit::uninit_array()
        // Set head, tail, len to 0

        todo!()
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        // TODO: Check if buffer is full (len == N)

        // If full, overwrite oldest element:
        // - Write to storage[tail]
        // - Advance tail: (tail + 1) % N
        // - Advance head: (head + 1) % N (to skip overwritten element)
        // - len stays at N

        // If not full:
        // - Write to storage[tail]
        // - Advance tail: (tail + 1) % N
        // - Increment len

        todo!()
    }

    pub fn pop(&mut self) -> Option<T> {
        // TODO: Check if empty (len == 0)
        // If empty, return None

        // TODO: Read from storage[head] using assume_init_read()

        // TODO: Advance head: (head + 1) % N

        // TODO: Decrement len

        // TODO: Return Some(value)

        todo!()
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn is_full(&self) -> bool {
        self.len == N
    }

    pub fn capacity(&self) -> usize {
        N
    }
}

impl<T, const N: usize> Drop for RingBuffer<T, N> {
    fn drop(&mut self) {
        // TODO: Pop all remaining elements to run destructors
        while self.pop().is_some() {}
    }
}

// Iterator support
pub struct RingBufferIter<T, const N: usize> {
    buffer: RingBuffer<T, N>,
}

impl<T, const N: usize> Iterator for RingBufferIter<T, N> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        // TODO: Call pop() on the buffer
        self.buffer.pop()
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let len = self.buffer.len();
        (len, Some(len))
    }
}

impl<T, const N: usize> IntoIterator for RingBuffer<T, N> {
    type Item = T;
    type IntoIter = RingBufferIter<T, N>;

    fn into_iter(self) -> Self::IntoIter {
        RingBufferIter { buffer: self }
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_ring_buffer_push_pop() {
        let mut buf: RingBuffer<i32, 4> = RingBuffer::new();

        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        assert_eq!(buf.pop(), Some(1));
        assert_eq!(buf.pop(), Some(2));

        buf.push(4).unwrap();
        buf.push(5).unwrap();

        assert_eq!(buf.pop(), Some(3));
        assert_eq!(buf.pop(), Some(4));
        assert_eq!(buf.pop(), Some(5));
        assert_eq!(buf.pop(), None);
    }

    #[test]
    fn test_ring_buffer_wraparound() {
        let mut buf: RingBuffer<i32, 3> = RingBuffer::new();

        // Fill buffer
        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        // Now full, next push should overwrite
        buf.push(4).unwrap(); // Overwrites 1
        buf.push(5).unwrap(); // Overwrites 2

        assert_eq!(buf.pop(), Some(3));
        assert_eq!(buf.pop(), Some(4));
        assert_eq!(buf.pop(), Some(5));
        assert_eq!(buf.pop(), None);
    }

    #[test]
    fn test_ring_buffer_iterator() {
        let mut buf: RingBuffer<i32, 5> = RingBuffer::new();

        buf.push(10).unwrap();
        buf.push(20).unwrap();
        buf.push(30).unwrap();

        let collected: Vec<i32> = buf.into_iter().collect();
        assert_eq!(collected, vec![10, 20, 30]);
    }

    #[test]
    fn test_ring_buffer_fifo_order() {
        let mut buf: RingBuffer<char, 4> = RingBuffer::new();

        buf.push('a').unwrap();
        buf.push('b').unwrap();
        buf.push('c').unwrap();

        assert_eq!(buf.pop(), Some('a')); // FIFO: first in, first out

        buf.push('d').unwrap();
        buf.push('e').unwrap();

        assert_eq!(buf.pop(), Some('b'));
        assert_eq!(buf.pop(), Some('c'));
        assert_eq!(buf.pop(), Some('d'));
    }

    #[test]
    fn test_ring_buffer_size_hint() {
        let mut buf: RingBuffer<i32, 5> = RingBuffer::new();

        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        let iter = buf.into_iter();
        assert_eq!(iter.size_hint(), (3, Some(3)));
    }
}
}

Check Your Understanding:

1. How does the ring buffer distinguish between full and empty states when head == tail?
2. Why do we use modulo arithmetic instead of checking bounds explicitly?
3. What are the trade-offs between overwriting old data vs returning an error when full?

Milestone 3: Generic Binary Heap with Ordering

Goal: Implement a generic min-heap or max-heap BinaryHeap<T, const N: usize> with trait bounds for ordering.

Concepts:

• Heap property: parent-child ordering relationships
• Generic trait bounds: T: Ord for comparison
• Heap algorithms: heapify_up, heapify_down
• Parent/child index calculations: parent = (i - 1) / 2, left = 2*i + 1
• Comparison abstraction with trait bounds

Implementation Steps:

1. Define BinaryHeap<T, const N: usize> struct:

   • Storage: [MaybeUninit<T>; N]
   • Track len: usize
   • Constraint: T: Ord (required for comparison)

2. Implement push(&mut self, value: T) -> Result<(), T>:

   • Check capacity (len < N)
   • Insert at storage[len]
   • Call heapify_up(len) to restore heap property
   • Increment len

3. Implement heapify_up(&mut self, index: usize):

   • While index > 0:
     • Calculate parent = (index - 1) / 2
     • Compare storage[index] with storage[parent]
     • If heap property violated, swap and continue with parent
     • Otherwise, break

4. Implement pop(&mut self) -> Option<T>:

   • Check if empty
   • Save root (storage[0])
   • Move last element to root
   • Decrement len
   • Call heapify_down(0) to restore heap property
   • Return saved root

5. Implement heapify_down(&mut self, index: usize):

   • While index has children:
     • Calculate left = 2 * index + 1, right = 2 * index + 2
     • Find smallest/largest child
     • If heap property violated, swap and continue with child
     • Otherwise, break

6. Add peek(&self) -> Option<&T> to view root without removing

Starter Code:

#![allow(unused)]
fn main() {
use std::mem::MaybeUninit;

pub struct BinaryHeap<T: Ord, const N: usize> {
    storage: [MaybeUninit<T>; N],
    len: usize,
}

impl<T: Ord, const N: usize> BinaryHeap<T, N> {
    pub fn new() -> Self {
        Self {
            storage: MaybeUninit::uninit_array(),
            len: 0,
        }
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        // TODO: Check if full
        if self.len >= N {
            return Err(value);
        }

        // TODO: Insert at end
        self.storage[self.len].write(value);

        // TODO: Heapify up from len
        self.heapify_up(self.len);

        self.len += 1;
        Ok(())
    }

    fn heapify_up(&mut self, mut index: usize) {
        // TODO: While index > 0
        while index > 0 {
            // TODO: Calculate parent index
            let parent = (index - 1) / 2;

            // TODO: Compare child with parent
            // Hint: Use assume_init_ref() to get &T for comparison
            let child_ref = unsafe { self.storage[index].assume_init_ref() };
            let parent_ref = unsafe { self.storage[parent].assume_init_ref() };

            // For max-heap: if child > parent, swap
            // For min-heap: if child < parent, swap
            // TODO: Implement max-heap (largest at root)
            if child_ref > parent_ref {
                self.storage.swap(index, parent);
                index = parent;
            } else {
                break;
            }
        }
    }

    pub fn pop(&mut self) -> Option<T> {
        // TODO: Check if empty
        if self.len == 0 {
            return None;
        }

        // TODO: Save root element
        self.len -= 1;

        // Swap root with last element
        self.storage.swap(0, self.len);

        // Read the (now last) element
        let value = unsafe { self.storage[self.len].assume_init_read() };

        // TODO: Heapify down from root (if not empty)
        if self.len > 0 {
            self.heapify_down(0);
        }

        Some(value)
    }

    fn heapify_down(&mut self, mut index: usize) {
        loop {
            // TODO: Calculate left and right child indices
            let left = 2 * index + 1;
            let right = 2 * index + 2;

            // TODO: Find largest among parent, left, right
            let mut largest = index;

            if left < self.len {
                let left_ref = unsafe { self.storage[left].assume_init_ref() };
                let largest_ref = unsafe { self.storage[largest].assume_init_ref() };
                if left_ref > largest_ref {
                    largest = left;
                }
            }

            if right < self.len {
                let right_ref = unsafe { self.storage[right].assume_init_ref() };
                let largest_ref = unsafe { self.storage[largest].assume_init_ref() };
                if right_ref > largest_ref {
                    largest = right;
                }
            }

            // TODO: If largest is not parent, swap and continue
            if largest != index {
                self.storage.swap(index, largest);
                index = largest;
            } else {
                break;
            }
        }
    }

    pub fn peek(&self) -> Option<&T> {
        // TODO: Return reference to root if not empty
        if self.len > 0 {
            Some(unsafe { self.storage[0].assume_init_ref() })
        } else {
            None
        }
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }
}

impl<T: Ord, const N: usize> Drop for BinaryHeap<T, N> {
    fn drop(&mut self) {
        for i in 0..self.len {
            unsafe {
                self.storage[i].assume_init_drop();
            }
        }
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_heap_push_pop_order() {
        let mut heap: BinaryHeap<i32, 10> = BinaryHeap::new();

        heap.push(5).unwrap();
        heap.push(3).unwrap();
        heap.push(7).unwrap();
        heap.push(1).unwrap();
        heap.push(9).unwrap();

        // Max-heap should pop in descending order
        assert_eq!(heap.pop(), Some(9));
        assert_eq!(heap.pop(), Some(7));
        assert_eq!(heap.pop(), Some(5));
        assert_eq!(heap.pop(), Some(3));
        assert_eq!(heap.pop(), Some(1));
        assert_eq!(heap.pop(), None);
    }

    #[test]
    fn test_heap_peek() {
        let mut heap: BinaryHeap<i32, 5> = BinaryHeap::new();

        assert_eq!(heap.peek(), None);

        heap.push(10).unwrap();
        heap.push(20).unwrap();
        heap.push(5).unwrap();

        assert_eq!(heap.peek(), Some(&20)); // Max element
        assert_eq!(heap.len(), 3); // Peek doesn't remove
    }

    #[test]
    fn test_heap_with_strings() {
        let mut heap: BinaryHeap<String, 5> = BinaryHeap::new();

        heap.push("apple".to_string()).unwrap();
        heap.push("zebra".to_string()).unwrap();
        heap.push("banana".to_string()).unwrap();

        // Lexicographic order
        assert_eq!(heap.pop(), Some("zebra".to_string()));
        assert_eq!(heap.pop(), Some("banana".to_string()));
        assert_eq!(heap.pop(), Some("apple".to_string()));
    }

    #[test]
    fn test_heap_capacity() {
        let mut heap: BinaryHeap<i32, 3> = BinaryHeap::new();

        assert_eq!(heap.push(1), Ok(()));
        assert_eq!(heap.push(2), Ok(()));
        assert_eq!(heap.push(3), Ok(()));

        // Should fail when full
        assert_eq!(heap.push(4), Err(4));
    }

    #[test]
    fn test_heap_property_maintained() {
        let mut heap: BinaryHeap<i32, 10> = BinaryHeap::new();

        for i in 0..10 {
            heap.push(i).unwrap();
        }

        let mut prev = heap.pop().unwrap();
        while let Some(current) = heap.pop() {
            assert!(prev >= current, "Heap property violated");
            prev = current;
        }
    }
}
}

Check Your Understanding:

1. How does the heap property differ between min-heap and max-heap?
2. Why is T: Ord required instead of T: PartialOrd for the heap?
3. What is the time complexity of push and pop operations?

Milestone 4: Generic Container Trait with Associated Types

Goal: Define a generic Container<T> trait with associated types for iterators, and implement it for all data structures.

Concepts:

• Trait definition with associated types
• Generic trait implementations
• Iterator associated types
• Trait bounds for implementations
• Code reuse through trait abstractions

Implementation Steps:

1. Define Container<T> trait:

   • Associated type Iter for iterator
   • Required methods: len(), is_empty(), clear(), iter()
   • Optional methods with default implementations

2. Implement Container<T> for Stack<T, N>:

   • Define StackIter<'a, T, N> iterator struct
   • Implement Iterator trait for StackIter
   • Connect via associated type Iter = StackIter<'a, T, N>

3. Implement Container<T> for RingBuffer<T, N> and BinaryHeap<T, N>:

   • Create corresponding iterator types
   • Implement trait methods

4. Add generic function using Container<T> trait bound:

   • Example: fn print_all<C: Container<T>, T: Display>(container: &C)
   • Demonstrates polymorphism through trait bounds

Starter Code:

#![allow(unused)]
fn main() {
use std::fmt::Display;

pub trait Container<T> {
    type Iter<'a>: Iterator<Item = &'a T>
    where
        T: 'a,
        Self: 'a;

    fn len(&self) -> usize;
    fn is_empty(&self) -> bool {
        self.len() == 0
    }
    fn iter(&self) -> Self::Iter<'_>;

    // Optional: mutable clear
    fn clear(&mut self);
}

// Implement for Stack
impl<T, const N: usize> Container<T> for Stack<T, N> {
    type Iter<'a> = StackIter<'a, T, N>
    where
        T: 'a;

    fn len(&self) -> usize {
        self.len
    }

    fn iter(&self) -> Self::Iter<'_> {
        StackIter {
            stack: self,
            index: 0,
        }
    }

    fn clear(&mut self) {
        // TODO: Pop all elements
        while self.pop().is_some() {}
    }
}

pub struct StackIter<'a, T, const N: usize> {
    stack: &'a Stack<T, N>,
    index: usize,
}

impl<'a, T, const N: usize> Iterator for StackIter<'a, T, N> {
    type Item = &'a T;

    fn next(&mut self) -> Option<Self::Item> {
        // TODO: Iterate from bottom to top (0 to len)
        if self.index < self.stack.len {
            let item = unsafe { self.stack.storage[self.index].assume_init_ref() };
            self.index += 1;
            Some(item)
        } else {
            None
        }
    }
}

// Generic function using Container trait
pub fn print_all<T, C>(container: &C)
where
    T: Display,
    C: Container<T>,
{
    for item in container.iter() {
        println!("{}", item);
    }
}

// Generic function to count elements matching predicate
pub fn count_matching<T, C, F>(container: &C, predicate: F) -> usize
where
    C: Container<T>,
    F: Fn(&T) -> bool,
{
    // TODO: Use iterator and filter with predicate
    container.iter().filter(|item| predicate(item)).count()
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_stack_container_trait() {
        let mut stack: Stack<i32, 10> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();

        assert_eq!(stack.len(), 3);
        assert!(!stack.is_empty());

        let collected: Vec<&i32> = stack.iter().collect();
        assert_eq!(collected, vec![&1, &2, &3]);
    }

    #[test]
    fn test_container_clear() {
        let mut stack: Stack<i32, 5> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();

        stack.clear();
        assert_eq!(stack.len(), 0);
        assert!(stack.is_empty());
    }

    #[test]
    fn test_generic_print_all() {
        let mut stack: Stack<i32, 5> = Stack::new();
        stack.push(10).unwrap();
        stack.push(20).unwrap();

        // Should compile and run without panic
        print_all(&stack);
    }

    #[test]
    fn test_count_matching() {
        let mut stack: Stack<i32, 10> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();
        stack.push(4).unwrap();
        stack.push(5).unwrap();

        let even_count = count_matching(&stack, |&x| x % 2 == 0);
        assert_eq!(even_count, 2); // 2 and 4

        let greater_than_3 = count_matching(&stack, |&x| x > 3);
        assert_eq!(greater_than_3, 2); // 4 and 5
    }

    #[test]
    fn test_container_polymorphism() {
        fn sum_all<T, C>(container: &C) -> T
        where
            T: std::ops::Add<Output = T> + Default + Copy,
            C: Container<T>,
        {
            container.iter().copied().fold(T::default(), |acc, x| acc + x)
        }

        let mut stack: Stack<i32, 5> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();

        assert_eq!(sum_all(&stack), 6);
    }
}
}

Check Your Understanding:

1. Why use associated types (type Iter) instead of generic type parameters?
2. How does the Container trait enable polymorphism across different data structures?
3. What are the benefits of GATs (Generic Associated Types) in the Iter definition?

Milestone 5: Builder Pattern with Generic Constraints

Goal: Implement a builder pattern for creating containers with custom configuration using generics.

Concepts:

• Builder pattern with type-state
• Generic constraints with Default, Clone traits
• Method chaining
• Consuming builders
• Zero-sized types (ZSTs) for state

Implementation Steps:

1. Define ContainerBuilder<T, const N: usize, State> struct:

   • Use phantom type State for type-state pattern
   • States: Empty, Configured, Ready
   • Each state is a zero-sized type (ZST)

2. Implement builder methods with state transitions:

   • new() -> ContainerBuilder<T, N, Empty>
   • with_default(value: T) -> ContainerBuilder<T, N, Configured> (requires T: Clone)
   • fill() -> ContainerBuilder<T, N, Ready> (requires T: Default)
   • build() -> Stack<T, N> (only on Ready state)

3. Add compile-time state guarantees:

   • Cannot call build() on Empty state (compile error)
   • Cannot call with_default() twice
   • Type system enforces valid construction sequences

4. Demonstrate zero-cost abstraction:

   • All builder types are ZSTs (size 0 at runtime)
   • State transitions happen at compile time only
   • Final build() produces actual container with no runtime overhead

Starter Code:

#![allow(unused)]
fn main() {
use std::marker::PhantomData;

// State marker types (ZSTs)
pub struct Empty;
pub struct Configured;
pub struct Ready;

pub struct ContainerBuilder<T, const N: usize, State> {
    config: Option<T>,
    _state: PhantomData<State>,
}

impl<T, const N: usize> ContainerBuilder<T, N, Empty> {
    pub fn new() -> Self {
        Self {
            config: None,
            _state: PhantomData,
        }
    }

    // Transition to Configured state
    pub fn with_default(self, value: T) -> ContainerBuilder<T, N, Configured>
    where
        T: Clone,
    {
        // TODO: Create Configured builder with value
        ContainerBuilder {
            config: Some(value),
            _state: PhantomData,
        }
    }

    // Transition to Ready state (for types with Default)
    pub fn with_defaults(self) -> ContainerBuilder<T, N, Ready>
    where
        T: Default,
    {
        // TODO: Create Ready builder
        ContainerBuilder {
            config: None,
            _state: PhantomData,
        }
    }
}

impl<T, const N: usize> ContainerBuilder<T, N, Configured> {
    // Transition to Ready state
    pub fn ready(self) -> ContainerBuilder<T, N, Ready> {
        ContainerBuilder {
            config: self.config,
            _state: PhantomData,
        }
    }
}

impl<T, const N: usize> ContainerBuilder<T, N, Ready> {
    // Only Ready state can build
    pub fn build(self) -> Stack<T, N>
    where
        T: Clone,
    {
        let mut stack = Stack::new();

        // TODO: If config has a default value, fill the stack
        if let Some(default) = self.config {
            for _ in 0..N {
                // Don't fail if full, just stop
                if stack.push(default.clone()).is_err() {
                    break;
                }
            }
        }

        stack
    }

    // Build with custom initializer
    pub fn build_with<F>(self, mut init: F) -> Stack<T, N>
    where
        F: FnMut(usize) -> T,
    {
        let mut stack = Stack::new();

        // TODO: Initialize each element with init function
        for i in 0..N {
            let value = init(i);
            if stack.push(value).is_err() {
                break;
            }
        }

        stack
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_builder_with_default() {
        let stack: Stack<i32, 5> = ContainerBuilder::new()
            .with_default(42)
            .ready()
            .build();

        assert_eq!(stack.len(), 5);
        assert_eq!(stack.peek(), Some(&42));
    }

    #[test]
    fn test_builder_with_defaults() {
        let stack: Stack<i32, 3> = ContainerBuilder::new()
            .with_defaults()
            .build();

        // Should be empty (Default for i32 is 0, but we don't auto-fill)
        assert_eq!(stack.len(), 0);
    }

    #[test]
    fn test_builder_with_initializer() {
        let stack: Stack<i32, 5> = ContainerBuilder::new()
            .with_defaults()
            .build_with(|i| (i * 2) as i32);

        assert_eq!(stack.len(), 5);
        assert_eq!(stack.pop(), Some(8)); // i=4 -> 4*2=8
        assert_eq!(stack.pop(), Some(6)); // i=3 -> 3*2=6
    }

    // This should NOT compile (uncomment to verify):
    // #[test]
    // fn test_builder_invalid_state() {
    //     let stack = ContainerBuilder::<i32, 5, Empty>::new()
    //         .build(); // ERROR: build() not available on Empty state
    // }

    #[test]
    fn test_builder_zero_size() {
        use std::mem::size_of;

        // All builder states should be zero-sized
        assert_eq!(size_of::<ContainerBuilder<i32, 100, Empty>>(), size_of::<Option<i32>>());
        assert_eq!(size_of::<ContainerBuilder<i32, 100, Configured>>(), size_of::<Option<i32>>());
        assert_eq!(size_of::<ContainerBuilder<i32, 100, Ready>>(), size_of::<Option<i32>>());

        // State markers are ZSTs
        assert_eq!(size_of::<Empty>(), 0);
        assert_eq!(size_of::<Configured>(), 0);
        assert_eq!(size_of::<Ready>(), 0);
    }

    #[test]
    fn test_builder_method_chaining() {
        let stack = ContainerBuilder::new()
            .with_default(String::from("test"))
            .ready()
            .build();

        assert_eq!(stack.len(), 5);
    }
}
}

Check Your Understanding:

1. How do zero-sized types (ZSTs) enable compile-time state checking with no runtime cost?
2. Why does the builder pattern prevent calling build() on the wrong state?
3. What are the trade-offs between builder pattern and direct construction?

Summary

You’ve built a complete generic data structure library with:

1. Generic Fixed-Size Stack with MaybeUninit<T> and const generics
2. Generic Ring Buffer with circular indexing and FIFO behavior
3. Generic Binary Heap with heap property and T: Ord constraint
4. Generic Container Trait with associated types for abstraction
5. Builder Pattern with type-state and zero-sized types (ZSTs)

Key Patterns Learned:

• Const generics for compile-time size guarantees
• MaybeUninit for uninitialized memory safety
• Trait bounds (Ord, Clone, Default) for generic constraints
• Monomorphization and zero-cost abstractions
• Associated types vs generic type parameters
• Type-state pattern with phantom types
• Drop implementation for RAII and destructors

Performance Characteristics:

• Stack allocation: 0ns allocation cost vs 50-100ns heap
• Monomorphization: Specialized machine code per type (no vtable overhead)
• Cache locality: Contiguous memory layout improves performance
• Const generics: Compiler knows sizes, enables better optimization
• Zero-cost abstractions: Generic code compiles to same ASM as hand-written

Real-World Applications:

• Embedded systems (fixed-size, no heap)
• Real-time systems (predictable performance)
• High-frequency trading (low latency)
• Game engines (cache-friendly data structures)
• Database indexes (B-trees, heaps)

Complete Working Example

#![allow(unused)]
fn main() {
//! Complete working code for chapter 04 – Generic Data Structures
//!
//! This file contains a fixed‑capacity generic `Stack<T, N>` implemented
//! with a raw storage buffer using `MaybeUninit<T>`, along with:
//! - Safe push/pop/peek APIs
//! - Capacity/len helpers
//! - Proper `Drop` to release only initialized elements
//! - `Debug` implementation
//! - An iterator over `&Stack` (`IntoIterator` for `&Stack`)
//! - A consuming iterator for `Stack` (`IntoIterator` for `Stack`)
//!
//! The code is self‑contained and can be copied into a standalone Rust file.

use core::fmt;
use core::mem::MaybeUninit;

pub struct Stack<T, const N: usize> {
    storage: [MaybeUninit<T>; N],
    len: usize,
}

impl<T, const N: usize> Stack<T, N> {
    /// Create an empty stack with capacity `N`.
    pub fn new() -> Self {
        // Fallback compatible with toolchains that don't have `MaybeUninit::uninit_array()`
        // Create an uninitialized array of `MaybeUninit<T>` safely.
        let storage: [MaybeUninit<T>; N] = unsafe {
            // `uninit::<[MaybeUninit<T>; N]>()` is fine and `assume_init` is safe here
            // because `MaybeUninit<_>` does not require initialization.
            core::mem::MaybeUninit::<[MaybeUninit<T>; N]>::uninit().assume_init()
        };
        Self { storage, len: 0 }
    }

    /// Try to push a value. Returns `Err(value)` if the stack is full.
    pub fn push(&mut self, value: T) -> Result<(), T> {
        if self.len >= N { return Err(value); }
        self.storage[self.len].write(value);
        self.len += 1;
        Ok(())
    }

    /// Pop a value from the top of the stack.
    pub fn pop(&mut self) -> Option<T> {
        if self.len == 0 { return None; }
        self.len -= 1;
        Some(unsafe { self.storage[self.len].assume_init_read() })
    }

    /// Peek at the top value without removing it.
    pub fn peek(&self) -> Option<&T> {
        if self.len == 0 { return None; }
        Some(unsafe { self.storage[self.len - 1].assume_init_ref() })
    }

    /// Peek at the top value mutably without removing it.
    pub fn peek_mut(&mut self) -> Option<&mut T> {
        if self.len == 0 { return None; }
        Some(unsafe { self.storage[self.len - 1].assume_init_mut() })
    }

    /// Current number of elements.
    pub fn len(&self) -> usize { self.len }

    /// Capacity of the stack (const generic `N`).
    pub fn capacity(&self) -> usize { N }

    pub fn is_empty(&self) -> bool { self.len == 0 }
    pub fn is_full(&self) -> bool { self.len == N }
}

impl<T, const N: usize> Drop for Stack<T, N> {
    fn drop(&mut self) {
        // Drop only the initialized elements in their insertion order.
        for i in 0..self.len {
            unsafe { self.storage[i].assume_init_drop(); }
        }
    }
}

impl<T: fmt::Debug, const N: usize> fmt::Debug for Stack<T, N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let iter = (0..self.len).map(|i| unsafe { self.storage[i].assume_init_ref() });
        f.debug_list().entries(iter).finish()
    }
}

/// Iterator over `&Stack` that yields `&T` from bottom to top (in insertion order).
pub struct StackIter<'a, T, const N: usize> {
    stack: &'a Stack<T, N>,
    idx: usize,
}

impl<'a, T, const N: usize> Iterator for StackIter<'a, T, N> {
    type Item = &'a T;
    fn next(&mut self) -> Option<Self::Item> {
        if self.idx < self.stack.len {
            let item = unsafe { self.stack.storage[self.idx].assume_init_ref() };
            self.idx += 1;
            Some(item)
        } else {
            None
        }
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.stack.len - self.idx;
        (remaining, Some(remaining))
    }
}

impl<'a, T, const N: usize> ExactSizeIterator for StackIter<'a, T, N> {}

impl<'a, T, const N: usize> IntoIterator for &'a Stack<T, N> {
    type Item = &'a T;
    type IntoIter = StackIter<'a, T, N>;
    fn into_iter(self) -> Self::IntoIter {
        StackIter { stack: self, idx: 0 }
    }
}

/// Consuming iterator that yields `T` in LIFO order.
pub struct StackIntoIter<T, const N: usize> {
    stack: Stack<T, N>,
}

impl<T, const N: usize> Iterator for StackIntoIter<T, N> {
    type Item = T;
    fn next(&mut self) -> Option<Self::Item> { self.stack.pop() }
    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.stack.len, Some(self.stack.len))
    }
}

impl<T, const N: usize> ExactSizeIterator for StackIntoIter<T, N> {}

impl<T, const N: usize> IntoIterator for Stack<T, N> {
    type Item = T;
    type IntoIter = StackIntoIter<T, N>;
    fn into_iter(self) -> Self::IntoIter { StackIntoIter { stack: self } }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn basic_push_pop_peek() {
        let mut s: Stack<i32, 4> = Stack::new();
        assert!(s.is_empty());
        assert_eq!(s.capacity(), 4);

        assert!(s.push(10).is_ok());
        assert!(s.push(20).is_ok());
        assert_eq!(s.len(), 2);
        assert_eq!(s.peek(), Some(&20));

        assert_eq!(s.pop(), Some(20));
        assert_eq!(s.pop(), Some(10));
        assert_eq!(s.pop(), None);
        assert!(s.is_empty());
    }

    #[test]
    fn full_stack() {
        let mut s: Stack<&str, 2> = Stack::new();
        assert!(s.push("a").is_ok());
        assert!(s.push("b").is_ok());
        assert!(s.is_full());
        let err = s.push("c").unwrap_err();
        assert_eq!(err, "c");
    }

    #[test]
    fn iter_by_ref() {
        let mut s: Stack<char, 4> = Stack::new();
        for ch in ['a', 'b', 'c'] { s.push(ch).unwrap(); }
        let collected: Vec<char> = (&s).into_iter().copied().collect();
        assert_eq!(collected, vec!['a', 'b', 'c']);
    }

    #[test]
    fn into_iter_consuming_lifo() {
        let mut s: Stack<i32, 3> = Stack::new();
        s.push(1).unwrap();
        s.push(2).unwrap();
        s.push(3).unwrap();
        let v: Vec<i32> = s.into_iter().collect();
        // LIFO order: 3, 2, 1
        assert_eq!(v, vec![3, 2, 1]);
    }
}
}

Complete Working Example

// Complete Generic Data Structures with Const Generics
// Implements all 5 milestones from the project specification

use std::fmt::{self, Display};
use std::marker::PhantomData;
use std::mem::MaybeUninit;

// ============================================================================
// Milestone 1: Generic Fixed-Size Stack with Const Generics
// ============================================================================

pub struct Stack<T, const N: usize> {
    storage: [MaybeUninit<T>; N],
    len: usize,
}

impl<T, const N: usize> Stack<T, N> {
    pub fn new() -> Self {
        Self {
            storage: unsafe {
                // MaybeUninit doesn't require initialization
                MaybeUninit::<[MaybeUninit<T>; N]>::uninit().assume_init()
            },
            len: 0,
        }
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        if self.len >= N {
            return Err(value);
        }
        self.storage[self.len].write(value);
        self.len += 1;
        Ok(())
    }

    pub fn pop(&mut self) -> Option<T> {
        if self.len == 0 {
            return None;
        }
        self.len -= 1;
        Some(unsafe { self.storage[self.len].assume_init_read() })
    }

    pub fn peek(&self) -> Option<&T> {
        if self.len == 0 {
            return None;
        }
        Some(unsafe { self.storage[self.len - 1].assume_init_ref() })
    }

    pub fn peek_mut(&mut self) -> Option<&mut T> {
        if self.len == 0 {
            return None;
        }
        Some(unsafe { self.storage[self.len - 1].assume_init_mut() })
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn is_full(&self) -> bool {
        self.len == N
    }

    pub fn capacity(&self) -> usize {
        N
    }
}

impl<T, const N: usize> Drop for Stack<T, N> {
    fn drop(&mut self) {
        for i in 0..self.len {
            unsafe {
                self.storage[i].assume_init_drop();
            }
        }
    }
}

impl<T: fmt::Debug, const N: usize> fmt::Debug for Stack<T, N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list()
            .entries((0..self.len).map(|i| unsafe { self.storage[i].assume_init_ref() }))
            .finish()
    }
}

// ============================================================================
// Milestone 2: Generic Ring Buffer with Circular Queuing
// ============================================================================

pub struct RingBuffer<T, const N: usize> {
    storage: [MaybeUninit<T>; N],
    head: usize,
    tail: usize,
    len: usize,
}

impl<T, const N: usize> RingBuffer<T, N> {
    pub fn new() -> Self {
        Self {
            storage: unsafe { MaybeUninit::<[MaybeUninit<T>; N]>::uninit().assume_init() },
            head: 0,
            tail: 0,
            len: 0,
        }
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        if self.len == N {
            // Overwrite oldest element (circular behavior)
            unsafe {
                self.storage[self.tail].assume_init_drop();
            }
            self.storage[self.tail].write(value);
            self.tail = (self.tail + 1) % N;
            self.head = (self.head + 1) % N;
            Ok(())
        } else {
            self.storage[self.tail].write(value);
            self.tail = (self.tail + 1) % N;
            self.len += 1;
            Ok(())
        }
    }

    pub fn pop(&mut self) -> Option<T> {
        if self.len == 0 {
            return None;
        }
        let value = unsafe { self.storage[self.head].assume_init_read() };
        self.head = (self.head + 1) % N;
        self.len -= 1;
        Some(value)
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn is_full(&self) -> bool {
        self.len == N
    }

    pub fn capacity(&self) -> usize {
        N
    }
}

impl<T, const N: usize> Drop for RingBuffer<T, N> {
    fn drop(&mut self) {
        while self.pop().is_some() {}
    }
}

// Iterator support
pub struct RingBufferIter<T, const N: usize> {
    buffer: RingBuffer<T, N>,
}

impl<T, const N: usize> Iterator for RingBufferIter<T, N> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        self.buffer.pop()
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let len = self.buffer.len();
        (len, Some(len))
    }
}

impl<T, const N: usize> IntoIterator for RingBuffer<T, N> {
    type Item = T;
    type IntoIter = RingBufferIter<T, N>;

    fn into_iter(self) -> Self::IntoIter {
        RingBufferIter { buffer: self }
    }
}

// ============================================================================
// Milestone 3: Generic Binary Heap with Ordering
// ============================================================================

pub struct BinaryHeap<T: Ord, const N: usize> {
    storage: [MaybeUninit<T>; N],
    len: usize,
}

impl<T: Ord, const N: usize> BinaryHeap<T, N> {
    pub fn new() -> Self {
        Self {
            storage: unsafe { MaybeUninit::<[MaybeUninit<T>; N]>::uninit().assume_init() },
            len: 0,
        }
    }

    pub fn push(&mut self, value: T) -> Result<(), T> {
        if self.len >= N {
            return Err(value);
        }

        self.storage[self.len].write(value);
        self.heapify_up(self.len);
        self.len += 1;
        Ok(())
    }

    fn heapify_up(&mut self, mut index: usize) {
        while index > 0 {
            let parent = (index - 1) / 2;

            let child_ref = unsafe { self.storage[index].assume_init_ref() };
            let parent_ref = unsafe { self.storage[parent].assume_init_ref() };

            // Max-heap: child > parent
            if child_ref > parent_ref {
                self.storage.swap(index, parent);
                index = parent;
            } else {
                break;
            }
        }
    }

    pub fn pop(&mut self) -> Option<T> {
        if self.len == 0 {
            return None;
        }

        self.len -= 1;
        self.storage.swap(0, self.len);
        let value = unsafe { self.storage[self.len].assume_init_read() };

        if self.len > 0 {
            self.heapify_down(0);
        }

        Some(value)
    }

    fn heapify_down(&mut self, mut index: usize) {
        loop {
            let left = 2 * index + 1;
            let right = 2 * index + 2;
            let mut largest = index;

            if left < self.len {
                let left_ref = unsafe { self.storage[left].assume_init_ref() };
                let largest_ref = unsafe { self.storage[largest].assume_init_ref() };
                if left_ref > largest_ref {
                    largest = left;
                }
            }

            if right < self.len {
                let right_ref = unsafe { self.storage[right].assume_init_ref() };
                let largest_ref = unsafe { self.storage[largest].assume_init_ref() };
                if right_ref > largest_ref {
                    largest = right;
                }
            }

            if largest != index {
                self.storage.swap(index, largest);
                index = largest;
            } else {
                break;
            }
        }
    }

    pub fn peek(&self) -> Option<&T> {
        if self.len > 0 {
            Some(unsafe { self.storage[0].assume_init_ref() })
        } else {
            None
        }
    }

    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn is_full(&self) -> bool {
        self.len == N
    }
}

impl<T: Ord, const N: usize> Drop for BinaryHeap<T, N> {
    fn drop(&mut self) {
        for i in 0..self.len {
            unsafe {
                self.storage[i].assume_init_drop();
            }
        }
    }
}

// ============================================================================
// Milestone 4: Generic Container Trait with Associated Types
// ============================================================================

pub trait Container<T> {
    type Iter<'a>: Iterator<Item = &'a T>
    where
        T: 'a,
        Self: 'a;

    fn len(&self) -> usize;
    fn is_empty(&self) -> bool {
        self.len() == 0
    }
    fn iter(&self) -> Self::Iter<'_>;
    fn clear(&mut self);
}

// Implement for Stack
impl<T, const N: usize> Container<T> for Stack<T, N> {
    type Iter<'a> = StackIter<'a, T, N>
    where
        T: 'a;

    fn len(&self) -> usize {
        self.len
    }

    fn iter(&self) -> Self::Iter<'_> {
        StackIter {
            stack: self,
            index: 0,
        }
    }

    fn clear(&mut self) {
        while self.pop().is_some() {}
    }
}

pub struct StackIter<'a, T, const N: usize> {
    stack: &'a Stack<T, N>,
    index: usize,
}

impl<'a, T, const N: usize> Iterator for StackIter<'a, T, N> {
    type Item = &'a T;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index < self.stack.len {
            let item = unsafe { self.stack.storage[self.index].assume_init_ref() };
            self.index += 1;
            Some(item)
        } else {
            None
        }
    }
}

// Generic function using Container trait
pub fn print_all<T, C>(container: &C)
where
    T: Display,
    C: Container<T>,
{
    for item in container.iter() {
        println!("{}", item);
    }
}

// Generic function to count elements matching predicate
pub fn count_matching<T, C, F>(container: &C, predicate: F) -> usize
where
    C: Container<T>,
    F: Fn(&T) -> bool,
{
    container.iter().filter(|item| predicate(item)).count()
}

// ============================================================================
// Milestone 5: Builder Pattern with Generic Constraints
// ============================================================================

// State marker types (ZSTs)
pub struct Empty;
pub struct Configured;
pub struct Ready;

pub struct ContainerBuilder<T, const N: usize, State> {
    config: Option<T>,
    _state: PhantomData<State>,
}

impl<T, const N: usize> ContainerBuilder<T, N, Empty> {
    pub fn new() -> Self {
        Self {
            config: None,
            _state: PhantomData,
        }
    }

    pub fn with_default(self, value: T) -> ContainerBuilder<T, N, Configured>
    where
        T: Clone,
    {
        ContainerBuilder {
            config: Some(value),
            _state: PhantomData,
        }
    }

    pub fn with_defaults(self) -> ContainerBuilder<T, N, Ready>
    where
        T: Default,
    {
        ContainerBuilder {
            config: None,
            _state: PhantomData,
        }
    }
}

impl<T, const N: usize> ContainerBuilder<T, N, Configured> {
    pub fn ready(self) -> ContainerBuilder<T, N, Ready> {
        ContainerBuilder {
            config: self.config,
            _state: PhantomData,
        }
    }
}

impl<T, const N: usize> ContainerBuilder<T, N, Ready> {
    pub fn build(self) -> Stack<T, N>
    where
        T: Clone,
    {
        let mut stack = Stack::new();

        if let Some(default) = self.config {
            for _ in 0..N {
                if stack.push(default.clone()).is_err() {
                    break;
                }
            }
        }

        stack
    }

    pub fn build_with<F>(self, mut init: F) -> Stack<T, N>
    where
        F: FnMut(usize) -> T,
    {
        let mut stack = Stack::new();

        for i in 0..N {
            let value = init(i);
            if stack.push(value).is_err() {
                break;
            }
        }

        stack
    }
}

// ============================================================================
// Main Function - Demonstrates All Milestones
// ============================================================================

fn main() {
    println!("=== Generic Data Structures with Const Generics ===\n");

    // Milestone 1: Stack
    println!("--- Milestone 1: Generic Fixed-Size Stack ---");
    let mut stack: Stack<i32, 5> = Stack::new();
    stack.push(1).unwrap();
    stack.push(2).unwrap();
    stack.push(3).unwrap();
    println!("Stack: {:?}", stack);
    println!("Peek: {:?}", stack.peek());
    println!("Pop: {:?}", stack.pop());
    println!("After pop: {:?}", stack);

    // Different types
    let mut str_stack: Stack<String, 3> = Stack::new();
    str_stack.push("hello".to_string()).unwrap();
    str_stack.push("world".to_string()).unwrap();
    println!("String stack: {:?}", str_stack);

    // Milestone 2: Ring Buffer
    println!("\n--- Milestone 2: Generic Ring Buffer ---");
    let mut ring: RingBuffer<i32, 4> = RingBuffer::new();
    ring.push(1).unwrap();
    ring.push(2).unwrap();
    ring.push(3).unwrap();
    println!("Ring buffer length: {}", ring.len());
    println!("Pop: {:?}", ring.pop());
    ring.push(4).unwrap();
    ring.push(5).unwrap();
    println!("After wraparound:");
    for val in ring.into_iter() {
        println!("  {}", val);
    }

    // Milestone 3: Binary Heap
    println!("\n--- Milestone 3: Generic Binary Heap ---");
    let mut heap: BinaryHeap<i32, 10> = BinaryHeap::new();
    heap.push(5).unwrap();
    heap.push(3).unwrap();
    heap.push(7).unwrap();
    heap.push(1).unwrap();
    heap.push(9).unwrap();
    println!("Heap peek (max): {:?}", heap.peek());
    println!("Popping in descending order:");
    while let Some(val) = heap.pop() {
        println!("  {}", val);
    }

    // Milestone 4: Container Trait
    println!("\n--- Milestone 4: Generic Container Trait ---");
    let mut stack2: Stack<i32, 10> = Stack::new();
    for i in 1..=5 {
        stack2.push(i).unwrap();
    }
    println!("Stack via Container trait:");
    println!("  Length: {}", stack2.len());
    println!("  Is empty: {}", stack2.is_empty());
    println!("  Elements:");
    for val in stack2.iter() {
        println!("    {}", val);
    }

    let even_count = count_matching(&stack2, |&x| x % 2 == 0);
    println!("  Even numbers count: {}", even_count);

    // Milestone 5: Builder Pattern
    println!("\n--- Milestone 5: Builder Pattern ---");
    let built_stack: Stack<i32, 5> = ContainerBuilder::new()
        .with_default(42)
        .ready()
        .build();
    println!("Built stack with default (42): {:?}", built_stack);

    let custom_stack: Stack<i32, 5> = ContainerBuilder::new()
        .with_defaults()
        .build_with(|i| (i * 2) as i32);
    println!("Built stack with custom init: {:?}", custom_stack);

    println!("\n=== All Milestones Complete! ===");
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // Milestone 1 Tests
    #[test]
    fn test_new_stack_is_empty() {
        let stack: Stack<i32, 10> = Stack::new();
        assert_eq!(stack.len(), 0);
        assert!(stack.is_empty());
        assert_eq!(stack.capacity(), 10);
    }

    #[test]
    fn test_push_and_pop() {
        let mut stack: Stack<i32, 5> = Stack::new();

        assert_eq!(stack.push(1), Ok(()));
        assert_eq!(stack.push(2), Ok(()));
        assert_eq!(stack.push(3), Ok(()));
        assert_eq!(stack.len(), 3);

        assert_eq!(stack.pop(), Some(3));
        assert_eq!(stack.pop(), Some(2));
        assert_eq!(stack.pop(), Some(1));
        assert_eq!(stack.pop(), None);
    }

    #[test]
    fn test_push_when_full() {
        let mut stack: Stack<i32, 3> = Stack::new();

        assert_eq!(stack.push(1), Ok(()));
        assert_eq!(stack.push(2), Ok(()));
        assert_eq!(stack.push(3), Ok(()));
        assert!(stack.is_full());

        assert_eq!(stack.push(4), Err(4));
    }

    #[test]
    fn test_peek() {
        let mut stack: Stack<String, 5> = Stack::new();

        assert_eq!(stack.peek(), None);

        stack.push("hello".to_string()).unwrap();
        stack.push("world".to_string()).unwrap();

        assert_eq!(stack.peek(), Some(&"world".to_string()));
        assert_eq!(stack.len(), 2);
    }

    #[test]
    fn test_drop_calls_destructor() {
        use std::sync::Arc;

        let value = Arc::new(42);
        assert_eq!(Arc::strong_count(&value), 1);

        {
            let mut stack: Stack<Arc<i32>, 5> = Stack::new();
            stack.push(Arc::clone(&value)).unwrap();
            stack.push(Arc::clone(&value)).unwrap();
            assert_eq!(Arc::strong_count(&value), 3);
        }

        assert_eq!(Arc::strong_count(&value), 1);
    }

    #[test]
    fn test_different_types() {
        let mut stack_i32: Stack<i32, 10> = Stack::new();
        stack_i32.push(42).unwrap();
        assert_eq!(stack_i32.pop(), Some(42));

        let mut stack_str: Stack<String, 10> = Stack::new();
        stack_str.push("test".to_string()).unwrap();
        assert_eq!(stack_str.pop(), Some("test".to_string()));

        #[derive(Debug, PartialEq)]
        struct Point {
            x: i32,
            y: i32,
        }

        let mut stack_point: Stack<Point, 10> = Stack::new();
        stack_point.push(Point { x: 1, y: 2 }).unwrap();
        assert_eq!(stack_point.pop(), Some(Point { x: 1, y: 2 }));
    }

    // Milestone 2 Tests
    #[test]
    fn test_ring_buffer_push_pop() {
        let mut buf: RingBuffer<i32, 4> = RingBuffer::new();

        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        assert_eq!(buf.pop(), Some(1));
        assert_eq!(buf.pop(), Some(2));

        buf.push(4).unwrap();
        buf.push(5).unwrap();

        assert_eq!(buf.pop(), Some(3));
        assert_eq!(buf.pop(), Some(4));
        assert_eq!(buf.pop(), Some(5));
        assert_eq!(buf.pop(), None);
    }

    #[test]
    fn test_ring_buffer_wraparound() {
        let mut buf: RingBuffer<i32, 3> = RingBuffer::new();

        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        buf.push(4).unwrap();
        buf.push(5).unwrap();

        assert_eq!(buf.pop(), Some(3));
        assert_eq!(buf.pop(), Some(4));
        assert_eq!(buf.pop(), Some(5));
        assert_eq!(buf.pop(), None);
    }

    #[test]
    fn test_ring_buffer_iterator() {
        let mut buf: RingBuffer<i32, 5> = RingBuffer::new();

        buf.push(10).unwrap();
        buf.push(20).unwrap();
        buf.push(30).unwrap();

        let collected: Vec<i32> = buf.into_iter().collect();
        assert_eq!(collected, vec![10, 20, 30]);
    }

    #[test]
    fn test_ring_buffer_fifo_order() {
        let mut buf: RingBuffer<char, 4> = RingBuffer::new();

        buf.push('a').unwrap();
        buf.push('b').unwrap();
        buf.push('c').unwrap();

        assert_eq!(buf.pop(), Some('a'));

        buf.push('d').unwrap();
        buf.push('e').unwrap();

        assert_eq!(buf.pop(), Some('b'));
        assert_eq!(buf.pop(), Some('c'));
        assert_eq!(buf.pop(), Some('d'));
    }

    #[test]
    fn test_ring_buffer_size_hint() {
        let mut buf: RingBuffer<i32, 5> = RingBuffer::new();

        buf.push(1).unwrap();
        buf.push(2).unwrap();
        buf.push(3).unwrap();

        let iter = buf.into_iter();
        assert_eq!(iter.size_hint(), (3, Some(3)));
    }

    // Milestone 3 Tests
    #[test]
    fn test_heap_push_pop_order() {
        let mut heap: BinaryHeap<i32, 10> = BinaryHeap::new();

        heap.push(5).unwrap();
        heap.push(3).unwrap();
        heap.push(7).unwrap();
        heap.push(1).unwrap();
        heap.push(9).unwrap();

        assert_eq!(heap.pop(), Some(9));
        assert_eq!(heap.pop(), Some(7));
        assert_eq!(heap.pop(), Some(5));
        assert_eq!(heap.pop(), Some(3));
        assert_eq!(heap.pop(), Some(1));
        assert_eq!(heap.pop(), None);
    }

    #[test]
    fn test_heap_peek() {
        let mut heap: BinaryHeap<i32, 5> = BinaryHeap::new();

        assert_eq!(heap.peek(), None);

        heap.push(10).unwrap();
        heap.push(20).unwrap();
        heap.push(5).unwrap();

        assert_eq!(heap.peek(), Some(&20));
        assert_eq!(heap.len(), 3);
    }

    #[test]
    fn test_heap_with_strings() {
        let mut heap: BinaryHeap<String, 5> = BinaryHeap::new();

        heap.push("apple".to_string()).unwrap();
        heap.push("zebra".to_string()).unwrap();
        heap.push("banana".to_string()).unwrap();

        assert_eq!(heap.pop(), Some("zebra".to_string()));
        assert_eq!(heap.pop(), Some("banana".to_string()));
        assert_eq!(heap.pop(), Some("apple".to_string()));
    }

    #[test]
    fn test_heap_capacity() {
        let mut heap: BinaryHeap<i32, 3> = BinaryHeap::new();

        assert_eq!(heap.push(1), Ok(()));
        assert_eq!(heap.push(2), Ok(()));
        assert_eq!(heap.push(3), Ok(()));

        assert_eq!(heap.push(4), Err(4));
    }

    #[test]
    fn test_heap_property_maintained() {
        let mut heap: BinaryHeap<i32, 10> = BinaryHeap::new();

        for i in 0..10 {
            heap.push(i).unwrap();
        }

        let mut prev = heap.pop().unwrap();
        while let Some(current) = heap.pop() {
            assert!(prev >= current, "Heap property violated");
            prev = current;
        }
    }

    // Milestone 4 Tests
    #[test]
    fn test_stack_container_trait() {
        let mut stack: Stack<i32, 10> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();

        assert_eq!(stack.len(), 3);
        assert!(!stack.is_empty());

        let collected: Vec<&i32> = stack.iter().collect();
        assert_eq!(collected, vec![&1, &2, &3]);
    }

    #[test]
    fn test_container_clear() {
        let mut stack: Stack<i32, 5> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();

        stack.clear();
        assert_eq!(stack.len(), 0);
        assert!(stack.is_empty());
    }

    #[test]
    fn test_count_matching() {
        let mut stack: Stack<i32, 10> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();
        stack.push(4).unwrap();
        stack.push(5).unwrap();

        let even_count = count_matching(&stack, |&x| x % 2 == 0);
        assert_eq!(even_count, 2);

        let greater_than_3 = count_matching(&stack, |&x| x > 3);
        assert_eq!(greater_than_3, 2);
    }

    #[test]
    fn test_container_polymorphism() {
        fn sum_all<T, C>(container: &C) -> T
        where
            T: std::ops::Add<Output = T> + Default + Copy,
            C: Container<T>,
        {
            container.iter().copied().fold(T::default(), |acc, x| acc + x)
        }

        let mut stack: Stack<i32, 5> = Stack::new();
        stack.push(1).unwrap();
        stack.push(2).unwrap();
        stack.push(3).unwrap();

        assert_eq!(sum_all(&stack), 6);
    }

    // Milestone 5 Tests
    #[test]
    fn test_builder_with_default() {
        let stack: Stack<i32, 5> = ContainerBuilder::new().with_default(42).ready().build();

        assert_eq!(stack.len(), 5);
        assert_eq!(stack.peek(), Some(&42));
    }

    #[test]
    fn test_builder_with_defaults() {
        let stack: Stack<i32, 3> = ContainerBuilder::new().with_defaults().build();

        assert_eq!(stack.len(), 0);
    }

    #[test]
    fn test_builder_with_initializer() {
        let mut stack: Stack<i32, 5> = ContainerBuilder::new()
            .with_defaults()
            .build_with(|i| (i * 2) as i32);

        assert_eq!(stack.len(), 5);
        assert_eq!(stack.pop(), Some(8));
        assert_eq!(stack.pop(), Some(6));
    }

    #[test]
    fn test_builder_zero_size() {
        use std::mem::size_of;

        assert_eq!(
            size_of::<ContainerBuilder<i32, 100, Empty>>(),
            size_of::<Option<i32>>()
        );
        assert_eq!(
            size_of::<ContainerBuilder<i32, 100, Configured>>(),
            size_of::<Option<i32>>()
        );
        assert_eq!(
            size_of::<ContainerBuilder<i32, 100, Ready>>(),
            size_of::<Option<i32>>()
        );

        assert_eq!(size_of::<Empty>(), 0);
        assert_eq!(size_of::<Configured>(), 0);
        assert_eq!(size_of::<Ready>(), 0);
    }

    #[test]
    fn test_builder_method_chaining() {
        let stack: Stack<String, 5> = ContainerBuilder::new()
            .with_default(String::from("test"))
            .ready()
            .build();

        assert_eq!(stack.len(), 5);
    }
}

Summary

The file src/bin/complete_04_generic.rs now contains:

Milestone 1: Generic Fixed-Size Stack with Const Generics

• Stack<T, const N: usize> using MaybeUninit for uninitialized memory
• Methods: new(), push(), pop(), peek(), len(), is_empty(), is_full()
• Proper Drop implementation to clean up initialized elements
• Debug implementation conditional on T: Debug

Milestone 2: Generic Ring Buffer with Circular Queuing

• RingBuffer<T, const N: usize> with circular FIFO behavior
• Uses head, tail, and len for tracking positions
• Overwrites oldest elements when full (circular behavior)
• Implements IntoIterator for consuming iteration

Milestone 3: Generic Binary Heap with Ordering

• BinaryHeap<T: Ord, const N: usize> implementing max-heap
• Heap algorithms: heapify_up() and heapify_down()
• Trait bound T: Ord required for total ordering
• Methods: push(), pop(), peek()

Milestone 4: Generic Container Trait with Associated Types

• Container trait with Generic Associated Types (GATs)
• Associated type Iter<’a> for iterators
• Implemented for Stack<T, N>
• Generic functions: print_all(), count_matching()

Milestone 5: Builder Pattern with Generic Constraints

• Type-state pattern using zero-sized types (ZSTs)
• States: Empty, Configured, Ready
• Compile-time state checking prevents invalid construction
• Methods: new(), with_default(), with_defaults(), ready(), build(), build_with()

Test Results

✅ All 25 tests passing, covering:

• Stack operations (push, pop, peek, capacity checking)
• Ring buffer with wraparound and FIFO behavior
• Binary heap with max-heap property
• Container trait polymorphism
• Builder pattern with type-state transitions
• Drop implementation and destructor calls
• Different generic types (i32, String, custom structs)

Key Concepts Demonstrated

• Const generics for compile-time size guarantees
• MaybeUninit for safe uninitialized memory
• Trait bounds (Ord, Clone, Default, Display)
• Monomorphization and zero-cost abstractions
• Associated types vs generic type parameters
• Type-state pattern with phantom types
• RAII with proper Drop implementation

The implementation runs successfully, producing correct output for all data structures and passing all tests!

Memory Pool Allocator

Problem Statement

Build a custom memory pool allocator that pre-allocates a large block of memory and manages allocations within it. This allocator should efficiently handle fixed-size allocations, track memory usage, and provide better performance than the system allocator for specific workloads.

Your memory pool should support:

• Pre-allocating a fixed-size pool
• Allocating and deallocating fixed-size blocks
• Tracking used/free blocks
• Preventing fragmentation
• Detecting memory leaks and double-frees

How System Allocators Work

Before we dive into memory pools, it’s essential to understand how general-purpose system allocators work and why they struggle with certain workloads. This knowledge will help you appreciate when and why specialized allocators like memory pools are superior.

System Allocator Overview

A system allocator (like malloc/free, jemalloc, tcmalloc) is a general-purpose memory management system that handles arbitrary-sized allocations. When your program calls malloc(size), the allocator must:

1. Find a suitable block of free memory
2. Mark it as used
3. Return a pointer to the caller
4. Track metadata for eventual deallocation

The Core Challenge: Must handle any size, any pattern, any timing efficiently.

Typical program workload:
malloc(8)     → need tiny block
malloc(1024)  → need medium block
malloc(64)    → need small block
malloc(8192)  → need large block
free(small)   → creates hole
malloc(32)    → reuse hole or find new space?

This unpredictability forces system allocators to use complex strategies that trade performance for flexibility.

Internal Data Structures

System allocators maintain several data structures to track free and allocated memory:

1. Free Lists (Linked Lists of Available Blocks)

Concept: Chain together all free memory blocks using pointers stored within the free blocks themselves.

Heap memory with free list:

Address    Data
0x1000   ┌─────────────────┐
         │ [Used Block]    │  Allocated to user
0x1040   ├─────────────────┤
         │ Size: 128       │  Metadata
         │ Next: 0x20C0 ───┼──┐  Pointer to next free block
         │ [Free Space]    │  │  (stored in the free space!)
0x10C0   ├─────────────────┤  │
         │ [Used Block]    │  │
0x2000   ├─────────────────┤  │
         │ [Used Block]    │  │
0x20C0   ├─────────────────┤◄─┘
         │ Size: 256       │
         │ Next: NULL      │
         │ [Free Space]    │
         └─────────────────┘

Free list: 0x1040 → 0x20C0 → NULL

Key Insight: No extra memory needed for the free list—the list lives in the free blocks themselves!

Search Strategies:

Example: First Fit Search

Request: malloc(64)
Free list: [32] → [128] → [48] → [256]

Scan:
- 32 bytes? Too small, skip
- 128 bytes? Large enough! Use it
  - Return pointer to start of block
  - If 128 - 64 = 64 remaining, split into new free block
  - Update free list

2. Size Classes / Bins (Segregated Free Lists)

Problem with Single Free List: Searching for the right size is slow O(n).

Solution: Maintain multiple free lists, one for each size range.

Bins (size classes):
┌──────────┬─────────────────┐
│ Bin 0    │ 8-16 bytes      │ → [Free 16] → [Free 8] → NULL
├──────────┼─────────────────┤
│ Bin 1    │ 17-32 bytes     │ → [Free 32] → [Free 24] → NULL
├──────────┼─────────────────┤
│ Bin 2    │ 33-64 bytes     │ → [Free 64] → [Free 48] → NULL
├──────────┼─────────────────┤
│ Bin 3    │ 65-128 bytes    │ → NULL (all allocated)
├──────────┼─────────────────┤
│ Bin 4    │ 129-256 bytes   │ → [Free 256] → NULL
├──────────┼─────────────────┤
│ ...      │ ...             │
└──────────┴─────────────────┘

malloc(50):
1. Calculate bin: 50 bytes → Bin 2 (33-64 bytes)
2. Check Bin 2: found [Free 64]
3. Return immediately - O(1)!

Benefits:

• Fast allocation: O(1) lookup for common sizes
• Less fragmentation: Similar-sized objects grouped together
• Better cache locality: Objects from same bin are nearby

Real Allocator Bin Layouts:

3. Block Metadata (Headers and Footers)

Every allocated block carries metadata for management:

Allocated Block Structure:

┌─────────────────────────────┐
│  HEADER                     │
│  ┌────────────────────────┐ │
│  │ Size: 128 bytes        │ │ ← Block size (includes header)
│  │ Flags: [IN_USE]        │ │ ← Status bits
│  │ Prev Size: 64          │ │ ← Previous block size (for coalescing)
│  └────────────────────────┘ │
├─────────────────────────────┤
│  USER DATA                  │ ← Pointer returned to user
│  (120 bytes usable)         │
│                             │
└─────────────────────────────┘
│  FOOTER (optional)          │
│  Size: 128 (duplicate)      │ ← Enables backward traversal
└─────────────────────────────┘

Total overhead: 8-16 bytes per allocation

Metadata Uses:

• Size: Know how much to free
• Status flags: In use, previous block free, etc.
• Boundary tags: Find adjacent blocks for coalescing

Optimization: Size Class Pools

Small allocations (≤ 256 bytes) often use slab allocation with no per-object metadata:

Slab for 64-byte objects:
┌───────┬───────┬───────┬───────┬───────┐
│ Obj 1 │ Obj 2 │ Obj 3 │ Obj 4 │ Obj 5 │
│ 64B   │ 64B   │ 64B   │ 64B   │ 64B   │
└───────┴───────┴───────┴───────┴───────┘

Bitmap: [1][1][0][1][0]  ← 1 = in use, 0 = free
         ↑  ↑     ↑
       Used Used  Used

No per-object headers! Just bitmap overhead.

Savings: 8-16 bytes per allocation for small objects = 10-20% memory savings.

Fragmentation: The Allocator’s Nemesis

Fragmentation is wasted memory that’s technically free but unusable. It’s the primary problem system allocators try to minimize.

Types of Fragmentation

1. External Fragmentation

Free memory exists but is scattered in pieces too small to satisfy requests.

Memory state after many allocations/deallocations:

[Used 32][Free 16][Used 64][Free 8][Used 128][Free 32][Used 16][Free 4]

Request malloc(64):
❌ FAIL: Total free = 16 + 8 + 32 + 4 = 60 bytes
✓ But no single contiguous block ≥ 64 bytes!

Fragmentation ratio: 60 bytes free but unusable = wasted

Real-World Impact:

• Long-running servers: 20-40% of heap can become fragmented
• Embedded systems: May fail allocations despite having enough total memory
• Can trigger expensive OS memory operations (brk, mmap)

2. Internal Fragmentation

Allocated more than needed due to allocator constraints.

Request: malloc(50)
Allocator rounds up to size class: 64 bytes
Return: 64-byte block

Used:     50 bytes
Wasted:   14 bytes (internal fragmentation)
Overhead: 28% waste!

With many small allocations:
10,000 × 50-byte requests
Allocated: 10,000 × 64 = 640 KB
Needed:    10,000 × 50 = 500 KB
Waste:     140 KB (28%)

Low Fragmentation Strategies

Modern allocators use sophisticated techniques to minimize fragmentation. Let’s examine the most important ones.

1. Coalescing (Merging Adjacent Free Blocks)

Problem: After many frees, free list becomes littered with tiny adjacent blocks.

Before coalescing:
[Used][Free 16][Free 32][Used][Free 8][Free 24][Used]
       ↑        ↑              ↑        ↑
   Can't satisfy malloc(64)!

After coalescing:
[Used][Free 48][Used][Free 32][Used]
       ↑              ↑
   Now malloc(64) fails, but malloc(48) or malloc(32) works

Implementation: Boundary Tags

Use metadata to find adjacent blocks:

#![allow(unused)]
fn main() {
fn coalesce_free_block(ptr: *mut u8) {
    let mut block = Block::from_ptr(ptr);

    // Check previous block
    if block.prev_free() {
        let prev = block.prev_block();
        // Remove prev from free list
        // Merge: block = [prev][block]
        block.size += prev.size;
    }

    // Check next block
    let next = block.next_block();
    if next.is_free() {
        // Remove next from free list
        // Merge: block = [block][next]
        block.size += next.size;
    }

    // Add coalesced block to free list
    add_to_free_list(block);
}
}

Cost: O(1) per free operation (just check neighbors)

Benefit: Maintains larger contiguous blocks, reduces external fragmentation by 30-50%

2. Splitting (Breaking Large Blocks)

Problem: Allocating small object from large block wastes space.

Free block: 1024 bytes
Request: malloc(64)

Without splitting:
[Used 64 + wasted 960] ← 960 bytes internal fragmentation!

With splitting:
[Used 64][Free 960]
         └── Return to free list

Implementation:

#![allow(unused)]
fn main() {
fn allocate_with_split(block: FreeBlock, requested_size: usize) -> *mut u8 {
    let total_size = block.size;
    let min_split_size = 32; // Don't split if remainder too small

    if total_size >= requested_size + min_split_size {
        // Split the block
        let remainder_size = total_size - requested_size;

        // First part: allocate
        let allocated = block.ptr;
        set_block_size(allocated, requested_size);
        set_used(allocated);

        // Second part: free
        let remainder = allocated.add(requested_size);
        set_block_size(remainder, remainder_size);
        set_free(remainder);
        add_to_free_list(remainder);

        return allocated;
    } else {
        // Too small to split, use whole block
        set_used(block.ptr);
        return block.ptr;
    }
}
}

Threshold: Only split if remainder ≥ minimum useful size (16-32 bytes)

• Prevents creating useless tiny blocks
• Balances internal vs external fragmentation

3. Size Classes with Power-of-Two Rounding

Strategy: Round allocations to power-of-two or specific size classes.

Benefits:

• Fast bin lookup: bin = log2(size) or bit manipulation
• Predictable splitting: 512-byte block splits perfectly into 2×256, 4×128, etc.
• Better reuse: More likely to find exact size match

Example Size Classes:

Tiny:    8, 16, 24, 32, 40, 48, 56, 64  (8-byte increments)
Small:   64, 80, 96, 112, 128, 160, 192, 224, 256  (16-byte increments)
Medium:  256, 320, 384, 448, 512, 640, 768, 896, 1024  (64-byte increments)
Large:   1K, 2K, 4K, 8K, 16K, 32K, 64K...  (powers of 2)
Huge:    Direct mmap, page-aligned

Internal Fragmentation Trade-off:

Request: 65 bytes
Allocated: 80 bytes (next size class)
Waste: 15 bytes (23%)

But:
✓ Fast O(1) allocation (direct bin lookup)
✓ Reduces external fragmentation (standard sizes)
✓ Better cache utilization (aligned sizes)

Typical waste: 10-15% internal fragmentation
Savings from reduced external fragmentation: 20-40%
Net win: 5-30% less total waste

4. Segregated Free Lists (Per-Size Bins)

Advanced Strategy: Separate free lists for each size class.

Allocation Request: 48 bytes

Step 1: Calculate bin index
bin = size_to_bin(48)  // bin 2 (33-64 bytes)

Step 2: Check exact bin
if bins[2] not empty:
    return bins[2].pop()  // O(1)!

Step 3: Check larger bins
for i in 3..MAX_BINS:
    if bins[i] not empty:
        block = bins[i].pop()
        split_and_return(block, 48)
        return block

Step 4: Request more memory from OS
return expand_heap(48)

Fast Path: O(1) when exact size available (90%+ of allocations in practice)

Benefits:

• Eliminates search time for common sizes
• Objects of similar size grouped together (better cache locality)
• Reduces fragmentation (similar-sized objects live/die together)

5. Arena/Region-Based Allocation

Strategy: Large allocations (>128KB) go directly to OS via mmap() instead of using heap.

malloc(200,000):
  ↓
Check if > threshold (typically 128KB)
  ↓ YES
Call mmap() → get dedicated memory region
  ↓
Return pointer
  ↓
free(): munmap() entire region

Benefits:
✓ No heap fragmentation (separate region)
✓ Can return memory to OS immediately
✓ Page-aligned automatically

jemalloc Arena Structure:

Per-Thread Arena:
┌────────────────────────┐
│ Small bins  (0-1KB)    │ ← Thread-local, no locking
├────────────────────────┤
│ Large bins  (1KB-128KB)│ ← Shared, requires lock
├────────────────────────┤
│ Huge allocations       │ ← Direct mmap
└────────────────────────┘

Multiple arenas reduce lock contention:
Thread 1 → Arena 1
Thread 2 → Arena 2
Thread 3 → Arena 1  (reuse)
Thread 4 → Arena 2  (reuse)

6. Deferred Coalescing

Problem: Coalescing on every free() is expensive (traversing neighbors, updating lists).

Solution: Batch coalesce operations.

Strategy 1: Lazy coalescing
- free(): Just add to free list, don't coalesce
- malloc(): If allocation fails, run coalescing pass, then retry

Strategy 2: Periodic coalescing
- Every N allocations, run full coalescing pass
- Amortized cost: O(1) per operation

Strategy 3: Opportunistic coalescing
- Coalesce only when freeing blocks adjacent to already-free blocks
- Detected via boundary tags

Trade-off:

• Less coalescing = faster free()
• More fragmentation temporarily
• Batch processing reduces overhead

Benchmark Impact:

Immediate coalescing:
  - free(): 50ns per call
  - malloc success rate: 95%

Deferred coalescing:
  - free(): 10ns per call (5x faster!)
  - malloc success rate: 92%
  - Periodic cleanup: 500ns every 1000 ops

Net: 2-3x overall throughput improvement

Real Allocator Implementations

Let’s see how production allocators combine these strategies:

jemalloc (Used by Rust, FreeBSD, Firefox, Meta)

Architecture:

┌───────────────────────────────────────┐
│ Per-Thread Caches (TCaches)          │
│  - Small allocations (<= 14KB)       │
│  - Zero contention                    │
├───────────────────────────────────────┤
│ Arenas (Shared regions)               │
│  - Multiple arenas reduce contention  │
│  - 4 cores × 4 arenas = 16 arenas    │
├───────────────────────────────────────┤
│ Size Classes                          │
│  - Tiny: 8-256 bytes                 │
│  - Small: 512B-14KB                  │
│  - Large: 16KB-4MB                   │
│  - Huge: >4MB (direct mmap)          │
└───────────────────────────────────────┘

Key Features:

• Immediate coalescing for small/medium
• Deferred coalescing for large
• 96 size classes (fine-grained)
• 4MB chunks (slab units)
• Typical fragmentation: 10-15%

tcmalloc (Used by Chrome, Golang)

Architecture:

┌───────────────────────────────────────┐
│ Per-Thread Caches                     │
│  - 60 size classes                    │
│  - Max cache size: 4MB per thread     │
├───────────────────────────────────────┤
│ Central Free List                     │
│  - Spans (groups of pages)            │
│  - Lock-protected                     │
├───────────────────────────────────────┤
│ Page Heap                             │
│  - 4KB pages                          │
│  - Buddy allocation for large         │
└───────────────────────────────────────┘

Key Features:

• No coalescing for small allocations (fixed spans)
• Buddy system for large (efficient coalescing)
• Lock-free for thread cache hits (99%+ of allocations)
• Typical fragmentation: 12-18%

dlmalloc/ptmalloc2 (Used by glibc, Linux default)

Architecture:

┌───────────────────────────────────────┐
│ Fast Bins (LIFO, no coalescing)      │
│  - 10 bins for very small sizes      │
│  - 16, 24, 32...80 bytes              │
├───────────────────────────────────────┤
│ Small Bins (size classes)             │
│  - 62 bins                            │
│  - FIFO order                         │
├───────────────────────────────────────┤
│ Large Bins (sorted by size)           │
│  - 63 bins                            │
│  - Best-fit search                    │
├───────────────────────────────────────┤
│ Unsorted Bin (recent frees)           │
│  - Staging area for coalescing        │
└───────────────────────────────────────┘

Key Features:

• Immediate coalescing except fast bins
• Best-fit for large allocations
• Wilderness preservation (keep large tail block)
• Typical fragmentation: 15-25% (higher than jemalloc/tcmalloc)

Fragmentation Benchmarks

Real-world fragmentation measurements from long-running programs:

Workload characteristics that cause fragmentation:

• Mixed sizes: Allocating 8, 64, 1024, 8, 64, 1024 repeatedly
• Long lifetime variance: Some objects live milliseconds, others live hours
• Phase transitions: Allocate 1000 objects, free 500, allocate 1000 more
• Random free order: Free in different order than allocated

Why Memory Pools Win for Specific Workloads

After understanding system allocators, we can now see exactly why and when memory pools are superior:

When to use system allocator:

• Variable-sized allocations
• Long-lived objects with complex lifetime patterns
• Small number of allocations (<1000/sec)
• General-purpose code

When to use memory pool:

• Fixed-size or narrow size range
• Short-lived objects (create/destroy cycles)
• High allocation rate (>10,000/sec)
• Real-time constraints (audio, games, trading systems)
• Embedded systems with limited memory

Rust Programming Concepts for This Project

Memory Pool Architecture

Core Components:

#![allow(unused)]
fn main() {
struct MemoryPool {
    memory: Vec<u8>,         // The pre-allocated memory block
    block_size: usize,       // Size of each allocatable chunk
    free_list: Vec<usize>,   // Stack of available block indices
}

Memory Layout:
┌───────────────────────────────────────────┐
│              memory: Vec<u8>              │
├──────┬──────┬──────┬──────┬──────┬────────┤
│Block │Block │Block │Block │Block │...     │
│  0   │  1   │  2   │  3   │  4   │        │
│64 B  │64 B  │64 B  │64 B  │64 B  │        │
└──────┴──────┴──────┴──────┴──────┴────────┘

Free List: [4, 3, 1, 0]  (Block 2 is allocated)
             ↑ top
Next allocation returns pointer to Block 4
}

Allocation Algorithm:

#![allow(unused)]
fn main() {
fn allocate(&mut self) -> Option<*mut u8> {
    // Pop an index from free list
    self.free_list.pop().map(|index| {
        // Calculate pointer: base + (index * block_size)
        let offset = index * self.block_size;
        unsafe { self.memory.as_mut_ptr().add(offset) }
    })
}
}

Deallocation Algorithm:

#![allow(unused)]
fn main() {
fn deallocate(&mut self, ptr: *mut u8) {
    // Calculate index: (ptr - base) / block_size
    let offset = ptr as usize - self.memory.as_ptr() as usize;
    let index = offset / self.block_size;

    // Push index back onto free list
    self.free_list.push(index);
}
}

Time Complexity:

• Allocation: O(1) - pop from Vec
• Deallocation: O(1) - push to Vec
• Both are just a few CPU instructions

Raw Pointers and Unsafe Rust

Memory pools require unsafe Rust because we’re manually managing memory. Let’s understand what that means.

Safe Rust (what you normally write):

#![allow(unused)]
fn main() {
let x = Box::new(42);  // Compiler tracks ownership
let y = x;             // Ownership moved to y
// Can't use x anymore - compile error!
// Box automatically frees memory when y goes out of scope
}

Unsafe Rust (what memory pools need):

#![allow(unused)]
fn main() {
let ptr: *mut i32 = pool.allocate() as *mut i32;
// ptr is a "raw pointer" - no ownership tracking
// Compiler doesn't know if it's valid
// We must manually ensure:
// 1. Pointer is not null
// 2. Points to valid memory
// 3. Memory is properly aligned
// 4. No use-after-free
// 5. No double-free
// 6. Proper drop handling
}

Raw Pointer Operations:

#![allow(unused)]
fn main() {
// 1. Dereferencing (reading/writing)
let ptr: *mut i32 = ...;
unsafe {
    *ptr = 42;          // Write through pointer
    let value = *ptr;   // Read through pointer
}

// 2. Pointer arithmetic
let ptr: *mut u8 = base_ptr;
let ptr2 = unsafe { ptr.add(64) };  // Move pointer 64 bytes forward

// 3. Casting
let byte_ptr: *mut u8 = ...;
let int_ptr: *mut i32 = byte_ptr as *mut i32;

// 4. Writing/reading values
unsafe {
    std::ptr::write(ptr, value);     // Write without dropping old value
    let value = std::ptr::read(ptr); // Read without moving
}
}

Why These Are Unsafe:

#![allow(unused)]
fn main() {
// Example 1: Dangling pointer
let ptr: *mut i32 = {
    let x = Box::new(42);
    &mut *x as *mut i32
}; // x dropped, memory freed
unsafe { *ptr }  // ❌ UNDEFINED BEHAVIOR: Reading freed memory

// Example 2: Null pointer dereference
let ptr: *mut i32 = std::ptr::null_mut();
unsafe { *ptr }  // ❌ SEGMENTATION FAULT

// Example 3: Alignment violation
let bytes = vec![0u8; 10];
let ptr = bytes.as_ptr() as *const u64;
unsafe { *ptr }  // ❌ UNDEFINED BEHAVIOR: u64 needs 8-byte alignment

// Example 4: Data race
// Thread 1:
unsafe { *ptr = 42 }
// Thread 2 (simultaneously):
unsafe { *ptr = 100 }  // ❌ DATA RACE
}

Our Responsibility in Unsafe Code:

When we write unsafe, we’re making a contract with the compiler:

#![allow(unused)]
fn main() {
unsafe {
    // I, the programmer, guarantee:
    // ✓ This pointer is non-null
    // ✓ Points to valid, initialized memory
    // ✓ Properly aligned for the type
    // ✓ No data races possible
    // ✓ Satisfies all Rust safety invariants
}
}

If we violate this contract: undefined behavior (crashes, corruption, security vulnerabilities).

RAII: Resource Acquisition Is Initialization

RAII is a pattern where resource lifetime is tied to object lifetime. In Rust, this is implemented via the Drop trait.

The Problem Without RAII:

#![allow(unused)]
fn main() {
let ptr = pool.allocate();
// ... use ptr ...
pool.deallocate(ptr);  // Easy to forget!

// Or:
let ptr = pool.allocate();
if error_condition {
    return Err(...);  // ❌ MEMORY LEAK: forgot to deallocate!
}
pool.deallocate(ptr);
}

RAII Solution:

#![allow(unused)]
fn main() {
struct Block<'a, T> {
    data: *mut T,
    pool: &'a mut TypedPool<T>,
}

impl<T> Drop for Block<'_, T> {
    fn drop(&mut self) {
        // Automatically called when Block goes out of scope
        unsafe {
            std::ptr::drop_in_place(self.data);  // Drop T's contents
        }
        self.pool.deallocate(self.data);  // Return to pool
    }
}

// Usage:
{
    let block = pool.allocate(42).unwrap();  // Block owns the memory
    // ... use block ...
}  // Block dropped here → automatically returns memory to pool!

// Even with early returns:
{
    let block = pool.allocate(42).unwrap();
    if error_condition {
        return Err(...);  // ✓ Block's Drop runs, memory returned
    }
}
}

Benefits:

• No leaks: Memory automatically returned
• Exception safe: Works with panics
• Composable: Blocks can contain Blocks
• Zero overhead: Drop inlined at compile time

RAII in Rust Standard Library:

#![allow(unused)]
fn main() {
// File handle
let file = File::open("data.txt")?;
// ... use file ...
// Drop automatically closes file descriptor

// Mutex guard
let guard = mutex.lock().unwrap();
// ... critical section ...
// Drop automatically releases lock

// Database transaction
let tx = db.transaction()?;
// ... queries ...
tx.commit()?;
// Drop rolls back if commit wasn't called
}

PhantomData: Zero-Sized Type Markers

PhantomData<T> tells the compiler about types we use, even though we don’t store them directly.

The Problem:

#![allow(unused)]
fn main() {
struct TypedPool<T> {
    pool: MemoryPool,
    // We don't actually store any T!
    // But we allocate T and return *mut T
}

// Compiler sees no T field, so:
// - Doesn't enforce T's variance rules
// - Doesn't track T for Send/Sync
// - Optimizes away T entirely
}

Solution with PhantomData:

#![allow(unused)]
fn main() {
struct TypedPool<T> {
    pool: MemoryPool,
    _marker: PhantomData<T>,  // "Pretend" we own a T
}

// Now compiler knows:
// - This type is generic over T
// - If T: !Send, then TypedPool<T>: !Send
// - If T: Drop, we need to handle T's drops
// - Variance rules apply
}

Key Properties:

1. Zero Size:

#![allow(unused)]
fn main() {
assert_eq!(std::mem::size_of::<PhantomData<String>>(), 0);
// Compiles to nothing, no runtime cost!
}

2. Ownership Semantics:

#![allow(unused)]
fn main() {
struct Owner<T> {
    data: *mut T,
    _marker: PhantomData<T>,  // Acts like we own T
}

// If T is not Send, Owner<T> is not Send
// If T has Drop, Owner must handle it
}

3. Different Kinds:

#![allow(unused)]
fn main() {
PhantomData<T>         // Own T (invariant)
PhantomData<&'a T>     // Borrow &'a T (covariant)
PhantomData<&'a mut T> // Mutably borrow &'a mut T (invariant)
PhantomData<fn(T)>     // Contravariant over T
}

Real Example:

#![allow(unused)]
fn main() {
struct TypedPool<T> {
    pool: MemoryPool,
    _marker: PhantomData<T>,
}

// Without PhantomData:
// TypedPool<String> could be Send even if String wasn't
// ❌ UNSOUND: could send non-Send types across threads

// With PhantomData:
// TypedPool<T>: Send only if T: Send
// ✓ SOUND: compiler enforces correct Send/Sync bounds
}

Thread Safety: Arc, Mutex, Send, and Sync

To share memory pools across threads, we need to understand Rust’s concurrency primitives.

Arc: Atomic Reference Counting

Arc<T> is a thread-safe reference-counted pointer. Multiple threads can hold references; memory is freed when the last reference is dropped.

#![allow(unused)]
fn main() {
// Without Arc (won't compile):
let pool = TypedPool::new(100);
thread::spawn(move || {
    pool.allocate(42);  // pool moved here
});
// pool.allocate(100);  // ❌ Error: pool was moved

// With Arc:
let pool = Arc::new(Mutex::new(TypedPool::new(100)));
let pool_clone = Arc::clone(&pool);

thread::spawn(move || {
    pool_clone.lock().unwrap().allocate(42);
});
pool.lock().unwrap().allocate(100);  // ✓ Both threads can access
}

How Arc Works:

Arc created with count = 1:
┌─────────────────┐
│  Reference      │
│  Count: 1       │
│  ┌──────────┐   │
│  │  Data    │   │
│  │ TypedPool│   │
│  └──────────┘   │
└─────────────────┘

After Arc::clone(&arc):
┌─────────────────┐
│  Reference      │
│  Count: 2  ←────┼─── Atomically incremented
│  ┌──────────┐   │
│  │  Data    │   │
│  │ TypedPool│   │
│  └──────────┘   │
└─────────────────┘
     ↑      ↑
   arc1   arc2

When arc1 drops: count decremented to 1
When arc2 drops: count reaches 0 → data freed

Mutex: Mutual Exclusion

Mutex<T> ensures only one thread at a time can access T.

#![allow(unused)]
fn main() {
let mutex = Mutex::new(pool);

// Thread 1:
{
    let guard = mutex.lock().unwrap();  // Blocks if locked
    guard.allocate(42);
    // Lock held
}  // guard dropped → lock released

// Thread 2:
{
    let guard = mutex.lock().unwrap();  // Can now acquire lock
    guard.allocate(100);
}
}

How Mutex Prevents Data Races:

#![allow(unused)]
fn main() {
// Without Mutex (won't compile):
let mut pool = TypedPool::new(100);
let pool_ref = &mut pool;  // Only ONE mutable reference allowed
// Can't create second reference → compile error

// With Mutex:
let mutex = Mutex::new(TypedPool::new(100));

// Thread 1:
let mut guard1 = mutex.lock().unwrap();
// Thread 2:
let mut guard2 = mutex.lock().unwrap();  // BLOCKS until thread 1 releases

// Only ONE guard exists at a time → no data races
}

Send and Sync Traits

These marker traits define thread safety:

#![allow(unused)]
fn main() {
// Send: Type can be transferred to another thread
// Examples: i32, String, Vec<T> where T: Send
unsafe impl Send for MyType {}

// Sync: Type can be referenced from multiple threads
// Equivalent to: &T is Send
// Examples: i32, AtomicUsize, Mutex<T>
unsafe impl Sync for MyType {}
}

Rules:

• T: Send means you can move T to another thread
• T: Sync means you can share &T across threads
• T: Sync ⟺ &T: Send

Examples:

#![allow(unused)]
fn main() {
// i32: Send + Sync
let x = 42;
thread::spawn(move || {
    println!("{}", x);  // ✓ Can send i32
});

// Rc<T>: !Send (not thread-safe reference counting)
let rc = Rc::new(42);
thread::spawn(move || {
    println!("{}", rc);  // ❌ Compile error: Rc is not Send
});

// Arc<T>: Send + Sync (atomic reference counting)
let arc = Arc::new(42);
thread::spawn(move || {
    println!("{}", arc);  // ✓ Can send Arc
});

// Cell<T>: !Sync (interior mutability without synchronization)
let cell = Cell::new(42);
let cell_ref = &cell;
thread::spawn(move || {
    cell_ref.set(100);  // ❌ Compile error: &Cell is not Send
});
}

Our SharedBlock Implementation:

#![allow(unused)]
fn main() {
struct SharedBlock<T> {
    data: *mut T,
    pool: Arc<Mutex<TypedPool<T>>>,
    _marker: PhantomData<T>,
}

// SAFETY: We must manually implement Send/Sync
// because raw pointers are !Send and !Sync by default

unsafe impl<T: Send> Send for SharedBlock<T> {}
// Safe because:
// - *mut T is owned uniquely by this SharedBlock
// - Arc<Mutex<...>> is Send when T: Send
// - We never share *mut T across threads

unsafe impl<T: Send> Sync for SharedBlock<T> {}
// Safe because:
// - All access to *mut T requires &mut self
// - Arc<Mutex<...>> synchronizes pool access
}

Deref and DerefMut: Smart Pointer Pattern

Deref and DerefMut enable automatic dereferencing, making smart pointers transparent.

Without Deref:

#![allow(unused)]
fn main() {
struct Block<T> {
    data: *mut T,
}

let block = Block { data: ... };
// To access data:
unsafe { (*block.data).method() }  // Ugly!
}

With Deref:

#![allow(unused)]
fn main() {
impl<T> Deref for Block<T> {
    type Target = T;

    fn deref(&self) -> &T {
        unsafe { &*self.data }
    }
}

let block = Block { data: ... };
block.method();  // Automatic deref! Calls (*block).method()
}

Deref Coercion:

#![allow(unused)]
fn main() {
impl Deref for Block<T> {
    type Target = T;
    fn deref(&self) -> &T { ... }
}

fn takes_ref(x: &String) { ... }

let block: Block<String> = ...;
takes_ref(&block);  // Automatically coerces Block<String> to &String
// Compiler inserts: takes_ref(&*block)
}

DerefMut for Mutability:

#![allow(unused)]
fn main() {
impl<T> DerefMut for Block<T> {
    fn deref_mut(&mut self) -> &mut T {
        unsafe { &mut *self.data }
    }
}

let mut block = Block { data: ... };
block.push_str("hello");  // Calls (*block).push_str("hello")
*block = new_value;       // Direct assignment through DerefMut
}

Standard Library Examples:

#![allow(unused)]
fn main() {
// Box<T> implements Deref
let boxed = Box::new(String::from("hello"));
boxed.len();  // Calls String::len through Deref

// String implements Deref<Target = str>
let s = String::from("hello");
let len: usize = s.len();  // Calls str::len through Deref

// Vec<T> implements Deref<Target = [T]>
let vec = vec![1, 2, 3];
let slice: &[i32] = &vec;  // Deref coercion
}

Connection to This Project

In this project, you’ll implement all these concepts:

1. Milestone 1: Raw memory pool with unsafe pointer operations

   • Learn pointer arithmetic, free lists, block management
   • Understand why unsafe code is necessary

2. Milestone 2: Type-safe RAII wrappers

   • Implement Drop for automatic cleanup
   • Use PhantomData for type safety
   • Implement Deref/DerefMut for ergonomics

3. Milestone 3: Thread-safe shared pools

   • Wrap with Arc<Mutex<>> for concurrency
   • Implement Send/Sync correctly
   • Understand why manual Send/Sync impls are needed for raw pointers

Build The Project

Milestone 1: Basic Memory Pool Structure

Goal: Create a memory pool that can allocate and deallocate fixed-size blocks.

What to implement:

• Define the memory pool structure with pre-allocated memory
• Track which blocks are free/used
• Implement basic allocation and deallocation

Architecture:

• Struct: MemoryPool - Main allocator structure
  • field: memory: Vec<u8>- The pre-allocated memory buffer
  • field: block_size: usize - Size of each allocatable block
  • field: total_size: usize - Total size of the pool
  • field: free_list: Vec<usize> - Indices of free blocks Functions:
• new() - Initializes the pool with specified size
• allocate() - Returns a pointer to a free block
• deallocate() - Returns a block to the free list
• total_blocks() - Returns number of blocks in pool

Starter Code:

#![allow(unused)]
fn main() {
/// A memory pool allocator that manages fixed-size blocks
pub struct MemoryPool {
    memory: Vec<u8>,
    block_size: usize,
    total_size: usize,
    free_list: Vec<usize>,
}

impl MemoryPool {
    /// Creates a new memory pool
    /// Role: Initialize pre-allocated memory and free list
    pub fn new(total_size: usize, block_size: usize) -> Self {
        todo!("Implement pool creation")
    }

    /// Allocates a block from the pool
    /// Role: Find and return a free block, update free list
    pub fn allocate(&mut self) -> Option<*mut u8> {
        todo!("Implement allocation logic")
    }

    /// Returns a block to the pool
    /// Role: Mark block as free and add to free list
    pub fn deallocate(&mut self, ptr: *mut u8) {
        todo!("Implement deallocation logic")
    }

    /// Returns total number of blocks
    /// Role: Calculate capacity of the pool
    pub fn total_blocks(&self) -> usize {
        todo!("Implement block counting")
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_pool_creation() {
        let pool = MemoryPool::new(1024, 64);
        assert_eq!(pool.block_size, 64);
        assert_eq!(pool.total_blocks(), 16);
    }

    #[test]
    fn test_single_allocation() {
        let mut pool = MemoryPool::new(1024, 64);
        let ptr = pool.allocate();
        assert!(ptr.is_some());
    }

    #[test]
    fn test_allocation_exhaustion() {
        let mut pool = MemoryPool::new(256, 64);
        let p1 = pool.allocate();
        let p2 = pool.allocate();
        let p3 = pool.allocate();
        let p4 = pool.allocate();
        let p5 = pool.allocate(); // Should fail - only 4 blocks available
        assert!(p5.is_none());
    }

    #[test]
    fn test_deallocation_and_reuse() {
        let mut pool = MemoryPool::new(256, 64);
        let ptr1 = pool.allocate().unwrap();
        pool.deallocate(ptr1);
        let ptr2 = pool.allocate();
        assert!(ptr2.is_some());
        // Should reuse the deallocated block
    }
}
}

—Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_pool_creation() {
        let pool = MemoryPool::new(1024, 64);
        assert_eq!(pool.block_size, 64);
        assert_eq!(pool.total_blocks(), 16);
    }

    #[test]
    fn test_single_allocation() {
        let mut pool = MemoryPool::new(1024, 64);
        let ptr = pool.allocate();
        assert!(ptr.is_some());
    }

    #[test]
    fn test_allocation_exhaustion() {
        let mut pool = MemoryPool::new(256, 64);
        let p1 = pool.allocate();
        let p2 = pool.allocate();
        let p3 = pool.allocate();
        let p4 = pool.allocate();
        let p5 = pool.allocate(); // Should fail - only 4 blocks available
        assert!(p5.is_none());
    }

    #[test]
    fn test_deallocation_and_reuse() {
        let mut pool = MemoryPool::new(256, 64);
        let ptr1 = pool.allocate().unwrap();
        pool.deallocate(ptr1);
        let ptr2 = pool.allocate();
        assert!(ptr2.is_some());
        // Should reuse the deallocated block
    }
}
}

Milestone 2: Safe Wrapper with Ownership Tracking

Goal: Create a safe API that prevents use-after-free and double-free bugs.

Why the previous Milestone is not enough: Raw pointers are unsafe and error-prone. We need ownership tracking to ensure memory safety.

What’s the improvement: Introduce typed blocks with RAII (Resource Acquisition Is Initialization). When a Block<T> is dropped, memory is automatically returned to the pool.

Key concepts:

• Struct: TypedPool<T> - Type-safe memory pool

  • Field: pool: MemoryPool - Underlying raw pool
  • Field: _marker: PhantomData<T> - Zero-size type marker

• Struct: Block<T> - RAII wrapper for allocated memory

  • Field: data: *mut T - Pointer to the allocated object
  • Field: pool: *mut TypedPool<T> - Pointer back to owning pool

• Trait: Drop - Ensures automatic cleanup on drop

• Function: TypedPool::new(capacity: usize) -> Self - Creates typed pool

• Function: allocate(&mut self, value: T) -> Option<Block<T>> - Returns owned block

• Function: Drop::drop(&mut self) - Auto-returns block to pool

Starter Code:

#![allow(unused)]
fn main() {
use std::marker::PhantomData;
use std::ops::{Deref, DerefMut};

/// A typed memory pool for type T
pub struct TypedPool<T> {
    pool: MemoryPool,
    _marker: PhantomData<T>,
}

pub struct Block<'a, T> {
    data: *mut T,
    pool: &'a mut TypedPool<T>,
}

impl<T> TypedPool<T> {
    /// Creates a typed pool for type T
    /// Role: Initialize pool with size based on sizeof(T)
    pub fn new(capacity: usize) -> Self {
        todo!("Create pool with appropriate block size for T")
    }

    /// Allocates and initializes a block
    /// Role: Get memory from pool and write value into it
    pub fn allocate(&mut self, value: T) -> Option<Block<T>> {
        todo!("Allocate block and initialize with value")
    }

    /// Returns number of available blocks
    /// Role: Query pool state
    pub fn available(&self) -> usize {
        todo!("Count free blocks")
    }
}

impl<T> Deref for Block<'_, T> {
    type Target = T;

    /// Allows treating Block<T> as &T
    /// Role: Enable transparent access to inner value
    fn deref(&self) -> &Self::Target {
        todo!("Return reference to stored value")
    }
}

impl<T> DerefMut for Block<'_, T> {
    /// Allows treating Block<T> as &mut T
    /// Role: Enable mutable access to inner value
    fn deref_mut(&mut self) -> &mut Self::Target {
        todo!("Return mutable reference to stored value")
    }
}

impl<T> Drop for Block<'_, T> {
    /// Automatically returns block to pool when dropped
    /// Role: RAII cleanup - ensures no memory leaks
    fn drop(&mut self) {
        todo!("Drop the value and return memory to pool")
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_typed_allocation() {
        let mut pool = TypedPool::<u64>::new(10);
        let block = pool.allocate(42);
        assert!(block.is_some());
        assert_eq!(*block.unwrap(), 42);
    }

    #[test]
    fn test_automatic_deallocation() {
        let mut pool = TypedPool::<u64>::new(2);
        {
            let _b1 = pool.allocate(10).unwrap();
            let _b2 = pool.allocate(20).unwrap();
            // Both blocks allocated
            assert_eq!(pool.available(), 0);
        } // Both blocks dropped here

        assert_eq!(pool.available(), 2);
    }

    #[test]
    fn test_block_access() {
        let mut pool = TypedPool::<String>::new(5);
        let mut block = pool.allocate(String::from("hello")).unwrap();
        block.push_str(" world");
        assert_eq!(&*block, "hello world");
    }

    #[test]
    fn test_prevents_double_free() {
        let mut pool = TypedPool::<i32>::new(5);
        let block = pool.allocate(100).unwrap();
        drop(block);
        // Block is already freed - can't free again
        // Rust's type system prevents this at compile time
    }
}
}

Milestone 3: Thread-Safe Pool with Arc and Mutex

Goal: Make the memory pool usable across threads.

Why the previous Milestone is not enough: The pool isn’t thread-safe - concurrent allocations would cause data races.

What’s the improvement: Wrap pool in Arc<Mutex<>> to enable safe sharing across threads. Blocks now hold an Arc reference to keep the pool alive.

Architecture: Structs:

• SharedPool<T>: Clone-able, thread-safe pool
  • field: inner: Arc<Mutex<TypedPool<T>>> - Shared, locked pool
• SharedBlock<T>: Block that holds Arc reference
  • field: data: *mut T - Pointer to data
  • field*: pool: Arc<Mutex<TypedPool<T>>> - Keeps pool alive
  • field*: _marker: PhantomData<T>

Functions:

• SharedPool::new(capacity) - Creates shareable pool
• clone() - Creates another reference to same pool
• allocate(value) - Thread-safe allocation
• available() - Returns free block count

Starter Code:

#![allow(unused)]
fn main() {
use std::sync::{Arc, Mutex};

/// Thread-safe shared memory pool
pub struct SharedPool<T> {
    inner: Arc<Mutex<TypedPool<T>>>,
}

pub struct SharedBlock<T> {
    data: *mut T,
    pool: Arc<Mutex<TypedPool<T>>>,
    _marker: PhantomData<T>,
}

// Safety: SharedBlock can be sent between threads if T can
unsafe impl<T: Send> Send for SharedBlock<T> {}

impl<T> SharedPool<T> {
    /// Creates a new thread-safe pool
    /// Role: Wrap TypedPool in Arc<Mutex<>>
    pub fn new(capacity: usize) -> Self {
        todo!("Create shared pool")
    }

    /// Allocates a block from the pool
    /// Role: Lock pool and allocate safely
    pub fn allocate(&self, value: T) -> Option<SharedBlock<T>> {
        todo!("Lock, allocate, wrap in SharedBlock")
    }

    /// Returns number of available blocks
    /// Role: Query pool state thread-safely
    pub fn available(&self) -> usize {
        todo!("Lock and check availability")
    }
}

impl<T> Clone for SharedPool<T> {
    /// Clones the Arc reference to the pool
    /// Role: Enable sharing across threads
    fn clone(&self) -> Self {
        todo!("Clone the Arc")
    }
}

impl<T> Deref for SharedBlock<T> {
    type Target = T;

    /// Role: Transparent access to value
    fn deref(&self) -> &Self::Target {
        todo!("Safe dereference")
    }
}

impl<T> DerefMut for SharedBlock<T> {
    /// Role: Mutable access to value
    fn deref_mut(&mut self) -> &mut Self::Target {
        todo!("Safe mutable dereference")
    }
}

impl<T> Drop for SharedBlock<T> {
    /// Returns block to pool when dropped
    /// Role: Thread-safe cleanup
    fn drop(&mut self) {
        todo!("Lock pool and deallocate")
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    use std::thread;

    #[test]
    fn test_shared_pool_creation() {
        let pool = SharedPool::<i32>::new(10);
        let block = pool.allocate(42);
        assert!(block.is_some());
    }

    #[test]
    fn test_concurrent_allocation() {
        let pool = SharedPool::<u64>::new(100);
        let mut handles = vec![];

        for i in 0..10 {
            let pool_clone = pool.clone();
            let handle = thread::spawn(move || {
                let mut blocks = vec![];
                for j in 0..10 {
                    if let Some(block) = pool_clone.allocate(i * 10 + j) {
                        blocks.push(block);
                    }
                }
                blocks
            });
            handles.push(handle);
        }

        for handle in handles {
            handle.join().unwrap();
        }

        // All allocations should succeed
        assert_eq!(pool.available(), 0);
    }

    #[test]
    fn test_pool_survives_block_thread() {
        let pool = SharedPool::<String>::new(5);

        let block = pool.allocate(String::from("thread-safe")).unwrap();
        let pool_clone = pool.clone();

        let handle = thread::spawn(move || {
            let _block2 = pool_clone.allocate(String::from("another")).unwrap();
            // pool_clone dropped here but pool still lives
        });

        handle.join().unwrap();

        // Original block still valid
        assert_eq!(&*block, "thread-safe");
    }
}
}

Testing Strategies

1. Correctness Tests:

   • Verify allocation/deallocation work correctly
   • Test edge cases (empty pool, full pool)
   • Ensure no use-after-free or double-free

2. Concurrency Tests:

   • Spawn multiple threads allocating simultaneously
   • Use tools like loom for systematic concurrency testing
   • Verify no data races with cargo test --features=sanitizer

3. Performance Tests:

   • Benchmark pool allocator vs system allocator
   • Measure allocation/deallocation throughput
   • Test with various block sizes

4. Memory Tests:

   • Use Valgrind/Address Sanitizer to detect leaks
   • Verify all memory is freed on pool drop
   • Test alignment requirements

Complete Working Example

use std::marker::PhantomData;
use std::ops::{Deref, DerefMut};
use std::sync::{Arc, Mutex};
use std::ptr;

//==============================================================================
// Milestone  1: Raw Memory Pool
//==============================================================================

/// A memory pool allocator that manages fixed-size blocks
pub struct MemoryPool {
    memory: Vec<u8>,
    block_size: usize,
    total_size: usize,
    free_list: Vec<usize>,
}

impl MemoryPool {
    /// Creates a new memory pool with the specified total size and block size
    pub fn new(total_size: usize, block_size: usize) -> Self {
        assert!(block_size > 0, "Block size must be positive");
        assert!(total_size >= block_size, "Total size must be >= block size");

        let num_blocks = total_size / block_size;
        let actual_size = num_blocks * block_size;

        // Pre-allocate all memory
        let memory = vec![0u8; actual_size];

        // Initialize free list with all block indices
        let free_list = (0..num_blocks).collect();

        MemoryPool {
            memory,
            block_size,
            total_size: actual_size,
            free_list,
        }
    }

    /// Allocates a block from the pool, returning a pointer to it
    pub fn allocate(&mut self) -> Option<*mut u8> {
        self.free_list.pop().map(|index| {
            let offset = index * self.block_size;
            unsafe { self.memory.as_mut_ptr().add(offset) }
        })
    }

    /// Deallocates a block, returning it to the pool
    pub fn deallocate(&mut self, ptr: *mut u8) {
        let offset = unsafe {
            ptr.offset_from(self.memory.as_ptr())
        } as usize;

        assert!(offset % self.block_size == 0, "Invalid pointer alignment");
        let index = offset / self.block_size;
        assert!(index < self.total_blocks(), "Pointer out of bounds");

        self.free_list.push(index);
    }

    /// Returns the total number of blocks in the pool
    pub fn total_blocks(&self) -> usize {
        self.total_size / self.block_size
    }

    /// Returns the number of available (free) blocks
    pub fn available(&self) -> usize {
        self.free_list.len()
    }
}

//==============================================================================
// Milestone  2: Type-Safe Pool with RAII
//==============================================================================

/// A typed memory pool for allocating objects of type T
pub struct TypedPool<T> {
    pool: MemoryPool,
    _marker: PhantomData<T>,
}

/// An RAII wrapper for an allocated block
/// Automatically returns memory to pool when dropped
pub struct Block<T> {
    data: *mut T,
    pool_ptr: *mut TypedPool<T>,
    _marker: PhantomData<T>,
}

impl<T> TypedPool<T> {
    /// Creates a new typed pool with capacity for `capacity` objects
    pub fn new(capacity: usize) -> Self {
        let block_size = std::mem::size_of::<T>().max(1);
        let total_size = capacity * block_size;

        TypedPool {
            pool: MemoryPool::new(total_size, block_size),
            _marker: PhantomData,
        }
    }

    /// Allocates a block and initializes it with `value`
    pub fn allocate(&mut self, value: T) -> Option<Block<T>> {
        self.pool.allocate().map(|ptr| {
            let typed_ptr = ptr as *mut T;
            // SAFETY: We just allocated this memory and it's properly aligned
            unsafe {
                ptr::write(typed_ptr, value);
            }

            Block {
                data: typed_ptr,
                pool_ptr: self as *mut TypedPool<T>,
                _marker: PhantomData,
            }
        })
    }

    /// Returns the number of available blocks
    pub fn available(&self) -> usize {
        self.pool.available()
    }

    /// Internal function to deallocate a block
    fn deallocate_raw(&mut self, ptr: *mut T) {
        self.pool.deallocate(ptr as *mut u8);
    }
}

impl<T> Deref for Block<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        // SAFETY: data is valid for the lifetime of Block
        unsafe { &*self.data }
    }
}

impl<T> DerefMut for Block<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        // SAFETY: data is valid and uniquely owned by Block
        unsafe { &mut *self.data }
    }
}

impl<T> Drop for Block<T> {
    fn drop(&mut self) {
        // SAFETY: data was initialized in allocate()
        unsafe {
            ptr::drop_in_place(self.data);
            (*self.pool_ptr).deallocate_raw(self.data);
        }
    }
}

// SAFETY: Block can be sent between threads if T can (pool is not thread-local)
unsafe impl<T: Send> Send for Block<T> {}

//==============================================================================
// Milestone  3: Thread-Safe Shared Pool
//==============================================================================

/// A thread-safe, reference-counted memory pool
#[derive(Clone)]
pub struct SharedPool<T> {
    inner: Arc<Mutex<TypedPool<T>>>,
}

/// A block allocated from a shared pool
pub struct SharedBlock<T> {
    data: *mut T,
    pool: Arc<Mutex<TypedPool<T>>>,
    _marker: PhantomData<T>,
}

// SAFETY: SharedBlock can be sent between threads if T can
unsafe impl<T: Send> Send for SharedBlock<T> {}
unsafe impl<T: Send> Sync for SharedBlock<T> {}

impl<T> SharedPool<T> {
    /// Creates a new thread-safe shared pool
    pub fn new(capacity: usize) -> Self {
        SharedPool {
            inner: Arc::new(Mutex::new(TypedPool::new(capacity))),
        }
    }

    /// Allocates a block from the pool
    pub fn allocate(&self, value: T) -> Option<SharedBlock<T>> {
        let mut pool = self.inner.lock().unwrap();

        pool.pool.allocate().map(|ptr| {
            let typed_ptr = ptr as *mut T;
            // SAFETY: We just allocated this memory
            unsafe {
                ptr::write(typed_ptr, value);
            }

            SharedBlock {
                data: typed_ptr,
                pool: Arc::clone(&self.inner),
                _marker: PhantomData,
            }
        })
    }

    /// Returns the number of available blocks
    pub fn available(&self) -> usize {
        self.inner.lock().unwrap().available()
    }
}

impl<T> Deref for SharedBlock<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        // SAFETY: data is valid for the lifetime of SharedBlock
        unsafe { &*self.data }
    }
}

impl<T> DerefMut for SharedBlock<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        // SAFETY: We have exclusive access via &mut self
        unsafe { &mut *self.data }
    }
}

impl<T> Drop for SharedBlock<T> {
    fn drop(&mut self) {
        // SAFETY: data was initialized in allocate()
        unsafe {
            ptr::drop_in_place(self.data);
        }

        let mut pool = self.pool.lock().unwrap();
        pool.pool.deallocate(self.data as *mut u8);
    }
}

//==============================================================================
// Example Usage and Tests
//==============================================================================

fn main() {
    println!("=== Memory Pool Examples ===\n");

    // Example 1: Basic pool usage
    println!("Example 1: Basic Pool");
    {
        let mut pool = TypedPool::<i32>::new(5);
        let mut block1 = pool.allocate(42).unwrap();
        let block2 = pool.allocate(100).unwrap();

        println!("Block1: {}", *block1);
        println!("Block2: {}", *block2);

        *block1 = 99;
        println!("Block1 modified: {}", *block1);
        println!("Available blocks: {}\n", pool.available());
    }

    // Example 2: Automatic cleanup
    println!("Example 2: RAII and Automatic Cleanup");
    {
        let mut pool = TypedPool::<String>::new(3);
        println!("Initial available: {}", pool.available());

        {
            let _b1 = pool.allocate(String::from("hello")).unwrap();
            let _b2 = pool.allocate(String::from("world")).unwrap();
            println!("After 2 allocations: {}", pool.available());
        } // b1 and b2 dropped here

        println!("After blocks dropped: {}\n", pool.available());
    }

    // Example 3: Thread-safe pool
    println!("Example 3: Thread-Safe Pool");
    {
        use std::thread;

        let pool = SharedPool::<u64>::new(20);
        let mut handles = vec![];

        for i in 0..4 {
            let pool_clone = pool.clone();
            let handle = thread::spawn(move || {
                let mut local_blocks = vec![];
                for j in 0..5 {
                    if let Some(block) = pool_clone.allocate(i * 5 + j) {
                        local_blocks.push(block);
                    }
                }
                println!("Thread {} allocated {} blocks", i, local_blocks.len());
                local_blocks
            });
            handles.push(handle);
        }

        for handle in handles {
            handle.join().unwrap();
        }

        println!("Final available: {}\n", pool.available());
    }

    // Example 4: Complex type with Drop
    println!("Example 4: Complex Types");
    {
        #[derive(Debug)]
        struct Resource {
            id: usize,
            data: Vec<i32>,
        }

        impl Drop for Resource {
            fn drop(&mut self) {
                println!("Resource {} dropped", self.id);
            }
        }

        let mut pool = TypedPool::<Resource>::new(3);

        {
            let r1 = pool.allocate(Resource {
                id: 1,
                data: vec![1, 2, 3],
            }).unwrap();

            let r2 = pool.allocate(Resource {
                id: 2,
                data: vec![4, 5, 6],
            }).unwrap();

            println!("Resource 1: {:?}", *r1);
            println!("Resource 2: {:?}", *r2);
        } // Resources properly dropped

        println!();
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::thread;

    #[test]
    fn test_basic_pool() {
        let mut pool = MemoryPool::new(1024, 64);
        assert_eq!(pool.total_blocks(), 16);
        assert_eq!(pool.available(), 16);

        let ptr = pool.allocate().unwrap();
        assert_eq!(pool.available(), 15);

        pool.deallocate(ptr);
        assert_eq!(pool.available(), 16);
    }

    #[test]
    fn test_typed_pool() {
        let mut pool = TypedPool::<u64>::new(10);
        let mut block = pool.allocate(42).unwrap();
        assert_eq!(*block, 42);

        *block = 100;
        assert_eq!(*block, 100);
    }

    #[test]
    fn test_automatic_cleanup() {
        let mut pool = TypedPool::<String>::new(5);
        assert_eq!(pool.available(), 5);

        {
            let _b1 = pool.allocate(String::from("test")).unwrap();
            let _b2 = pool.allocate(String::from("test2")).unwrap();
            assert_eq!(pool.available(), 3);
        }

        assert_eq!(pool.available(), 5);
    }

    #[test]
    fn test_shared_pool_threading() {
        let pool = SharedPool::<i32>::new(100);
        let mut handles = vec![];

        for i in 0..10 {
            let pool_clone = pool.clone();
            let handle = thread::spawn(move || {
                let mut blocks = vec![];
                for j in 0..10 {
                    blocks.push(pool_clone.allocate(i * 10 + j).unwrap());
                }
                blocks
            });
            handles.push(handle);
        }

        let mut all_blocks = vec![];
        for handle in handles {
            let blocks = handle.join().unwrap();
            assert_eq!(blocks.len(), 10);
            all_blocks.extend(blocks);
        }

        // All blocks are still allocated (held by all_blocks)
        assert_eq!(pool.available(), 0);

        // Drop all blocks and verify they're returned to pool
        drop(all_blocks);
        assert_eq!(pool.available(), 100);
    }

    #[test]
    fn test_drop_behavior() {
        use std::sync::atomic::{AtomicUsize, Ordering};
        use std::sync::Arc;

        let drop_count = Arc::new(AtomicUsize::new(0));

        struct DropCounter {
            count: Arc<AtomicUsize>,
        }

        impl Drop for DropCounter {
            fn drop(&mut self) {
                self.count.fetch_add(1, Ordering::SeqCst);
            }
        }

        {
            let mut pool = TypedPool::<DropCounter>::new(5);
            let _b1 = pool
                .allocate(DropCounter {
                    count: drop_count.clone(),
                })
                .unwrap();
            let _b2 = pool
                .allocate(DropCounter {
                    count: drop_count.clone(),
                })
                .unwrap();
        }

        assert_eq!(drop_count.load(Ordering::SeqCst), 2);
    }

    // Additional tests from specification
    #[test]
    fn test_pool_creation() {
        let pool = MemoryPool::new(1024, 64);
        assert_eq!(pool.block_size, 64);
        assert_eq!(pool.total_blocks(), 16);
        assert_eq!(pool.available(), 16);
    }

    #[test]
    fn test_single_allocation() {
        let mut pool = MemoryPool::new(1024, 64);
        let ptr = pool.allocate();
        assert!(ptr.is_some());
        assert_eq!(pool.available(), 15);
    }

    #[test]
    fn test_allocation_exhaustion() {
        let mut pool = MemoryPool::new(256, 64);
        let p1 = pool.allocate();
        let p2 = pool.allocate();
        let p3 = pool.allocate();
        let p4 = pool.allocate();
        let p5 = pool.allocate(); // Should fail - only 4 blocks available

        assert!(p1.is_some());
        assert!(p2.is_some());
        assert!(p3.is_some());
        assert!(p4.is_some());
        assert!(p5.is_none());
    }

    #[test]
    fn test_deallocation_and_reuse() {
        let mut pool = MemoryPool::new(256, 64);
        let ptr1 = pool.allocate().unwrap();
        assert_eq!(pool.available(), 3);

        pool.deallocate(ptr1);
        assert_eq!(pool.available(), 4);

        let ptr2 = pool.allocate();
        assert!(ptr2.is_some());
        assert_eq!(pool.available(), 3);
    }

    #[test]
    fn test_typed_allocation() {
        let mut pool = TypedPool::<u64>::new(10);
        let block = pool.allocate(42);
        assert!(block.is_some());
        assert_eq!(*block.unwrap(), 42);
    }

    #[test]
    fn test_automatic_deallocation() {
        let mut pool = TypedPool::<u64>::new(2);
        assert_eq!(pool.available(), 2);

        {
            let _b1 = pool.allocate(10).unwrap();
            let _b2 = pool.allocate(20).unwrap();
            assert_eq!(pool.available(), 0);
        } // Both blocks dropped here

        assert_eq!(pool.available(), 2);
    }

    #[test]
    fn test_block_access() {
        let mut pool = TypedPool::<String>::new(5);
        let mut block = pool.allocate(String::from("hello")).unwrap();
        block.push_str(" world");
        assert_eq!(&*block, "hello world");
    }

    #[test]
    fn test_shared_pool_creation() {
        let pool = SharedPool::<i32>::new(10);
        let block = pool.allocate(42);
        assert!(block.is_some());
        assert_eq!(*block.unwrap(), 42);
    }

    #[test]
    fn test_concurrent_allocation() {
        let pool = SharedPool::<u64>::new(100);
        let mut handles = vec![];

        for i in 0..10 {
            let pool_clone = pool.clone();
            let handle = thread::spawn(move || {
                let mut blocks = vec![];
                for j in 0..10 {
                    if let Some(block) = pool_clone.allocate(i * 10 + j) {
                        blocks.push(block);
                    }
                }
                blocks
            });
            handles.push(handle);
        }

        let mut all_blocks = vec![];
        for handle in handles {
            all_blocks.extend(handle.join().unwrap());
        }

        // All allocations should succeed
        assert_eq!(pool.available(), 0);
        drop(all_blocks);
        assert_eq!(pool.available(), 100);
    }

    #[test]
    fn test_pool_survives_block_thread() {
        let pool = SharedPool::<String>::new(5);

        let block = pool.allocate(String::from("thread-safe")).unwrap();
        let pool_clone = pool.clone();

        let handle = thread::spawn(move || {
            let _block2 = pool_clone.allocate(String::from("another")).unwrap();
            // pool_clone dropped here but pool still lives
        });

        handle.join().unwrap();

        // Original block still valid
        assert_eq!(&*block, "thread-safe");
    }
}

Reference-Counted Smart Pointer

Problem Statement

Reference counting is fundamental to memory management in languages without garbage collection. Understanding Rc and Arc teaches you about shared ownership, reference cycles, and the trade-offs between compile-time and runtime safety. These patterns appear in GUI frameworks, graph structures, caches, and any system where data has multiple owners.

What we will write

Implement a custom reference-counted smart pointer (similar to Rc<T>) that allows multiple ownership of heap-allocated data. Your implementation should automatically free memory when the last reference is dropped and provide interior mutability through RefCell-like semantics.

Your smart pointer should support:

• Multiple owners sharing the same data
• Automatic cleanup when reference count reaches zero
• Weak references to break reference cycles
• Interior mutability patterns
• Clone-on-write optimization

Understanding Reference Counting and Smart Pointers

Before implementing reference-counted pointers, let’s understand the fundamental concepts of ownership, shared data, and the trade-offs between compile-time and runtime memory management.

What is Reference Counting?

Reference counting is a memory management technique where each object tracks how many pointers (references) point to it. When the count drops to zero, the object is automatically freed.

The Ownership Problem:

#![allow(unused)]
fn main() {
// Rust's ownership: only ONE owner
let data = String::from("hello");
let owner1 = data;  // data moved to owner1
// let owner2 = data;  // ❌ ERROR: data was moved

// What if we NEED multiple owners?
// Example: GUI widget shared by multiple event handlers
// Example: Graph node with multiple incoming edges
}

Reference Counting Solution:

#![allow(unused)]
fn main() {
// Multiple owners sharing data
let data = Rc::new(String::from("hello"));
let owner1 = Rc::clone(&data);   // ✓ OK: count = 2
let owner2 = Rc::clone(&data);   // ✓ OK: count = 3
// All three point to the same String
// String freed when all dropped (count → 0)
}

How It Works:

Create Rc<String>("hello"):
┌─────────────────────┐
│   RcInner           │
│  ┌────────────────┐ │
│  │ strong: 1      │ │ ← Reference count
│  │ data: "hello"  │ │ ← Actual data
│  └────────────────┘ │
└─────────────────────┘
        ↑
       rc1

After rc2 = rc1.clone():
┌─────────────────────┐
│   RcInner           │
│  ┌────────────────┐ │
│  │ strong: 2      │ │ ← Incremented
│  │ data: "hello"  │ │
│  └────────────────┘ │
└─────────────────────┘
    ↑           ↑
   rc1         rc2

After drop(rc1):
┌─────────────────────┐
│   RcInner           │
│  ┌────────────────┐ │
│  │ strong: 1      │ │ ← Decremented
│  │ data: "hello"  │ │
│  └────────────────┘ │
└─────────────────────┘
                ↑
               rc2

After drop(rc2):
┌─────────────────────┐
│   RcInner           │
│  ┌────────────────┐ │
│  │ strong: 0      │ │ ← Zero: FREE MEMORY!
│  │ data: "hello"  │ │ ← Dropped
│  └────────────────┘ │
└─────────────────────┘
      (deallocated)

Why Reference Counting?

1. Multiple Ownership

Some data structures naturally require shared ownership:

#![allow(unused)]
fn main() {
// Graph with cycles
struct Node {
    value: i32,
    neighbors: Vec<Rc<Node>>,  // Multiple edges can point to same node
}

let node_a = Rc::new(Node { value: 1, neighbors: vec![] });
let node_b = Rc::new(Node { value: 2, neighbors: vec![Rc::clone(&node_a)] });
let node_c = Rc::new(Node { value: 3, neighbors: vec![Rc::clone(&node_a)] });

// node_a has 3 owners: itself + node_b + node_c
// All three can access node_a's data
}

2. Dynamic Lifetime

Sometimes you don’t know which reference will be dropped last:

#![allow(unused)]
fn main() {
// GUI event handlers
struct Button {
    label: Rc<String>,
    on_click: Box<dyn Fn()>,
}

let label = Rc::new(String::from("Submit"));

let button1 = Button {
    label: Rc::clone(&label),
    on_click: Box::new(|| println!("Clicked")),
};

let button2 = Button {
    label: Rc::clone(&label),
    on_click: Box::new(|| println!("Also clicked")),
};

// Don't know if button1 or button2 will be dropped first
// Label stays alive until BOTH are dropped
}

3. Caching and Deduplication

Share identical data to save memory:

#![allow(unused)]
fn main() {
// String interning: share common strings
let mut cache: HashMap<&str, Rc<String>> = HashMap::new();

fn intern(cache: &mut HashMap<&str, Rc<String>>, s: &str) -> Rc<String> {
    cache.entry(s)
        .or_insert_with(|| Rc::new(s.to_string()))
        .clone()
}

let s1 = intern(&mut cache, "hello");  // Allocates "hello"
let s2 = intern(&mut cache, "hello");  // Reuses same allocation
// s1 and s2 point to the SAME String
// Saves memory when "hello" appears many times
}

Rc vs Box vs &T

Box: Single owner, heap allocation

#![allow(unused)]
fn main() {
let b = Box::new(42);
// Exactly one owner
// Freed when b goes out of scope
// Compile-time ownership tracking
}

&T: Borrowed reference, no ownership

#![allow(unused)]
fn main() {
let x = 42;
let r = &x;
// r borrows x
// Compiler ensures x outlives r
// Compile-time borrow checking
}

Rc: Multiple owners, heap allocation

#![allow(unused)]
fn main() {
let rc = Rc::new(42);
let rc2 = Rc::clone(&rc);
// Multiple owners
// Freed when BOTH drop
// Runtime reference counting
}

Comparison:

┌─────────┬────────────┬───────────┬──────────────┬────────────┐
│         │ Ownership  │ Lifetime  │ Safety Check │ Overhead   │
├─────────┼────────────┼───────────┼──────────────┼────────────┤
│ Box<T>  │ Single     │ Scoped    │ Compile-time │ None       │
│ &T      │ Borrowed   │ Scoped    │ Compile-time │ None       │
│ Rc<T>   │ Multiple   │ Dynamic   │ Runtime      │ Refcount   │
└─────────┴────────────┴───────────┴──────────────┴────────────┘

The Reference Cycle Problem

Reference cycles cause memory leaks with reference counting:

#![allow(unused)]
fn main() {
// MEMORY LEAK: Cycle never freed!
struct Node {
    value: i32,
    next: Option<Rc<RefCell<Node>>>,
}

let node1 = Rc::new(RefCell::new(Node { value: 1, next: None }));
let node2 = Rc::new(RefCell::new(Node { value: 2, next: None }));

// Create cycle: node1 → node2 → node1
node1.borrow_mut().next = Some(Rc::clone(&node2));
node2.borrow_mut().next = Some(Rc::clone(&node1));

// Drop both:
drop(node1);  // node1 refcount: 2 → 1 (still alive! node2 holds ref)
drop(node2);  // node2 refcount: 2 → 1 (still alive! node1 holds ref)

// ❌ MEMORY LEAK: Both nodes have refcount=1, never freed
//    They reference each other, but nothing else references them
}

Visualization:

After drop(node1) and drop(node2):

   ┌──────────────────┐
   │ Node { value: 1 }│
   │ refcount: 1      │
   │ next: ───────┐   │
   └──────────────│───┘
                  │
                  ↓
   ┌──────────────│───┐
   │ Node { value: 2 }│
   │ refcount: 1      │
   │ next: ───────┐   │
   └──────────────│───┘
                  │
                  └──────────────→ (back to Node 1)

No external references, but refcounts never reach 0!
MEMORY LEAKED: Unreachable but not freed.

Solution: Weak References

Weak<T> doesn’t increment the strong count, breaking cycles:

#![allow(unused)]
fn main() {
struct Node {
    value: i32,
    parent: Option<Weak<RefCell<Node>>>,  // ← Weak instead of Rc
    children: Vec<Rc<RefCell<Node>>>,
}

let parent = Rc::new(RefCell::new(Node {
    value: 1,
    parent: None,
    children: vec![],
}));

let child = Rc::new(RefCell::new(Node {
    value: 2,
    parent: Some(Rc::downgrade(&parent)),  // ← Weak reference
    children: vec![],
}));

parent.borrow_mut().children.push(Rc::clone(&child));

// Strong references:
// parent: 1 (our variable)
// child: 2 (our variable + parent's children vec)

// Weak references:
// parent: 1 (child's parent field)

// Drop parent:
drop(parent);  // parent refcount: 1 → 0 → FREED!

// child's weak reference to parent becomes invalid
// child.parent.upgrade() → None

// Drop child:
drop(child);  // child refcount: 1 → 0 → FREED!

// ✓ NO LEAK: All memory freed
}

Strong vs Weak References

Strong Reference (Rc):

• Keeps data alive
• Counted in strong_count
• Data freed when strong_count reaches 0

Weak Reference (Weak):

• Doesn’t keep data alive
• Counted in weak_count
• Can become invalid (data freed while weak ref exists)
• Must upgrade() to Rc<T> to access data

Reference Counting:

#![allow(unused)]
fn main() {
struct RcInner<T> {
    strong_count: usize,  // Number of Rc<T> pointers
    weak_count: usize,    // Number of Weak<T> pointers
    data: T,
}

// Rules:
// 1. Data (T) freed when strong_count = 0
// 2. RcInner freed when strong_count = 0 AND weak_count = 0
// 3. Weak refs can exist after data is freed
}

Example:

#![allow(unused)]
fn main() {
let strong = Rc::new(String::from("data"));
// strong_count: 1, weak_count: 0

let weak1 = Rc::downgrade(&strong);
// strong_count: 1, weak_count: 1

let weak2 = Rc::downgrade(&strong);
// strong_count: 1, weak_count: 2

let strong2 = weak1.upgrade().unwrap();
// strong_count: 2, weak_count: 2

drop(strong);
// strong_count: 1, weak_count: 2

drop(strong2);
// strong_count: 0 → Data (String) freed!
// weak_count: 2 → RcInner still alive (for weak refs)

weak1.upgrade();  // Returns None (data gone)
weak2.upgrade();  // Returns None

drop(weak1);
// weak_count: 1

drop(weak2);
// weak_count: 0 → RcInner freed!
}

Interior Mutability: RefCell

The Problem: Rc<T> gives shared references (&T), but we often need mutation.

#![allow(unused)]
fn main() {
let rc = Rc::new(vec![1, 2, 3]);
let rc2 = Rc::clone(&rc);

// Can't mutate through shared reference:
// rc.push(4);  // ❌ ERROR: can't call push on &Vec<i32>
}

Solution: RefCell provides interior mutability with runtime borrow checking.

#![allow(unused)]
fn main() {
let rc = Rc::new(RefCell::new(vec![1, 2, 3]));
let rc2 = Rc::clone(&rc);

// Borrow mutably at runtime:
rc.borrow_mut().push(4);  // ✓ OK: runtime check passes

println!("{:?}", rc2.borrow());  // [1, 2, 3, 4]
// Both rc and rc2 see the mutation!
}

How RefCell Works:

#![allow(unused)]
fn main() {
struct RefCell<T> {
    value: UnsafeCell<T>,      // The actual data (allows mut through &)
    borrow_state: Cell<isize>,  // Tracks borrows
}

// borrow_state values:
//  0: Not borrowed
// >0: N immutable borrows active
// -1: One mutable borrow active
}

Borrow Checking at Runtime:

#![allow(unused)]
fn main() {
let cell = RefCell::new(42);

// Multiple immutable borrows OK:
let b1 = cell.borrow();      // borrow_state: 0 → 1
let b2 = cell.borrow();      // borrow_state: 1 → 2
drop(b1);                     // borrow_state: 2 → 1
drop(b2);                     // borrow_state: 1 → 0

// Mutable borrow requires exclusive access:
let mut b = cell.borrow_mut();  // borrow_state: 0 → -1
// cell.borrow();               // ❌ PANIC: already mutably borrowed
drop(b);                         // borrow_state: -1 → 0

// Rules (enforced at runtime):
// 1. Many immutable borrows OR one mutable borrow
// 2. Violation = panic!
}

Compile-Time vs Runtime:

#![allow(unused)]
fn main() {
// Compile-time borrow checking (normal Rust):
let mut x = 42;
let r1 = &x;
let r2 = &x;
// let r3 = &mut x;  // ❌ COMPILE ERROR

// Runtime borrow checking (RefCell):
let cell = RefCell::new(42);
let r1 = cell.borrow();
let r2 = cell.borrow();
let r3 = cell.borrow_mut();  // ❌ RUNTIME PANIC!
}

Trade-offs:

Compile-time (&T, &mut T):
✓ Zero runtime cost
✓ Errors caught at compile time
✗ Can't express some valid patterns

Runtime (RefCell<T>):
✓ More flexible (can mutate through &)
✓ Enables patterns impossible with & alone
✗ Runtime overhead (checking borrows)
✗ Errors found at runtime (panics)

The Rc<RefCell> Pattern

Combining Rc and RefCell enables shared mutable state:

#![allow(unused)]
fn main() {
// Pattern: Rc<RefCell<T>>
let data = Rc::new(RefCell::new(vec![1, 2, 3]));
let data2 = Rc::clone(&data);
let data3 = Rc::clone(&data);

// All three can mutate the same Vec:
data.borrow_mut().push(4);
println!("{:?}", data2.borrow());  // [1, 2, 3, 4]

data2.borrow_mut().push(5);
println!("{:?}", data3.borrow());  // [1, 2, 3, 4, 5]
}

When to Use:

• Graphs with mutable nodes
• Observer pattern (multiple observers, mutable subject)
• Cached values that need updating
• Parent-child relationships with mutations

Example: Tree with Parent Pointers:

#![allow(unused)]
fn main() {
struct TreeNode {
    value: i32,
    parent: Option<Weak<RefCell<TreeNode>>>,  // Weak to avoid cycle
    children: Vec<Rc<RefCell<TreeNode>>>,     // Strong to keep children alive
}

let root = Rc::new(RefCell::new(TreeNode {
    value: 1,
    parent: None,
    children: vec![],
}));

let child = Rc::new(RefCell::new(TreeNode {
    value: 2,
    parent: Some(Rc::downgrade(&root)),
    children: vec![],
}));

// Add child to parent:
root.borrow_mut().children.push(Rc::clone(&child));

// Mutate child:
child.borrow_mut().value = 42;

// Access parent through child:
if let Some(parent_rc) = child.borrow().parent.as_ref().unwrap().upgrade() {
    println!("Parent value: {}", parent_rc.borrow().value);  // 1
}
}

NonNull: Raw Pointers Done Right

NonNull<T> is a wrapper around *mut T with two guarantees:

1. Pointer is never null
2. Pointer is properly aligned

Why Not *mut T?:

#![allow(unused)]
fn main() {
// *mut T can be null:
let ptr: *mut i32 = std::ptr::null_mut();
// Dangerous: no null check enforced

// NonNull<T> cannot be null:
// let ptr: NonNull<i32> = NonNull::new(std::ptr::null_mut()).unwrap();
// ✗ Panics: new() returns None for null
}

Benefits:

#![allow(unused)]
fn main() {
struct MyRc<T> {
    // ptr: *mut RcInner<T>,  // Could be null, not clear ownership
    ptr: NonNull<RcInner<T>>,  // ✓ Never null, covariant, clearer intent
}

// NonNull properties:
// 1. Size: same as *mut T (one usize)
// 2. Null check eliminated (guaranteed non-null)
// 3. Proper variance for T (covariant)
// 4. Explicit unsafe operations
}

Usage:

#![allow(unused)]
fn main() {
// Creating NonNull:
let boxed = Box::new(42);
let ptr = NonNull::new(Box::into_raw(boxed)).unwrap();

// Dereferencing (unsafe):
unsafe {
    let value = ptr.as_ref();  // &T
    let value_mut = ptr.as_mut();  // &mut T
    let raw = ptr.as_ptr();  // *mut T
}

// Freeing:
unsafe {
    drop(Box::from_raw(ptr.as_ptr()));
}
}

UnsafeCell: Foundation of Interior Mutability

UnsafeCell<T> is the only legal way to get &mut T from &UnsafeCell<T>.

The Problem:

#![allow(unused)]
fn main() {
struct Container {
    value: i32,
}

impl Container {
    fn mutate(&self) {
        // ❌ Can't do this: have &self, need &mut self.value
        // self.value = 42;
    }
}
}

Solution with UnsafeCell:

#![allow(unused)]
fn main() {
struct Container {
    value: UnsafeCell<i32>,
}

impl Container {
    fn mutate(&self) {
        unsafe {
            *self.value.get() = 42;  // ✓ OK: UnsafeCell allows this
        }
    }
}
}

Why It’s Safe:

• UnsafeCell<T> opts out of Rust’s aliasing guarantees
• You promise: no simultaneous & and &mut to the same data
• RefCell uses UnsafeCell + runtime checks to uphold this

RefCell Implementation:

#![allow(unused)]
fn main() {
pub struct RefCell<T> {
    value: UnsafeCell<T>,       // Interior mutability
    borrow_state: Cell<isize>,  // Track borrows
}

impl<T> RefCell<T> {
    pub fn borrow(&self) -> Ref<T> {
        // Check no mutable borrows:
        assert!(self.borrow_state.get() >= 0);

        self.borrow_state.set(self.borrow_state.get() + 1);

        Ref {
            value: unsafe { &*self.value.get() },  // ← UnsafeCell magic
            borrow: &self.borrow_state,
        }
    }
}
}

Connection to This Project

In this project, you’ll implement all these concepts:

1. Milestone 1: Basic reference counting with Rc<T>

   • Heap allocation with Box
   • Reference counting with clone/drop
   • NonNull for safe raw pointers
   • PhantomData for variance

2. Milestone 2: Weak references to break cycles

   • Two-count system (strong + weak)
   • Conditional freeing logic
   • Safe upgrading from weak to strong

3. Milestone 3: Interior mutability with RefCell<T>

   • UnsafeCell for legal mutation through &
   • Runtime borrow tracking
   • RAII guards (Ref/RefMut)
   • Panic on violations

Milestone 1: Basic Reference Counter

Goal: Implement a simple MyRc<T> with reference counting.

What to implement:

• Heap-allocated data with reference count
• Clone to increment count
• Drop to decrement and potentially free

Key concepts: Structs:

• MyRc<T>
  • Field: strong_count: usize - Number of MyRc pointers
  • Field: data: T - The actual data
• RcInner<T>
  • Field: ptr: NonNull<RcInner<T>> - Pointer to heap data
  • Field: _marker: PhantomData<RcInner<T>> - Ensure proper variance
• Functions:
  • new(value: T) -> MyRc<T> - Allocates and initializes
  • clone() -> MyRc<T> - Increments ref count
  • drop() - Decrements, frees if zero
  • strong_count() -> usize - Returns current count

Starter Code:

#![allow(unused)]
fn main() {
use std::ops::Deref;
use std::ptr::NonNull;

/// Inner structure holding the data and reference count
struct RcInner<T> {
    strong_count: usize,
    data: T,
}

/// A reference-counted smart pointer
pub struct MyRc<T> {
    ptr: NonNull<RcInner<T>>,
    _marker: std::marker::PhantomData<RcInner<T>>,
}

impl<T> MyRc<T> {
    /// Creates a new reference-counted pointer
    /// Role: Allocate on heap with count=1
    pub fn new(value: T) -> Self {
        todo!("Allocate RcInner on heap")
    }

    /// Returns the current strong reference count
    /// Role: Query reference count
    pub fn strong_count(this: &Self) -> usize {
        todo!("Read strong_count from inner")
    }

    /// Gets a reference to the inner data
    /// Role: Access to inner structure
    fn inner(&self) -> &RcInner<T> {
        todo!("Dereference ptr safely")
    }

    /// Gets a mutable reference to the inner data
    /// Role: Mutable access (requires unique ownership)
    fn inner_mut(&mut self) -> &mut RcInner<T> {
        todo!("Dereference ptr mutably")
    }
}

impl<T> Clone for MyRc<T> {
    /// Clones the Rc by incrementing the reference count
    /// Role: Share ownership
    fn clone(&self) -> Self {
        todo!("Increment count, return new MyRc with same ptr")
    }
}

impl<T> Deref for MyRc<T> {
    type Target = T;

    /// Allows treating MyRc<T> as &T
    /// Role: Transparent access to data
    fn deref(&self) -> &Self::Target {
        todo!("Return reference to data field")
    }
}

impl<T> Drop for MyRc<T> {
    /// Decrements count, frees memory if count reaches zero
    /// Role: Automatic cleanup
    fn drop(&mut self) {
        todo!("Decrement count, deallocate if zero")
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_basic_rc_creation() {
        let rc = MyRc::new(42);
        assert_eq!(*rc, 42);
        assert_eq!(MyRc::strong_count(&rc), 1);
    }

    #[test]
    fn test_rc_clone_increments_count() {
        let rc1 = MyRc::new(100);
        let rc2 = rc1.clone();
        assert_eq!(MyRc::strong_count(&rc1), 2);
        assert_eq!(MyRc::strong_count(&rc2), 2);
        assert_eq!(*rc1, *rc2);
    }

    #[test]
    fn test_rc_drop_decrements_count() {
        let rc1 = MyRc::new(String::from("hello"));
        {
            let rc2 = rc1.clone();
            assert_eq!(MyRc::strong_count(&rc1), 2);
            drop(rc2);
        }
        assert_eq!(MyRc::strong_count(&rc1), 1);
    }

    #[test]
    fn test_data_freed_when_count_zero() {
        use std::sync::atomic::{AtomicBool, Ordering};
        use std::sync::Arc;

        let dropped = Arc::new(AtomicBool::new(false));

        struct DropDetector {
            flag: Arc<AtomicBool>,
        }

        impl Drop for DropDetector {
            fn drop(&mut self) {
                self.flag.store(true, Ordering::SeqCst);
            }
        }

        {
            let rc = MyRc::new(DropDetector { flag: dropped.clone() });
            let _rc2 = rc.clone();
        }

        assert!(dropped.load(Ordering::SeqCst));
    }
}
}

Milestone 2: Weak References

Goal: Add weak references to prevent reference cycles.

Why the previous Milestone is not enough: Strong references create cycles (e.g., parent->child, child->parent) that never get freed.

What’s the improvement: MyWeak<T> doesn’t increment strong count. It can upgrade to MyRc<T> if data still exists, or return None if data was freed.

Architecture:

• Field: weak_count: usize (add to RcInner)

Structs:

• MyWeak<T>: Non-owning reference
  • field: ptr: NonNull<RcInner<T>> - Pointer to heap data

Functions:

• upgrade() - Try to get MyRc if data alive
• clone() - Increment weak count
• drop() - Decrement weak count

Starter Code:

#![allow(unused)]
fn main() {
/// Inner structure now tracks both strong and weak counts
struct RcInner<T> {
    strong_count: usize,
    weak_count: usize,
    data: T,
}

/// A weak reference that doesn't own the data
pub struct MyWeak<T> {
    ptr: NonNull<RcInner<T>>,
    _marker: std::marker::PhantomData<RcInner<T>>,
}

impl<T> MyRc<T> {
    /// Creates a weak reference
    /// Role: Create non-owning pointer
    pub fn downgrade(this: &Self) -> MyWeak<T> {
        todo!("Increment weak_count, create MyWeak")
    }

    /// Returns the weak reference count
    /// Role: Query weak references
    pub fn weak_count(this: &Self) -> usize {
        todo!("Read weak_count")
    }
}

impl<T> MyWeak<T> {
    /// Attempts to upgrade to a strong reference
    /// Role: Convert weak to strong if data exists
    pub fn upgrade(&self) -> Option<MyRc<T>> {
        todo!("Check strong_count > 0, increment and return MyRc")
    }

    /// Returns the strong count if data still exists
    /// Role: Query without upgrading
    pub fn strong_count(&self) -> usize {
        todo!("Read strong_count")
    }
}

impl<T> Clone for MyWeak<T> {
    /// Clone the weak reference
    /// Role: Share weak reference
    fn clone(&self) -> Self {
        todo!("Increment weak_count")
    }
}

impl<T> Drop for MyWeak<T> {
    /// Decrement weak count, free RcInner if both counts are zero
    /// Role: Cleanup weak reference
    fn drop(&mut self) {
        todo!("Decrement weak_count, free if strong=0 and weak=0")
    }
}

// Update MyRc::drop to only free data when strong=0,
// but keep RcInner alive if weak_count > 0
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_weak_creation() {
        let rc = MyRc::new(42);
        let weak = MyRc::downgrade(&rc);
        assert_eq!(MyRc::weak_count(&rc), 1);
        assert_eq!(MyRc::strong_count(&rc), 1);
    }

    #[test]
    fn test_weak_upgrade_success() {
        let rc = MyRc::new(String::from("data"));
        let weak = MyRc::downgrade(&rc);

        let upgraded = weak.upgrade();
        assert!(upgraded.is_some());
        assert_eq!(*upgraded.unwrap(), "data");
    }

    #[test]
    fn test_weak_upgrade_fails_after_drop() {
        let weak = {
            let rc = MyRc::new(100);
            let weak = MyRc::downgrade(&rc);
            weak
        }; // rc dropped here

        assert!(weak.upgrade().is_none());
    }

    #[test]
    fn test_weak_doesnt_keep_alive() {
        use std::sync::Arc;
        use std::sync::atomic::{AtomicBool, Ordering};

        let dropped = Arc::new(AtomicBool::new(false));

        struct DropDetector {
            flag: Arc<AtomicBool>,
        }

        impl Drop for DropDetector {
            fn drop(&mut self) {
                self.flag.store(true, Ordering::SeqCst);
            }
        }

        let weak = {
            let rc = MyRc::new(DropDetector { flag: dropped.clone() });
            MyRc::downgrade(&rc)
        };

        assert!(dropped.load(Ordering::SeqCst));
        assert!(weak.upgrade().is_none());
    }

    #[test]
    fn test_break_cycle() {
        use std::cell::RefCell;

        struct Node {
            parent: Option<MyWeak<RefCell<Node>>>,
            children: Vec<MyRc<RefCell<Node>>>,
        }

        let parent = MyRc::new(RefCell::new(Node {
            parent: None,
            children: vec![],
        }));

        let child = MyRc::new(RefCell::new(Node {
            parent: Some(MyRc::downgrade(&parent)),
            children: vec![],
        }));

        parent.borrow_mut().children.push(child.clone());

        // No cycle - weak ref breaks it
        assert_eq!(MyRc::strong_count(&parent), 1);
        assert_eq!(MyRc::strong_count(&child), 2);
    }
}
}

Milestone 3: Interior Mutability with RefCell

Goal: Combine MyRc with interior mutability to allow mutation through shared references.

Why the previous Milestone is not enough: MyRc gives shared &T references. We need &mut T even with multiple owners.

What’s the improvement: Implement MyRefCell<T> with runtime borrow checking. Track borrows at runtime and panic on violations.

Architecture: Structs:

• MyRefCell<T>: Interior mutability container
  • value: UnsafeCell<T> - Actual data
  • borrow_state: Cell<isize> - >0: N immutable borrows, -1: mutable borrow
• Ref<'a, T>: Immutable borrow guard
• RefMut<'a, T>: Mutable borrow guard

Functions:

• new(value) - Create new RefCell
• borrow() - Get Ref, panic if mutably borrowed
• borrow_mut() - Get RefMut, panic if any borrows exist
• try_borrow() - Non-panicking version
• try_borrow_mut() - Non-panicking version

Starter Code:

#![allow(unused)]
fn main() {
use std::cell::{Cell, UnsafeCell};

/// A cell with runtime borrow checking
pub struct MyRefCell<T> {
    value: UnsafeCell<T>,
    borrow_state: Cell<isize>,
}

pub struct Ref<'a, T> {
    value: &'a T,
    borrow: &'a Cell<isize>,
}

pub struct RefMut<'a, T> {
    value: &'a mut T,
    borrow: &'a Cell<isize>,
}

impl<T> MyRefCell<T> {
    /// Creates a new RefCell
    /// Role: Initialize with borrow_state=0
    pub fn new(value: T) -> Self {
        todo!("Initialize UnsafeCell and borrow state")
    }

    /// Borrows the value immutably
    /// Role: Increment borrow count, return Ref
    pub fn borrow(&self) -> Ref<T> {
        todo!("Check not mutably borrowed, increment count")
    }

    /// Borrows the value mutably
    /// Role: Set borrow state to -1, return RefMut
    pub fn borrow_mut(&self) -> RefMut<T> {
        todo!("Check no borrows exist, set state=-1")
    }
}

impl<T> Deref for Ref<'_, T> {
    type Target = T;

    /// Role: Transparent access
    fn deref(&self) -> &Self::Target {
        self.value
    }
}

impl<T> Drop for Ref<'_, T> {
    /// Decrements borrow count
    /// Role: Release immutable borrow
    fn drop(&mut self) {
        todo!("Decrement borrow_state")
    }
}

impl<T> Deref for RefMut<'_, T> {
    type Target = T;

    /// Role: Transparent access
    fn deref(&self) -> &Self::Target {
        self.value
    }
}

impl<T> DerefMut for RefMut<'_, T> {
    /// Role: Mutable access
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.value
    }
}

impl<T> Drop for RefMut<'_, T> {
    /// Resets borrow state to 0
    /// Role: Release mutable borrow
    fn drop(&mut self) {
        todo!("Set borrow_state to 0")
    }
}

// Safety: MyRefCell can be Send if T is Send
unsafe impl<T: Send> Send for MyRefCell<T> {}
// Note: MyRefCell is NOT Sync - can't share &MyRefCell across threads
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_refcell_basic_borrow() {
        let cell = MyRefCell::new(42);
        let borrowed = cell.borrow();
        assert_eq!(*borrowed, 42);
    }

    #[test]
    fn test_refcell_multiple_immutable() {
        let cell = MyRefCell::new(100);
        let b1 = cell.borrow();
        let b2 = cell.borrow();
        assert_eq!(*b1, *b2);
    }

    #[test]
    fn test_refcell_mutable_borrow() {
        let cell = MyRefCell::new(String::from("hello"));
        {
            let mut borrowed = cell.borrow_mut();
            borrowed.push_str(" world");
        }
        assert_eq!(&*cell.borrow(), "hello world");
    }

    #[test]
    #[should_panic(expected = "already borrowed")]
    fn test_refcell_panic_on_double_mut() {
        let cell = MyRefCell::new(42);
        let _b1 = cell.borrow_mut();
        let _b2 = cell.borrow_mut(); // Should panic
    }

    #[test]
    #[should_panic(expected = "already borrowed")]
    fn test_refcell_panic_mut_while_immutable() {
        let cell = MyRefCell::new(42);
        let _b1 = cell.borrow();
        let _b2 = cell.borrow_mut(); // Should panic
    }

    #[test]
    fn test_rc_refcell_combination() {
        let data = MyRc::new(MyRefCell::new(vec![1, 2, 3]));
        let data2 = data.clone();

        data.borrow_mut().push(4);
        assert_eq!(*data2.borrow(), vec![1, 2, 3, 4]);
    }
}
}

Complete Working Example

// Complete Reference-Counted Smart Pointer Implementation
// Implements custom Rc<T>, Weak<T>, and RefCell<T>

use std::cell::{Cell, UnsafeCell};
use std::marker::PhantomData;
use std::mem::ManuallyDrop;
use std::ops::{Deref, DerefMut};
use std::ptr::NonNull;

// ============================================================================
// Milestone 1: Basic Reference Counting (MyRc<T>)
// ============================================================================

struct RcInner<T> {
    strong_count: usize,
    weak_count: usize,
    data: ManuallyDrop<T>,
}

pub struct MyRc<T> {
    ptr: NonNull<RcInner<T>>,
    _marker: PhantomData<RcInner<T>>,
}

impl<T> MyRc<T> {
    pub fn new(value: T) -> Self {
        let inner = Box::new(RcInner {
            strong_count: 1,
            weak_count: 0,
            data: ManuallyDrop::new(value),
        });

        MyRc {
            ptr: NonNull::new(Box::into_raw(inner)).unwrap(),
            _marker: PhantomData,
        }
    }

    pub fn strong_count(this: &Self) -> usize {
        this.inner().strong_count
    }

    pub fn weak_count(this: &Self) -> usize {
        this.inner().weak_count
    }

    fn inner(&self) -> &RcInner<T> {
        unsafe { self.ptr.as_ref() }
    }

    pub fn downgrade(this: &Self) -> MyWeak<T> {
        unsafe {
            let inner = this.ptr.as_ptr();
            (*inner).weak_count += 1;
        }

        MyWeak {
            ptr: this.ptr,
            _marker: PhantomData,
        }
    }
}

impl<T> Clone for MyRc<T> {
    fn clone(&self) -> Self {
        unsafe {
            let inner = self.ptr.as_ptr();
            (*inner).strong_count += 1;
        }

        MyRc {
            ptr: self.ptr,
            _marker: PhantomData,
        }
    }
}

impl<T> Deref for MyRc<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &*self.inner().data
    }
}

impl<T> Drop for MyRc<T> {
    fn drop(&mut self) {
        unsafe {
            let inner = self.ptr.as_ptr();
            (*inner).strong_count -= 1;

            if (*inner).strong_count == 0 {
                // Snapshot weak_count before dropping data
                let had_weak_refs = (*inner).weak_count > 0;

                // Temporarily increment weak_count to prevent deallocation during data drop
                // This ensures weak refs dropped during data destruction don't free the RcInner
                (*inner).weak_count += 1;

                // Always drop the data
                ManuallyDrop::drop(&mut (*inner).data);

                // Decrement the temporary weak_count
                (*inner).weak_count -= 1;

                // Only deallocate if there were originally no weak refs AND none remain
                if !had_weak_refs && (*inner).weak_count == 0 {
                    drop(Box::from_raw(inner));
                }
            }
        }
    }
}

// ============================================================================
// Milestone 2: Weak References (MyWeak<T>)
// ============================================================================

pub struct MyWeak<T> {
    ptr: NonNull<RcInner<T>>,
    _marker: PhantomData<RcInner<T>>,
}

impl<T> MyWeak<T> {
    pub fn upgrade(&self) -> Option<MyRc<T>> {
        unsafe {
            let inner = self.ptr.as_ptr();

            if (*inner).strong_count == 0 {
                None
            } else {
                (*inner).strong_count += 1;
                Some(MyRc {
                    ptr: self.ptr,
                    _marker: PhantomData,
                })
            }
        }
    }

    pub fn strong_count(&self) -> usize {
        unsafe { (*self.ptr.as_ptr()).strong_count }
    }

    pub fn weak_count(&self) -> usize {
        unsafe { (*self.ptr.as_ptr()).weak_count }
    }
}

impl<T> Clone for MyWeak<T> {
    fn clone(&self) -> Self {
        unsafe {
            (*self.ptr.as_ptr()).weak_count += 1;
        }

        MyWeak {
            ptr: self.ptr,
            _marker: PhantomData,
        }
    }
}

impl<T> Drop for MyWeak<T> {
    fn drop(&mut self) {
        unsafe {
            let inner = self.ptr.as_ptr();
            (*inner).weak_count -= 1;

            // Only free RcInner if both counts are zero
            if (*inner).strong_count == 0 && (*inner).weak_count == 0 {
                drop(Box::from_raw(inner));
            }
        }
    }
}

// ============================================================================
// Milestone 3: Interior Mutability (MyRefCell<T>)
// ============================================================================

pub struct MyRefCell<T> {
    value: UnsafeCell<T>,
    borrow_state: Cell<isize>,
}

pub struct Ref<'a, T> {
    value: &'a T,
    borrow: &'a Cell<isize>,
}

pub struct RefMut<'a, T> {
    value: &'a mut T,
    borrow: &'a Cell<isize>,
}

impl<T> MyRefCell<T> {
    pub fn new(value: T) -> Self {
        MyRefCell {
            value: UnsafeCell::new(value),
            borrow_state: Cell::new(0),
        }
    }

    pub fn borrow(&self) -> Ref<'_, T> {
        let state = self.borrow_state.get();

        if state < 0 {
            panic!("already mutably borrowed");
        }

        self.borrow_state.set(state + 1);

        Ref {
            value: unsafe { &*self.value.get() },
            borrow: &self.borrow_state,
        }
    }

    pub fn borrow_mut(&self) -> RefMut<'_, T> {
        let state = self.borrow_state.get();

        if state != 0 {
            panic!("already borrowed");
        }

        self.borrow_state.set(-1);

        RefMut {
            value: unsafe { &mut *self.value.get() },
            borrow: &self.borrow_state,
        }
    }

    pub fn into_inner(self) -> T {
        self.value.into_inner()
    }
}

impl<T> Deref for Ref<'_, T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        self.value
    }
}

impl<T> Drop for Ref<'_, T> {
    fn drop(&mut self) {
        let state = self.borrow.get();
        self.borrow.set(state - 1);
    }
}

impl<T> Deref for RefMut<'_, T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        self.value
    }
}

impl<T> DerefMut for RefMut<'_, T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.value
    }
}

impl<T> Drop for RefMut<'_, T> {
    fn drop(&mut self) {
        self.borrow.set(0);
    }
}

unsafe impl<T: Send> Send for MyRefCell<T> {}

// ============================================================================
// Main Function - Demonstrates All Components
// ============================================================================

fn main() {
    println!("=== Reference-Counted Smart Pointer ===\n");

    // Milestone 1: Basic Reference Counting
    println!("--- Part 1: Basic Reference Counting ---");
    {
        let rc1 = MyRc::new(42);
        println!("rc1: {}, count: {}", *rc1, MyRc::strong_count(&rc1));

        let rc2 = rc1.clone();
        println!("After clone, count: {}", MyRc::strong_count(&rc1));
        println!("rc2: {}, count: {}", *rc2, MyRc::strong_count(&rc2));

        drop(rc2);
        println!("After drop rc2, count: {}", MyRc::strong_count(&rc1));
    }
    println!();

    // Milestone 2: Weak References
    println!("--- Part 2: Weak References ---");
    {
        let strong = MyRc::new(String::from("data"));
        let weak = MyRc::downgrade(&strong);

        println!("Strong count: {}", MyRc::strong_count(&strong));
        println!("Weak count: {}", MyRc::weak_count(&strong));

        if let Some(upgraded) = weak.upgrade() {
            println!("Upgraded: {}", *upgraded);
        }

        drop(strong);

        if weak.upgrade().is_none() {
            println!("Upgrade failed - data was dropped");
        }
    }
    println!();

    // Milestone 3: Breaking Reference Cycles
    println!("--- Part 3: Breaking Cycles with Weak ---");
    {
        struct Node {
            value: i32,
            parent: Option<MyWeak<MyRefCell<Node>>>,
            children: Vec<MyRc<MyRefCell<Node>>>,
        }

        let parent = MyRc::new(MyRefCell::new(Node {
            value: 1,
            parent: None,
            children: vec![],
        }));

        let child = MyRc::new(MyRefCell::new(Node {
            value: 2,
            parent: Some(MyRc::downgrade(&parent)),
            children: vec![],
        }));

        parent.borrow_mut().children.push(child.clone());

        println!("Parent value: {}", (*parent.borrow()).value);
        println!("Child value: {}", (*child.borrow()).value);

        // Access parent through child's weak reference
        let child_borrow = child.borrow();
        if let Some(weak_ref) = &child_borrow.parent {
            if let Some(parent_rc) = weak_ref.upgrade() {
                println!("Child's parent value: {}", (*parent_rc.borrow()).value);
            }
        }
    }
    println!();

    // Milestone 4: Rc<RefCell<T>> Pattern
    println!("--- Part 4: Rc<RefCell<T>> Pattern ---");
    {
        let data = MyRc::new(MyRefCell::new(vec![1, 2, 3]));
        let data2 = data.clone();
        let data3 = data.clone();

        println!("Initial: {:?}", *data.borrow());

        data.borrow_mut().push(4);
        println!("After data.push(4): {:?}", *data2.borrow());

        data2.borrow_mut().push(5);
        println!("After data2.push(5): {:?}", *data3.borrow());
    }
    println!();

    // Milestone 5: RefCell Borrow Checking
    println!("--- Part 5: RefCell Borrow Checking ---");
    {
        let cell = MyRefCell::new(100);

        {
            let b1 = cell.borrow();
            let b2 = cell.borrow();
            println!("Multiple immutable borrows: {} and {}", *b1, *b2);
        }

        {
            let mut b = cell.borrow_mut();
            *b += 50;
            println!("Mutable borrow, new value: {}", *b);
        }

        println!("Final value: {}", *cell.borrow());
    }
    println!();

    println!("=== All Components Complete! ===");
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // Milestone 1: MyRc Tests
    #[test]
    fn test_rc_basic() {
        let rc = MyRc::new(42);
        assert_eq!(*rc, 42);
        assert_eq!(MyRc::strong_count(&rc), 1);
    }

    #[test]
    fn test_rc_clone() {
        let rc1 = MyRc::new(100);
        let rc2 = rc1.clone();
        assert_eq!(MyRc::strong_count(&rc1), 2);
        assert_eq!(*rc1, *rc2);
    }

    #[test]
    fn test_rc_multiple_clones() {
        let rc1 = MyRc::new(String::from("hello"));
        let rc2 = rc1.clone();
        let rc3 = rc1.clone();
        let rc4 = rc2.clone();

        assert_eq!(MyRc::strong_count(&rc1), 4);
        assert_eq!(*rc1, "hello");
        assert_eq!(*rc2, "hello");
        assert_eq!(*rc3, "hello");
        assert_eq!(*rc4, "hello");
    }

    #[test]
    fn test_rc_drop() {
        let rc1 = MyRc::new(42);
        let rc2 = rc1.clone();
        let rc3 = rc1.clone();

        assert_eq!(MyRc::strong_count(&rc1), 3);
        drop(rc2);
        assert_eq!(MyRc::strong_count(&rc1), 2);
        drop(rc3);
        assert_eq!(MyRc::strong_count(&rc1), 1);
    }

    // Milestone 2: MyWeak Tests
    #[test]
    fn test_weak_upgrade() {
        let strong = MyRc::new(42);
        let weak = MyRc::downgrade(&strong);

        assert!(weak.upgrade().is_some());
        assert_eq!(*weak.upgrade().unwrap(), 42);

        drop(strong);
        assert!(weak.upgrade().is_none());
    }

    #[test]
    fn test_weak_counts() {
        let strong = MyRc::new(100);
        assert_eq!(MyRc::strong_count(&strong), 1);
        assert_eq!(MyRc::weak_count(&strong), 0);

        let weak1 = MyRc::downgrade(&strong);
        assert_eq!(MyRc::strong_count(&strong), 1);
        assert_eq!(MyRc::weak_count(&strong), 1);

        let _weak2 = weak1.clone();
        assert_eq!(MyRc::weak_count(&strong), 2);

        drop(weak1);
        assert_eq!(MyRc::weak_count(&strong), 1);
    }

    #[test]
    fn test_weak_survives_strong_drop() {
        let strong = MyRc::new(String::from("data"));
        let weak = MyRc::downgrade(&strong);

        assert_eq!(weak.strong_count(), 1);
        drop(strong);
        assert_eq!(weak.strong_count(), 0);
        assert!(weak.upgrade().is_none());
    }

    #[test]
    fn test_multiple_weak_refs() {
        let strong = MyRc::new(42);
        let weak1 = MyRc::downgrade(&strong);
        let weak2 = MyRc::downgrade(&strong);
        let weak3 = weak1.clone();

        assert_eq!(MyRc::weak_count(&strong), 3);

        assert_eq!(*weak1.upgrade().unwrap(), 42);
        assert_eq!(*weak2.upgrade().unwrap(), 42);
        assert_eq!(*weak3.upgrade().unwrap(), 42);
    }

    // Milestone 3: MyRefCell Tests
    #[test]
    fn test_refcell_borrow() {
        let cell = MyRefCell::new(42);
        let b1 = cell.borrow();
        let b2 = cell.borrow();
        assert_eq!(*b1, *b2);
        assert_eq!(*b1, 42);
    }

    #[test]
    fn test_refcell_borrow_mut() {
        let cell = MyRefCell::new(42);
        *cell.borrow_mut() = 100;
        assert_eq!(*cell.borrow(), 100);
    }

    #[test]
    fn test_refcell_sequential_borrows() {
        let cell = MyRefCell::new(0);

        {
            let b = cell.borrow();
            assert_eq!(*b, 0);
        }

        {
            let mut b = cell.borrow_mut();
            *b = 10;
        }

        {
            let b = cell.borrow();
            assert_eq!(*b, 10);
        }
    }

    #[test]
    #[should_panic(expected = "already mutably borrowed")]
    fn test_refcell_panic_immut_while_mut() {
        let cell = MyRefCell::new(42);
        let _b1 = cell.borrow_mut();
        let _b2 = cell.borrow(); // Should panic
    }

    #[test]
    #[should_panic(expected = "already borrowed")]
    fn test_refcell_panic_mut_while_immut() {
        let cell = MyRefCell::new(42);
        let _b1 = cell.borrow();
        let _b2 = cell.borrow_mut(); // Should panic
    }

    #[test]
    #[should_panic(expected = "already borrowed")]
    fn test_refcell_panic_mut_while_mut() {
        let cell = MyRefCell::new(42);
        let _b1 = cell.borrow_mut();
        let _b2 = cell.borrow_mut(); // Should panic
    }

    #[test]
    fn test_refcell_multiple_immutable_borrows() {
        let cell = MyRefCell::new(vec![1, 2, 3]);
        let b1 = cell.borrow();
        let b2 = cell.borrow();
        let b3 = cell.borrow();

        assert_eq!(*b1, vec![1, 2, 3]);
        assert_eq!(*b2, vec![1, 2, 3]);
        assert_eq!(*b3, vec![1, 2, 3]);
    }

    #[test]
    fn test_refcell_into_inner() {
        let cell = MyRefCell::new(42);
        *cell.borrow_mut() = 100;
        assert_eq!(cell.into_inner(), 100);
    }

    // Combined Tests
    #[test]
    fn test_rc_refcell_pattern() {
        let data = MyRc::new(MyRefCell::new(vec![1, 2, 3]));
        let data2 = data.clone();

        data.borrow_mut().push(4);
        assert_eq!(*data2.borrow(), vec![1, 2, 3, 4]);

        data2.borrow_mut().push(5);
        assert_eq!(*data.borrow(), vec![1, 2, 3, 4, 5]);
    }

    #[test]
    fn test_tree_structure() {
        struct TreeNode {
            value: i32,
            parent: Option<MyWeak<MyRefCell<TreeNode>>>,
            children: Vec<MyRc<MyRefCell<TreeNode>>>,
        }

        let root = MyRc::new(MyRefCell::new(TreeNode {
            value: 1,
            parent: None,
            children: vec![],
        }));

        let child1 = MyRc::new(MyRefCell::new(TreeNode {
            value: 2,
            parent: Some(MyRc::downgrade(&root)),
            children: vec![],
        }));

        let child2 = MyRc::new(MyRefCell::new(TreeNode {
            value: 3,
            parent: Some(MyRc::downgrade(&root)),
            children: vec![],
        }));

        root.borrow_mut().children.push(child1.clone());
        root.borrow_mut().children.push(child2.clone());

        assert_eq!((*root.borrow()).value, 1);
        assert_eq!((*root.borrow()).children.len(), 2);

        // Access parent through child
        let child1_borrow = child1.borrow();
        let parent = child1_borrow.parent.as_ref().unwrap().upgrade().unwrap();
        assert_eq!((*parent.borrow()).value, 1);
    }

    #[test]
    fn test_drop_behavior() {
        use std::sync::atomic::{AtomicUsize, Ordering};
        use std::sync::Arc;

        let drop_count = Arc::new(AtomicUsize::new(0));

        struct DropCounter {
            count: Arc<AtomicUsize>,
        }

        impl Drop for DropCounter {
            fn drop(&mut self) {
                self.count.fetch_add(1, Ordering::SeqCst);
            }
        }

        {
            let rc1 = MyRc::new(DropCounter {
                count: drop_count.clone(),
            });
            let rc2 = rc1.clone();
            let rc3 = rc1.clone();

            assert_eq!(drop_count.load(Ordering::SeqCst), 0);
            drop(rc1);
            assert_eq!(drop_count.load(Ordering::SeqCst), 0);
            drop(rc2);
            assert_eq!(drop_count.load(Ordering::SeqCst), 0);
            drop(rc3);
        }

        assert_eq!(drop_count.load(Ordering::SeqCst), 1);
    }
}

Type-Safe Configuration System

Problem Statement

Build a configuration system for a web server that uses newtype wrappers to prevent common configuration errors. You’ll start with basic structs, then add type safety through newtypes, validated types, and finally a fluent builder API.

Use Cases

When you need this pattern:

1. Server configuration: Ports, hostnames, URLs, timeouts - prevent mixing
2. Database configuration: Connection strings, pool sizes, credentials
3. API clients: Endpoints, API keys, rate limits, retry policies
4. File paths: Config vs data vs cache paths - type-safe separation
5. Resource limits: Memory limits, CPU limits, connection limits - enforce positivity
6. Credentials: Username, password, API tokens - hide in Debug output

Understanding Type-Safe Configuration

Before implementing the configuration system, let’s understand the fundamental concepts of type safety, newtypes, and builder patterns that make configuration robust and maintainable.

What is the Newtype Pattern?

The newtype pattern creates a new type that wraps an existing type, giving it a distinct identity in the type system. It’s called “newtype” because you create a new type with the same representation as an existing type.

Basic Syntax:

#![allow(unused)]
fn main() {
struct Port(u16);  // Port is a NEW type, distinct from u16
}

Even though Port contains a u16, Rust treats them as completely different types.

The Problem: Primitive Obsession:

#![allow(unused)]
fn main() {
fn start_server(host: String, port: u16, timeout: u64) {
    // What units is timeout? Seconds? Milliseconds?
    // What if someone passes port as timeout?
    // All we know is: String, u16, u64 (too generic!)
}

// Bugs waiting to happen:
start_server("localhost".to_string(), 30, 8080);  // Swapped port and timeout!
start_server("8080".to_string(), 8080, 30);       // Passed port as host!
}

Solution with Newtypes:

#![allow(unused)]
fn main() {
struct Hostname(String);
struct Port(u16);
struct Timeout(Duration);

fn start_server(host: Hostname, port: Port, timeout: Timeout) {
    // Types make it IMPOSSIBLE to swap parameters!
}

// These won't compile:
start_server(Port(8080), Hostname("localhost".into()), ...);  // ❌ Wrong order
start_server(Hostname("8080".into()), Port(30), ...);         // ❌ Nonsensical values
}

Why Newtypes? The Benefits

1. Type Safety at Compile Time

#![allow(unused)]
fn main() {
struct Meters(f64);
struct Feet(f64);

fn build_bridge(length: Meters) { }

let length_meters = Meters(100.0);
let length_feet = Feet(328.0);

build_bridge(length_meters);  // ✓ OK
build_bridge(length_feet);    // ❌ Compile error!
}

Real disaster: Mars Climate Orbiter (1999) - $327 million spacecraft lost because one team used metric units, another used imperial units. A newtype could have prevented this!

2. Self-Documenting Code

#![allow(unused)]
fn main() {
// Without newtypes - confusing
fn configure(a: u16, b: u16, c: u16) -> Result<(), String> {
    // Which is port? Which is timeout? Which is max connections?
}

// With newtypes - crystal clear
fn configure(
    port: Port,
    timeout_ms: TimeoutMillis,
    max_conn: MaxConnections
) -> Result<(), String> {
    // Intent is immediately obvious!
}
}

3. Encapsulation and Validation

#![allow(unused)]
fn main() {
struct Port(u16);

impl Port {
    pub fn new(port: u16) -> Result<Self, String> {
        if port == 0 || port > 65535 {
            Err("Port must be 1-65535".into())
        } else {
            Ok(Port(port))
        }
    }

    // Private: can only create Port through new()
    // Guarantees: all Port values are valid!
}

// Once created, Port is GUARANTEED valid
fn bind(port: Port) {
    // No need to check if port is valid - type system ensures it!
    TcpListener::bind(("0.0.0.0", port.0)).unwrap();
}
}

4. Zero Runtime Cost

#![allow(unused)]
fn main() {
struct Port(u16);

// At runtime:
assert_eq!(std::mem::size_of::<Port>(), std::mem::size_of::<u16>());
// Both are 2 bytes - no overhead!

// Compiler optimizes away the wrapper completely
}

This is called a zero-cost abstraction: safety without performance penalty.

Parse, Don’t Validate: A Philosophy

The Traditional Approach (Validation):

#![allow(unused)]
fn main() {
fn process_config(port: u16) {
    if port == 0 {
        panic!("Invalid port");
    }
    // ... use port ...

    some_other_function(port);  // Must validate AGAIN!
}

fn some_other_function(port: u16) {
    if port == 0 {  // Duplicate validation everywhere!
        panic!("Invalid port");
    }
    // ... use port ...
}
}

Problems:

• Validation logic scattered everywhere
• Easy to forget validation
• No compile-time guarantee

The Newtype Approach (Parsing):

#![allow(unused)]
fn main() {
fn process_config(port_str: &str) -> Result<(), String> {
    let port = Port::new(port_str.parse()?)?;  // Parse ONCE
    // From here on, port is GUARANTEED valid!

    some_other_function(port);  // No re-validation needed!
}

fn some_other_function(port: Port) {
    // Type signature says: port is valid
    // No validation code needed!
}
}

Benefits:

• Validation happens exactly once (at boundary)
• Type system propagates validity guarantee
• Impossible to forget validation

Slogan: “Parse, don’t validate” - convert untrustworthy input into trustworthy types once, then rely on types.

NonZeroU32: Built-in Safety

Rust provides NonZeroU32 (and similar types) to encode “never zero” at the type level.

Why It Exists:

#![allow(unused)]
fn main() {
// Without NonZeroU32
struct MaxConnections(u32);

impl MaxConnections {
    fn new(count: u32) -> Result<Self, String> {
        if count == 0 {
            Err("Count must be > 0".into())
        } else {
            Ok(MaxConnections(count))
        }
    }
}

// Problem: Must validate manually, easy to forget check
}

With NonZeroU32:

#![allow(unused)]
fn main() {
use std::num::NonZeroU32;

struct MaxConnections(NonZeroU32);

impl MaxConnections {
    fn new(count: u32) -> Result<Self, String> {
        NonZeroU32::new(count)
            .map(MaxConnections)
            .ok_or_else(|| "Count must be > 0".into())
    }
}

// Benefits:
// 1. Type guarantees: can't create NonZeroU32 with 0
// 2. Niche optimization: Option<NonZeroU32> is same size as NonZeroU32
// 3. Documentation: type signature self-documents the constraint
}

The Niche Optimization:

#![allow(unused)]
fn main() {
// Regular u32
assert_eq!(std::mem::size_of::<u32>(), 4);
assert_eq!(std::mem::size_of::<Option<u32>>(), 8);  // Need discriminant

// NonZeroU32 uses 0 as "None" sentinel
assert_eq!(std::mem::size_of::<NonZeroU32>(), 4);
assert_eq!(std::mem::size_of::<Option<NonZeroU32>>(), 4);  // ← Same size!

// Rust uses 0 to represent None, avoiding extra space for discriminant
}

The Builder Pattern

The builder pattern provides a fluent API for constructing complex objects step-by-step.

The Problem with Constructors:

#![allow(unused)]
fn main() {
// Too many parameters - hard to remember order
ServerConfig::new(
    "localhost".to_string(),
    8080,
    30,
    100,
    true,
    false,
    LogLevel::Info,
    Some("/var/log".into()),
);

// Which number is what? Easy to mix up!
}

Solution: Builder Pattern:

#![allow(unused)]
fn main() {
let config = ServerConfig::builder()
    .host("localhost")       // Clear what each does
    .port(8080)
    .timeout_secs(30)
    .max_connections(100)
    .enable_logging(true)
    .log_level(LogLevel::Info)
    .build()?;
}

How It Works:

#![allow(unused)]
fn main() {
struct ServerConfigBuilder {
    host: Option<String>,       // None = not set yet
    port: Option<u16>,
    timeout_secs: Option<u64>,
    // ... other fields ...
}

impl ServerConfigBuilder {
    fn new() -> Self {
        Self {
            host: None,
            port: None,
            timeout_secs: None,
        }
    }

    fn host(mut self, host: impl Into<String>) -> Self {
        self.host = Some(host.into());
        self  // Return self for chaining!
    }

    fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }

    fn build(self) -> Result<ServerConfig, Vec<String>> {
        // Validate all fields and construct ServerConfig
    }
}
}

Key Design Decisions:

1. Consuming self vs &mut self:

#![allow(unused)]
fn main() {
// Option A: &mut self (mutable reference)
fn port(&mut self, port: u16) -> &mut Self {
    self.port = Some(port);
    self
}

// Usage
let mut builder = ServerConfig::builder();
builder.port(8080).timeout_secs(30);

// Option B: self (consuming)
fn port(mut self, port: u16) -> Self {
    self.port = Some(port);
    self
}

// Usage - more ergonomic!
let config = ServerConfig::builder()
    .port(8080)
    .timeout_secs(30)
    .build();
}

Taking self by value:

• ✓ More ergonomic (no mut needed)
• ✓ Prevents reuse of partial builders
• ✓ Feels more “fluent”
• ✗ Slightly less flexible

2. impl Into<T> for Flexibility:

#![allow(unused)]
fn main() {
fn host(mut self, host: impl Into<String>) -> Self {
    self.host = Some(host.into());
    self
}

// Now accepts:
builder.host("localhost")             // &str
builder.host(hostname_string)         // String
builder.host(cow_string)              // Cow<str>
builder.host(format!("host{}", 1))   // String from format!
}

Much better than:

#![allow(unused)]
fn main() {
fn host(mut self, host: String) -> Self {
    // Forces callers to call .to_string() everywhere!
}
}

3. Validation at build(), Not Setters:

#![allow(unused)]
fn main() {
// ❌ Bad: Validate in setters
fn port(mut self, port: u16) -> Result<Self, String> {
    if port == 0 {
        return Err("Invalid port".into());
    }
    self.port = Some(port);
    Ok(self)
}

// Annoying: every setter returns Result!
let config = ServerConfig::builder()
    .port(8080)?           // Awkward
    .timeout_secs(30)?     // Lots of ?
    .build()?;

// ✓ Good: Validate in build()
fn port(mut self, port: u16) -> Self {
    self.port = Some(port);  // Just store, don't validate yet
    self
}

fn build(self) -> Result<ServerConfig, Vec<String>> {
    // Validate everything here, collect ALL errors
}

// Clean API:
let config = ServerConfig::builder()
    .port(8080)
    .timeout_secs(30)
    .build()?;  // Single ? at end
}

Comprehensive Error Reporting

The Problem: Fail-Fast Validation:

#![allow(unused)]
fn main() {
fn validate(config: &Config) -> Result<(), String> {
    if config.port == 0 {
        return Err("Invalid port".into());  // Stop here!
    }
    if config.timeout == 0 {
        return Err("Invalid timeout".into());  // Never reached if port invalid
    }
    if config.max_conn == 0 {
        return Err("Invalid max_conn".into());  // Never reached if timeout invalid
    }
    Ok(())
}

// User experience:
// Run 1: "Invalid port" → fix port
// Run 2: "Invalid timeout" → fix timeout
// Run 3: "Invalid max_conn" → fix max_conn
// THREE iterations to find all errors!
}

Solution: Collect All Errors:

#![allow(unused)]
fn main() {
fn build(self) -> Result<ServerConfig, Vec<String>> {
    let mut errors = Vec::new();

    // Validate port
    let port = match self.port {
        Some(p) => match Port::new(p) {
            Ok(port) => port,
            Err(e) => {
                errors.push(format!("Port: {}", e));
                Port::new(8080).unwrap()  // Placeholder to continue
            }
        },
        None => Port::new(8080).unwrap(),  // Default
    };

    // Validate timeout (even if port failed!)
    let timeout = match self.timeout_secs {
        Some(t) => match Timeout::from_secs(t) {
            Ok(timeout) => timeout,
            Err(e) => {
                errors.push(format!("Timeout: {}", e));
                Timeout::from_secs(30).unwrap()
            }
        },
        None => Timeout::from_secs(30).unwrap(),
    };

    // ... validate all fields ...

    if !errors.is_empty() {
        Err(errors)  // Return ALL errors at once!
    } else {
        Ok(ServerConfig::new(port, timeout, ...))
    }
}

// User experience:
// Run 1: "Port: must be > 0, Timeout: must be > 0, MaxConn: must be > 0"
// ONE iteration to find all errors!
}

The Deref Trait: Transparent Access

Deref allows a type to behave like a reference to another type.

Without Deref:

#![allow(unused)]
fn main() {
struct Port(u16);

impl Port {
    fn get(&self) -> u16 {
        self.0
    }
}

let port = Port(8080);
println!("Port: {}", port.get());  // Verbose
if port.get() > 1024 { }           // Clunky
}

With Deref:

#![allow(unused)]
fn main() {
use std::ops::Deref;

impl Deref for Port {
    type Target = u16;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

let port = Port(8080);
println!("Port: {}", *port);  // Dereference to get u16
if *port > 1024 { }           // Direct comparison

// Auto-deref in many contexts:
if port > 1024 { }            // Compiler auto-inserts *
}

How Deref Coercion Works:

#![allow(unused)]
fn main() {
impl Deref for Port {
    type Target = u16;
    fn deref(&self) -> &u16 { &self.0 }
}

fn takes_u16(n: &u16) { }

let port = Port(8080);
takes_u16(&port);  // Compiler: &Port → &u16 via Deref!

// Compiler automatically tries:
// 1. Is &Port compatible with &u16? No
// 2. Does Port implement Deref? Yes, with Target = u16
// 3. Convert &Port to &u16 by calling deref()
}

When to Use Deref:

✅ Good:

• Smart pointers (Box<T>, Rc<T>, Arc<T>)
• Newtypes that are “essentially” the inner type
• Want transparent access to wrapped value

❌ Avoid:

• Type has additional semantics beyond wrapper
• Would hide important type distinction
• Inner type is implementation detail

Example of BAD Deref use:

#![allow(unused)]
fn main() {
// DON'T do this!
struct Password(String);

impl Deref for Password {
    type Target = String;
    fn deref(&self) -> &String { &self.0 }
}

// Now Password behaves like String:
let pw = Password("secret123".into());
println!("{}", pw);  // ❌ Accidentally prints password!

// Better: NO Deref, force explicit access
// pw.as_str()  // Explicit, harder to accidentally leak
}

Default Values and Required Fields

Design Pattern: Optional vs Required:

#![allow(unused)]
fn main() {
impl ServerConfigBuilder {
    fn build(self) -> Result<ServerConfig, Vec<String>> {
        let mut errors = Vec::new();

        // REQUIRED field: Error if missing
        let host = match self.host {
            Some(h) if !h.is_empty() => Hostname(h),
            Some(_) => {
                errors.push("Host cannot be empty".into());
                Hostname("localhost".into())  // Placeholder for error path
            }
            None => {
                errors.push("Host is required".into());
                Hostname("localhost".into())
            }
        };

        // OPTIONAL field: Default if missing
        let port = match self.port {
            Some(p) => Port::new(p)?,
            None => Port::new(8080).unwrap(),  // Sensible default
        };

        // ...
    }
}
}

Choosing Good Defaults:

✓ Good defaults:

• Port 8080 (common HTTP alternate)
• Timeout 30 seconds (reasonable for web)
• Max connections 100 (prevents resource exhaustion)

✗ Bad defaults:

• Port 0 (invalid!)
• Timeout 0 (no timeout = hang forever)
• Max connections unlimited (resource exhaustion)

Document defaults:

#![allow(unused)]
fn main() {
impl ServerConfig {
    /// Creates a builder with these defaults:
    /// - port: 8080
    /// - timeout: 30 seconds
    /// - max_connections: 100
    pub fn builder() -> ServerConfigBuilder {
        ServerConfigBuilder::new()
    }
}
}

Connection to This Project

In this project, you’ll implement all these concepts:

1. Milestone 1: Basic struct with primitive types

   • See the problems with type-unsafe config
   • Understand why validation is insufficient

2. Milestone 2: Newtype wrappers with validation

   • Create distinct types for each config value
   • Implement smart constructors
   • Use NonZeroU32 for guaranteed non-zero values
   • Achieve zero-cost type safety

3. Milestone 3: Builder pattern with defaults

   • Fluent API for construction
   • Comprehensive error collection
   • Deref for ergonomic access
   • Optional fields with sensible defaults

Key Learning Points:

• Newtypes provide compile-time safety at zero runtime cost
• Smart constructors enforce invariants once at creation
• Builder pattern makes complex construction ergonomic
• Collecting all errors improves user experience
• Deref enables transparent access while maintaining type safety

Real-World Applications:

• AWS SDK: All service clients use builder pattern
• reqwest: HTTP client configuration
• tokio: Runtime and task configuration
• diesel: Database connection configuration
• clap: Command-line argument parsing
• serde: Serialization configuration

Why It Matters

Real-World Impact: Configuration bugs are a major source of production outages:

The Configuration Hell Problem:

• Knight Capital (2012): Wrong server configuration caused $440M loss in 45 minutes
• AWS S3 Outage (2017): Typo in configuration command took down large portion of internet
• Common bugs: Port 80 vs 8080, localhost vs production host, mixing dev/prod credentials
• Type confusion: Passing timeout in seconds vs milliseconds, mixing database connection strings

Without Type Safety:

#![allow(unused)]
fn main() {
struct Config {
    host: String,      // Could be "localhost", "localhost:8080", or "https://..."
    port: u16,         // Could be 0, 99999, or negative number
    timeout: u64,      // Seconds? Milliseconds? Minutes?
    max_connections: i32, // Could be negative!
}

// Bug: Accidentally swap host and database_url
let config = Config {
    host: "postgres://localhost/db".to_string(), // Wrong!
    port: 5432,  // Database port, not HTTP port!
    timeout: 30, // 30 what?
    max_connections: -1, // Negative connections?
};
}

With Newtype Pattern:

#![allow(unused)]
fn main() {
struct Hostname(String);
struct Port(u16);
struct Timeout(Duration);
struct MaxConnections(NonZeroU32);

// Compiler prevents mixing types
fn connect(host: Hostname, port: Port) { }
connect(Port(8080), Hostname("localhost")); // ❌ Compile error!
}

Performance Benefits:

• Zero runtime cost: Newtypes compile to same memory layout as wrapped type
• Compile-time guarantees: Invalid states impossible to represent
• Elimination of defensive code: No need to check if port > 0, it’s guaranteed

Type Safety Prevents:

• Passing milliseconds where seconds expected (1000x bug!)
• Using database port for HTTP server
• Negative values for counts/sizes
• Empty strings for required fields
• Mixing development and production settings

Milestone 1: Basic Configuration Struct

Goal: Create a basic configuration struct ServerConfig with named fields to group related configuration data

struct ServerConfig

• field: host: String, // Server hostname/IP address (e.g., “localhost”, “0.0.0.0”)
• field: port: u16, // TCP port number (1-65535)
• field: timeout_seconds: u64, // Connection timeout duration in seconds
• field: max_connections: u32, // Maximum concurrent client connections allowed

Memory Layout:

#![allow(unused)]
fn main() {
ServerConfig:
  host: String         [24 bytes: ptr + len + capacity]
  port: u16            [2 bytes]
  timeout_seconds: u64 [8 bytes]
  max_connections: u32 [4 bytes]
  [+ 6 bytes padding for alignment]
Total: ~44 bytes
}

No runtime overhead for grouping is just the sum of field sizes plus alignment.

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_basic_config() {
    let config = ServerConfig::new(
        "localhost".to_string(),
        8080,
        30,
        100,
    );

    assert_eq!(config.host, "localhost");
    assert_eq!(config.port, 8080);
}

#[test]
fn test_can_create_invalid_config() {
    // This compiles but is semantically wrong!
    let bad_config = ServerConfig::new(
        "".to_string(),           // Empty host
        0,                        // Invalid port
        0,                        // Zero timeout
        0,                        // Zero connections
    );

    // No way to prevent this at compile time yet
    assert_eq!(bad_config.port, 0);
}
}

Starter Code:

#![allow(unused)]
fn main() {
// ServerConfig: Main configuration struct for web server settings
// Role: Groups all server configuration parameters together
#[derive(Debug, Clone)]
struct ServerConfig {
    host: String,           // Server hostname/IP address (e.g., "localhost", "0.0.0.0")
    port: u16,             // TCP port number (1-65535)
    timeout_seconds: u64,  // Connection timeout duration in seconds
    max_connections: u32,  // Maximum concurrent client connections allowed
}

impl ServerConfig {
    // new: Constructor that creates a ServerConfig instance
    // Role: Initializes configuration with provided values
    fn new(host: String, port: u16, timeout_seconds: u64, max_connections: u32) -> Self {
        // TODO: Create ServerConfig with given values
        todo!()
    }
}
}

Check Your Understanding:

• What’s wrong with allowing port: 0 or max_connections: 0?
• How could we accidentally pass the wrong string to the host parameter?
• What happens if someone passes timeout in milliseconds by mistake?

Why Milestone 1 Isn’t Enough

Critical Limitations:

1. No type safety: Can swap host and database_url parameters - both are String
2. No validation: Can create config with port: 0, max_connections: 0, empty host
3. No semantic meaning: Is timeout in seconds? Milliseconds? Minutes?
4. Easy to mix up: ServerConfig::new(port_str, host_str) compiles if you swap them
5. Debug leaks secrets: println!("{:?}", config) might print passwords

What we’re adding: Newtype wrappers for each configuration value:

• Port(u16), Hostname(String), Timeout(Duration), MaxConnections(NonZeroU32)
• Each is a distinct type - compiler prevents mixing them up
• Smart constructors validate inputs
• Custom Debug implementations hide sensitive data

Improvements:

• Type safety: Can’t pass Port where Hostname expected
• Validation: Port::new(0) returns Err - can’t create invalid port
• Clarity: Timeout(Duration::from_secs(30)) is unambiguous
• Security: Password type hides value in Debug output

Milestone 2: Newtype Wrappers for Type Safety

Goal: Wrap each configuration field in a distinct newtype to prevent accidental mixing and enable field-specific validation.

The Core Problem: Primitive Obsession:

#![allow(unused)]
fn main() {
// All these are just numbers or strings!
fn configure(
    port: u16,           // Could be 0-65535
    timeout: u64,        // Could be anything
    max_conn: u32,       // Could be 0 or negative logic
    pool_size: u16,      // Same type as port!
) { }

// Compiler can't help you here:
configure(
    30,      // Meant to be timeout, passed as port!
    8080,    // Meant to be port, passed as timeout!
    0,       // Invalid but compiles!
    100,
);
}

The Solution: Newtype Pattern:

#![allow(unused)]
fn main() {
struct Port(u16);
struct Timeout(Duration);
struct MaxConnections(NonZeroU32);
struct PoolSize(NonZeroU16);

fn configure(
    port: Port,
    timeout: Timeout,
    max_conn: MaxConnections,
    pool_size: PoolSize,
) { }

// Now this won't compile!
configure(
    Timeout::from_secs(30),  // ❌ Expected Port, got Timeout
    Port::new(8080).unwrap(), // ❌ Expected Timeout, got Port
    ...
);
}

What We’re Building:

Four newtype wrappers with validation:

1. Hostname(String): Type-safe string that’s specifically a hostname
2. Port(u16): Validated port number (1-65535)
3. Timeout(Duration): Positive duration with clear units
4. MaxConnections(NonZeroU32): Guaranteed positive connection limit

The Validation Strategy:

Each newtype implements validation in its constructor:

#![allow(unused)]
fn main() {
impl Port {
    fn new(port: u16) -> Result<Self, String> {
        // Range check
        if port == 0 {
            return Err("Port must be > 0".to_string());
        }
        Ok(Port(port))
    }
}
}

Key Design Principle: Parse, Don’t Validate:

Once a value is wrapped in a newtype, it’s guaranteed valid. No need to re-check:

#![allow(unused)]
fn main() {
fn start_server(port: Port) {
    // No need to check if port > 0
    // Type system guarantees it!
    let socket = TcpListener::bind(("0.0.0.0", port.get())).unwrap();
}
}

Starter Code:

#![allow(unused)]
fn main() {
use std::fmt;
use std::num::NonZeroU32;
use std::time::Duration;

// Hostname: Newtype wrapper for server hostname
// Role: Prevents mixing hostname strings with other string types
#[derive(Debug, Clone, PartialEq)]
struct Hostname(String);  // Inner field: the hostname string value

// Port: Newtype wrapper for TCP port numbers with validation
// Role: Ensures port is always valid (1-65535), prevents mixing with other integers
#[derive(Debug, Clone, Copy, PartialEq)]
struct Port(u16);  // Inner field: validated port number

impl Port {
    // new: Smart constructor that validates port range
    // Role: Ensures only valid ports can be created
    fn new(port: u16) -> Result<Self, String> {
        // TODO: Validate port is in range 1..=65535
        // Hint: Check port > 0, return Ok(Port(port)) or Err with message
        todo!()
    }

    // get: Accessor for inner port value
    // Role: Extracts the raw u16 port number
    fn get(&self) -> u16 {
        // TODO: Return the inner u16 value
        todo!()
    }
}

// Timeout: Newtype wrapper for timeout durations
// Role: Enforces timeout is positive duration, prevents mixing raw numbers
#[derive(Debug, Clone, Copy, PartialEq)]
struct Timeout(Duration);  // Inner field: std::time::Duration value

impl Timeout {
    // from_secs: Constructor that creates timeout from seconds
    // Role: Validates positive timeout and wraps in Duration type
    fn from_secs(secs: u64) -> Result<Self, String> {
        // TODO: Validate secs > 0, wrap in Duration
        // Hint: Duration::from_secs(secs)
        todo!()
    }

    // as_duration: Accessor for inner Duration
    // Role: Provides access to underlying Duration for time operations
    fn as_duration(&self) -> Duration {
        // TODO: Return inner Duration
        todo!()
    }
}

// MaxConnections: Newtype wrapper for connection limits using NonZeroU32
// Role: Guarantees connection limit is always positive (can't be zero)
#[derive(Debug, Clone, Copy, PartialEq)]
struct MaxConnections(NonZeroU32);  // Inner field: guaranteed non-zero value

impl MaxConnections {
    // new: Smart constructor that ensures non-zero connection count
    // Role: Validates and creates non-zero connection limit
    fn new(count: u32) -> Result<Self, String> {
        // TODO: Convert to NonZeroU32, handle zero case
        // Hint: NonZeroU32::new(count).ok_or_else(|| "count must be > 0")
        todo!()
    }

    // get: Accessor for inner connection count
    // Role: Extracts the raw u32 value (guaranteed non-zero)
    fn get(&self) -> u32 {
        // TODO: Return inner value as u32
        // Hint: self.0.get()
        todo!()
    }
}

// ServerConfig: Updated configuration using type-safe newtypes
// Role: Groups validated, type-safe configuration parameters
#[derive(Debug, Clone)]
struct ServerConfig {
    host: Hostname,                   // Type-safe hostname
    port: Port,                       // Validated port number
    timeout: Timeout,                 // Validated timeout duration
    max_connections: MaxConnections,  // Guaranteed positive connection limit
}

impl ServerConfig {
    // new: Constructor accepting only validated newtype values
    // Role: Creates config from type-safe components (no validation needed here)
    fn new(
        host: Hostname,
        port: Port,
        timeout: Timeout,
        max_connections: MaxConnections,
    ) -> Self {
        // TODO: Create ServerConfig with newtype fields
        todo!()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_port_validation() {
    assert!(Port::new(8080).is_ok());
    assert!(Port::new(0).is_err());  // Invalid port
    assert!(Port::new(65535).is_ok()); // Max valid port
}

#[test]
fn test_cannot_swap_types() {
    // This won't compile - demonstrates type safety!
    // let port = Port::new(8080).unwrap();
    // let host = Hostname("localhost".to_string());
    // let config = ServerConfig::new(port, host, ...); // ❌ Type error!
}

#[test]
fn test_timeout_validation() {
    assert!(Timeout::from_secs(30).is_ok());
    assert!(Timeout::from_secs(0).is_err()); // Zero timeout invalid
}

#[test]
fn test_max_connections() {
    assert!(MaxConnections::new(100).is_ok());
    assert!(MaxConnections::new(0).is_err()); // Zero connections invalid
}

#[test]
fn test_valid_config() {
    let config = ServerConfig::new(
        Hostname("localhost".to_string()),
        Port::new(8080).unwrap(),
        Timeout::from_secs(30).unwrap(),
        MaxConnections::new(100).unwrap(),
    );

    assert_eq!(config.port.get(), 8080);
}
}

Check Your Understanding:

• Why can’t you accidentally swap Port and MaxConnections now?
• What happens at compile-time if you try Port::new(8080).unwrap().as_duration()?
• Why use NonZeroU32 instead of validating u32 > 0 manually?
• What’s the memory overhead of these newtypes? (Hint: zero!)

Why Milestone 2 Isn’t Enough

Remaining Issues:

1. Verbose construction: Must call .unwrap() multiple times, lots of Result handling
2. Inflexible: Can’t create config incrementally or with defaults
3. Poor ergonomics: config.port.get() is clunky compared to config.port direct access
4. No validation context: Errors don’t say which field failed

What we’re adding:

• Builder pattern: Fluent API for constructing config step-by-step
• Default values: Reasonable defaults for optional fields
• Better error handling: Collect all validation errors, not just first one
• Deref implementation: Transparent access to inner values

Improvements:

• Ergonomics: config.port instead of config.port.get() via Deref
• Flexibility: ServerConfig::builder().port(8080).timeout_secs(30).build()
• Better errors: “Invalid port: 0, Invalid timeout: 0” (all errors at once)
• Defaults: Can omit optional fields, builder provides sensible defaults

Milestone 3: Builder Pattern with Defaults

Goal: Create a fluent builder API that makes construction ergonomic, provides sensible defaults, and collects all validation errors at once.

Why This Milestone Matters:

The Ergonomics Problem:

#![allow(unused)]
fn main() {
// Milestone 2 API - verbose and error-prone
let config = ServerConfig::new(
    Hostname("localhost".to_string()),
    Port::new(8080).unwrap(),  // Panic if invalid!
    Timeout::from_secs(30).unwrap(),
    MaxConnections::new(100).unwrap(),
);
}

Problems:

1. Verbose: Many function calls, lots of .unwrap()
2. Panic-prone: .unwrap() panics on invalid input
3. No defaults: Must specify every field explicitly
4. Error handling: First error stops construction, others ignored

The Builder Solution:

#![allow(unused)]
fn main() {
// Milestone 3 API - fluent and safe
let config = ServerConfig::builder()
    .host("localhost")          // Strings auto-converted
    .port(8080)                 // Validation deferred
    .timeout_secs(30)
    .max_connections(100)
    .build()?;                  // All errors reported at once

// With defaults
let config = ServerConfig::builder()
    .host("localhost")
    .build()?;  // Uses default port, timeout, max_connections
}

What We’re Building:

Three key components:

1. ServerConfigBuilder: Collects configuration values with Option fields
2. Fluent methods: Each method returns self for chaining
3. build() method: Validates everything, applies defaults, returns Result

The Builder Pattern Structure:

#![allow(unused)]
fn main() {
struct ServerConfigBuilder {
    host: Option<String>,        // Not built yet
    port: Option<u16>,          // Raw value, not validated
    timeout_secs: Option<u64>,
    max_connections: Option<u32>,
}

impl ServerConfigBuilder {
    fn new() -> Self {
        ServerConfigBuilder {
            host: None,
            port: None,
            timeout_secs: None,
            max_connections: None,
        }
    }

    fn host(mut self, host: impl Into<String>) -> Self {
        self.host = Some(host.into());
        self  // Return self for chaining!
    }

    fn build(self) -> Result<ServerConfig, Vec<String>> {
        // Validate everything here
    }
}
}

Why Take self Not &mut self?

This is a subtle but important design choice:

#![allow(unused)]
fn main() {
// With &mut self (mutable reference)
fn port(&mut self, port: u16) -> &mut Self {
    self.port = Some(port);
    self
}

// Usage - less ergonomic
let mut builder = ServerConfig::builder();
builder.port(8080).timeout_secs(30);

// With self (consuming)
fn port(mut self, port: u16) -> Self {
    self.port = Some(port);
    self
}

// Usage - more ergonomic
let config = ServerConfig::builder()
    .port(8080)      // Consumes and returns new builder
    .timeout_secs(30)  // Chains naturally
    .build();
}

Taking self by value prevents reuse of partially-built builders, which is usually what you want.

The Power of impl Into<String>:

#![allow(unused)]
fn main() {
fn host(mut self, host: impl Into<String>) -> Self {
    self.host = Some(host.into());
    self
}
}

This accepts any type that can be converted to String:

• &str: builder.host("localhost")
• String: builder.host(hostname_variable)
• Cow<str>: builder.host(cow_string)

More flexible than host: String, which requires .to_string() everywhere!

Validation Strategy: Collect All Errors:

#![allow(unused)]
fn main() {
fn build(self) -> Result<ServerConfig, Vec<String>> {
    let mut errors = Vec::new();

    // Validate host
    let host = match self.host {
        Some(h) if !h.is_empty() => Hostname(h),
        Some(_) => {
            errors.push("Host cannot be empty".to_string());
            Hostname("localhost".to_string())  // Placeholder
        }
        None => {
            errors.push("Host is required".to_string());
            Hostname("localhost".to_string())
        }
    };

    // Validate port (with default)
    let port = match self.port {
        Some(p) => match Port::new(p) {
            Ok(port) => port,
            Err(e) => {
                errors.push(format!("Invalid port: {}", e));
                Port::new(8080).unwrap()  // Safe default
            }
        },
        None => Port::new(8080).unwrap(),  // Default
    };

    // ... similar for other fields ...

    if !errors.is_empty() {
        Err(errors)  // Return ALL errors
    } else {
        Ok(ServerConfig::new(host, port, timeout, max_connections))
    }
}
}

Why Collect All Errors?

Bad UX (stop on first error):

❌ Port must be greater than 0

Fix it, run again...

❌ Timeout must be greater than 0 seconds

Fix it, run again...

❌ Connection count must be greater than 0

Good UX (report all errors):

❌ Multiple validation errors:
  - Port must be greater than 0
  - Timeout must be greater than 0 seconds
  - Connection count must be greater than 0

Fix all three at once!

The Deref Trait for Ergonomics:

#![allow(unused)]
fn main() {
impl Deref for Port {
    type Target = u16;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}
}

Now you can use Port almost like a u16:

#![allow(unused)]
fn main() {
let port = Port::new(8080).unwrap();

// Without Deref
println!("Port: {}", port.get());

// With Deref
println!("Port: {}", *port);  // Dereference to u16

// Even auto-derefs in many contexts
if port > 1024 {  // Auto-derefs to u16 for comparison!
    println!("Unprivileged port");
}
}

When to Use Deref:

✅ Good use cases:

• Newtypes wrapping a single value
• Want transparent access to inner value
• Inner value is “the essence” of the type

❌ Avoid Deref when:

• Type has additional semantics beyond the wrapped value
• Deref would expose internal implementation details
• Want to prevent confusion with the inner type

Default Values Design:

#![allow(unused)]
fn main() {
// Required fields: None = error
let host = match self.host {
    Some(h) => h,
    None => {
        errors.push("Host is required".to_string());
        "localhost".to_string()  // Placeholder for error path
    }
};

// Optional fields: None = default
let port = match self.port {
    Some(p) => Port::new(p)?,
    None => Port::new(8080).unwrap(),  // Sensible default
};
}

Real-World Builder Examples:

1. reqwest::Client: HTTP client builder

   #![allow(unused)]
   fn main() {
   let client = Client::builder()
       .timeout(Duration::from_secs(10))
       .gzip(true)
       .build()?;
   }

2. tokio::Runtime: Async runtime builder

   #![allow(unused)]
   fn main() {
   let runtime = Runtime::builder()
       .worker_threads(4)
       .thread_name("my-pool")
       .build()?;
   }

3. AWS SDK: Service client builders

   #![allow(unused)]
   fn main() {
   let client = S3Client::builder()
       .region(Region::new("us-east-1"))
       .credentials_provider(provider)
       .build();
   }

Type State Builder (Advanced):

You can even use the typestate pattern on builders to enforce “host must be set before build”:

#![allow(unused)]
fn main() {
struct NoHost;
struct HasHost;

struct ServerConfigBuilder<State> {
    host: Option<String>,
    _state: PhantomData<State>,
}

impl ServerConfigBuilder<NoHost> {
    fn host(self, host: impl Into<String>) -> ServerConfigBuilder<HasHost> {
        // Returns different type!
    }
}

impl ServerConfigBuilder<HasHost> {
    fn build(self) -> Result<ServerConfig, Vec<String>> {
        // Only callable after host() was called!
    }
}
}

Starter Code:

#![allow(unused)]
fn main() {
use std::ops::Deref;

// Deref implementation for Port
// Role: Allows transparent access to inner u16 value using * operator
impl Deref for Port {
    type Target = u16;  // Dereferencing produces a &u16

    // deref: Provides reference to inner value
    // Role: Enables ergonomic access like *port instead of port.get()
    fn deref(&self) -> &Self::Target {
        // TODO: Return reference to inner u16
        todo!()
    }
}

// TODO: Implement Deref for other newtypes similarly (Timeout, MaxConnections)

// ServerConfigBuilder: Fluent builder for constructing ServerConfig
// Role: Collects configuration values step-by-step with validation and defaults
struct ServerConfigBuilder {
    host: Option<String>,        // Optional hostname (required field)
    port: Option<u16>,          // Optional port (defaults to 8080)
    timeout_secs: Option<u64>,  // Optional timeout (defaults to 30 seconds)
    max_connections: Option<u32>, // Optional connection limit (defaults to 100)
}

impl ServerConfigBuilder {
    // new: Creates empty builder
    // Role: Initializes all fields to None, ready for configuration
    fn new() -> Self {
        // TODO: Create builder with all None values
        todo!()
    }

    // host: Sets hostname in builder
    // Role: Accepts any type convertible to String for flexibility
    fn host(mut self, host: impl Into<String>) -> Self {
        // TODO: Set host field and return self for chaining
        // Hint: self.host = Some(host.into()); self
        todo!()
    }

    // port: Sets port number in builder
    // Role: Stores port for later validation during build()
    fn port(mut self, port: u16) -> Self {
        // TODO: Set port and return self
        todo!()
    }

    // timeout_secs: Sets timeout duration in seconds
    // Role: Stores timeout for validation and Duration conversion during build()
    fn timeout_secs(mut self, secs: u64) -> Self {
        // TODO: Set timeout_secs and return self
        todo!()
    }

    // max_connections: Sets maximum connection limit
    // Role: Stores connection limit for validation during build()
    fn max_connections(mut self, max: u32) -> Self {
        // TODO: Set max_connections and return self
        todo!()
    }

    // build: Validates all fields and constructs ServerConfig
    // Role: Applies defaults, validates all values, collects all errors
    fn build(self) -> Result<ServerConfig, Vec<String>> {
        let mut errors = Vec::new();

        // Validate and extract host, or add error
        let host = match self.host {
            Some(h) if !h.is_empty() => Hostname(h),
            Some(_) => {
                errors.push("Host cannot be empty".to_string());
                Hostname("localhost".to_string()) // Placeholder
            }
            None => {
                errors.push("Host is required".to_string());
                Hostname("localhost".to_string())
            }
        };

        // Validate port or use default 8080
        let port = match self.port {
            Some(p) => match Port::new(p) {
                Ok(port) => port,
                Err(e) => {
                    errors.push(format!("Invalid port: {}", e));
                    Port::new(8080).unwrap() // Safe default
                }
            },
            None => Port::new(8080).unwrap(), // Default
        };

        // TODO: Similar for timeout (default 30s)
        let timeout = todo!();

        // TODO: Similar for max_connections (default 100)
        let max_connections = todo!();

        // If errors, return Err(errors), else Ok(config)
        // Role: Reports all validation errors at once, or returns valid config
        if !errors.is_empty() {
            Err(errors)
        } else {
            Ok(ServerConfig::new(host, port, timeout, max_connections))
        }
    }
}

impl ServerConfig {
    // builder: Entry point for fluent configuration API
    // Role: Creates new builder instance to start configuration chain
    fn builder() -> ServerConfigBuilder {
        ServerConfigBuilder::new()
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[test]
fn test_builder_fluent_api() {
    let config = ServerConfig::builder()
        .host("localhost")
        .port(8080)
        .timeout_secs(30)
        .max_connections(100)
        .build()
        .unwrap();

    assert_eq!(*config.port, 8080); // Deref in action
}

#[test]
fn test_builder_defaults() {
    let config = ServerConfig::builder()
        .host("localhost")
        .build()
        .unwrap();

    // Should use default values
    assert_eq!(*config.port, 8080);
    assert_eq!(*config.max_connections, 100);
}

#[test]
fn test_builder_validation_errors() {
    let result = ServerConfig::builder()
        .port(0)  // Invalid
        .timeout_secs(0)  // Invalid
        .build();

    assert!(result.is_err());
    let errors = result.unwrap_err();
    assert!(errors.len() >= 2); // At least port and timeout errors
}

#[test]
fn test_builder_missing_required() {
    let result = ServerConfig::builder()
        .port(8080)
        .build();

    assert!(result.is_err());
    let errors = result.unwrap_err();
    assert!(errors.iter().any(|e| e.contains("Host")));
}
}

Check Your Understanding:

• How does Deref allow *config.port to work?
• Why return Self from builder methods instead of &mut Self?
• What’s the benefit of collecting all errors vs returning on first error?
• How does impl Into<String> make the API more flexible?

Complete Project Summary

What You Built:

1. Basic configuration struct with named fields
2. Newtype wrappers for type safety and validation
3. Fluent builder API with defaults and comprehensive error reporting
4. Deref implementation for ergonomic access

Key Concepts Practiced:

• Newtype pattern for compile-time type safety
• Smart constructors with validation
• Builder pattern for ergonomic APIs
• Deref trait for transparent access
• Collecting multiple validation errors

Real-World Application: This pattern is used in:

• AWS SDK configuration builders
• HTTP client configuration (reqwest, hyper)
• Database connection configuration
• Server/application configuration libraries

Complete Working Example

// Complete Type-Safe Configuration System

use std::num::NonZeroU32;
use std::ops::Deref;
use std::time::Duration;

//==============================================================================
// Milestone 1: Basic Configuration Struct
//==============================================================================

/// BasicServerConfig: Simple configuration struct without type safety
/// Demonstrates the problems with using primitive types directly
#[derive(Debug, Clone)]
#[allow(dead_code)]
struct BasicServerConfig {
    host: String,
    port: u16,
    timeout_seconds: u64,
    max_connections: u32,
}

impl BasicServerConfig {
    /// Creates a basic config - allows invalid values!
    #[allow(dead_code)]
    fn new(host: String, port: u16, timeout_seconds: u64, max_connections: u32) -> Self {
        BasicServerConfig {
            host,
            port,
            timeout_seconds,
            max_connections,
        }
    }
}

//==============================================================================
// Milestone 2: Newtype Wrappers for Type Safety
//==============================================================================

/// Hostname: Type-safe wrapper for server hostname
/// Prevents mixing hostname strings with other string types
#[derive(Debug, Clone, PartialEq)]
struct Hostname(String);

impl Hostname {
    #[allow(dead_code)]
    fn new(hostname: String) -> Self {
        Hostname(hostname)
    }

    fn as_str(&self) -> &str {
        &self.0
    }
}

/// Port: Validated TCP port number (1-65535)
/// Prevents invalid port values at compile time
#[derive(Debug, Clone, Copy, PartialEq)]
struct Port(u16);

impl Port {
    /// Smart constructor that validates port range
    fn new(port: u16) -> Result<Self, String> {
        if port == 0 {
            Err("Port must be greater than 0".to_string())
        } else {
            Ok(Port(port))
        }
    }

    #[allow(dead_code)]
    fn get(&self) -> u16 {
        self.0
    }
}

impl Deref for Port {
    type Target = u16;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

/// Timeout: Validated timeout duration
/// Ensures timeout is positive and has clear units (Duration)
#[derive(Debug, Clone, Copy, PartialEq)]
struct Timeout(Duration);

impl Timeout {
    /// Smart constructor that validates positive timeout
    fn from_secs(secs: u64) -> Result<Self, String> {
        if secs == 0 {
            Err("Timeout must be greater than 0 seconds".to_string())
        } else {
            Ok(Timeout(Duration::from_secs(secs)))
        }
    }

    fn as_duration(&self) -> Duration {
        self.0
    }
}

impl Deref for Timeout {
    type Target = Duration;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

/// MaxConnections: Guaranteed non-zero connection limit
/// Uses NonZeroU32 for additional niche optimization
#[derive(Debug, Clone, Copy, PartialEq)]
struct MaxConnections(NonZeroU32);

impl MaxConnections {
    /// Smart constructor that ensures non-zero count
    fn new(count: u32) -> Result<Self, String> {
        NonZeroU32::new(count)
            .map(MaxConnections)
            .ok_or_else(|| "Connection count must be greater than 0".to_string())
    }

    fn get(&self) -> u32 {
        self.0.get()
    }
}

impl Deref for MaxConnections {
    type Target = NonZeroU32;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

//==============================================================================
// ServerConfig: Type-Safe Configuration
//==============================================================================

/// ServerConfig: Main configuration struct using type-safe newtypes
/// All fields are validated at construction time
#[derive(Debug, Clone)]
struct ServerConfig {
    host: Hostname,
    port: Port,
    timeout: Timeout,
    max_connections: MaxConnections,
}

impl ServerConfig {
    /// Creates a new ServerConfig from validated newtypes
    fn new(
        host: Hostname,
        port: Port,
        timeout: Timeout,
        max_connections: MaxConnections,
    ) -> Self {
        ServerConfig {
            host,
            port,
            timeout,
            max_connections,
        }
    }

    /// Entry point for fluent builder API
    fn builder() -> ServerConfigBuilder {
        ServerConfigBuilder::new()
    }
}

//==============================================================================
// Milestone 3: Builder Pattern with Defaults
//==============================================================================

/// ServerConfigBuilder: Fluent builder for constructing ServerConfig
/// Collects configuration values step-by-step with validation and defaults
struct ServerConfigBuilder {
    host: Option<String>,
    port: Option<u16>,
    timeout_secs: Option<u64>,
    max_connections: Option<u32>,
}

impl ServerConfigBuilder {
    /// Creates empty builder with all fields None
    fn new() -> Self {
        ServerConfigBuilder {
            host: None,
            port: None,
            timeout_secs: None,
            max_connections: None,
        }
    }

    /// Sets hostname (required field)
    fn host(mut self, host: impl Into<String>) -> Self {
        self.host = Some(host.into());
        self
    }

    /// Sets port number (defaults to 8080 if not specified)
    fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }

    /// Sets timeout in seconds (defaults to 30 if not specified)
    fn timeout_secs(mut self, secs: u64) -> Self {
        self.timeout_secs = Some(secs);
        self
    }

    /// Sets maximum connections (defaults to 100 if not specified)
    fn max_connections(mut self, max: u32) -> Self {
        self.max_connections = Some(max);
        self
    }

    /// Validates all fields and constructs ServerConfig
    /// Collects ALL validation errors, not just the first one
    fn build(self) -> Result<ServerConfig, Vec<String>> {
        let mut errors = Vec::new();

        // Validate hostname (required field)
        let host = match self.host {
            Some(h) if !h.is_empty() => Hostname(h),
            Some(_) => {
                errors.push("Host cannot be empty".to_string());
                Hostname("localhost".to_string()) // Placeholder for error path
            }
            None => {
                errors.push("Host is required".to_string());
                Hostname("localhost".to_string())
            }
        };

        // Validate port with default 8080
        let port = match self.port {
            Some(p) => match Port::new(p) {
                Ok(port) => port,
                Err(e) => {
                    errors.push(format!("Invalid port: {}", e));
                    Port::new(8080).unwrap() // Safe default
                }
            },
            None => Port::new(8080).unwrap(), // Default
        };

        // Validate timeout with default 30 seconds
        let timeout = match self.timeout_secs {
            Some(secs) => match Timeout::from_secs(secs) {
                Ok(timeout) => timeout,
                Err(e) => {
                    errors.push(format!("Invalid timeout: {}", e));
                    Timeout::from_secs(30).unwrap()
                }
            },
            None => Timeout::from_secs(30).unwrap(),
        };

        // Validate max_connections with default 100
        let max_connections = match self.max_connections {
            Some(max) => match MaxConnections::new(max) {
                Ok(mc) => mc,
                Err(e) => {
                    errors.push(format!("Invalid max_connections: {}", e));
                    MaxConnections::new(100).unwrap()
                }
            },
            None => MaxConnections::new(100).unwrap(),
        };

        // Return all errors or valid config
        if !errors.is_empty() {
            Err(errors)
        } else {
            Ok(ServerConfig::new(host, port, timeout, max_connections))
        }
    }
}

//==============================================================================
// Example Usage and Main
//==============================================================================

fn main() {
    println!("=== Type-Safe Configuration System ===\n");

    // Example 1: Using builder with all fields
    println!("Example 1: Complete configuration");
    let config = ServerConfig::builder()
        .host("0.0.0.0")
        .port(8080)
        .timeout_secs(30)
        .max_connections(100)
        .build()
        .unwrap();

    println!("Config: {:?}", config);
    println!("  Host: {}", config.host.as_str());
    println!("  Port: {}", *config.port); // Deref in action!
    println!("  Timeout: {:?}", config.timeout.as_duration());
    println!("  Max connections: {}", config.max_connections.get());
    println!();

    // Example 2: Using builder with defaults
    println!("Example 2: Using defaults");
    let config2 = ServerConfig::builder()
        .host("localhost")
        .build()
        .unwrap();

    println!("Config with defaults: {:?}", config2);
    println!("  Default port: {}", *config2.port);
    println!("  Default timeout: {:?}", config2.timeout.as_duration());
    println!("  Default max_connections: {}", config2.max_connections.get());
    println!();

    // Example 3: Handling validation errors
    println!("Example 3: Validation errors (collected all at once)");
    let result = ServerConfig::builder()
        .port(0) // Invalid!
        .timeout_secs(0) // Invalid!
        .max_connections(0) // Invalid!
        .build();

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(errors) => {
            println!("Validation errors:");
            for error in errors {
                println!("  - {}", error);
            }
        }
    }
    println!();

    // Example 4: Type safety demonstration
    println!("Example 4: Type safety prevents mistakes");
    let port = Port::new(8080).unwrap();
    let timeout = Timeout::from_secs(30).unwrap();

    println!("Created port: {}", *port);
    println!("Created timeout: {:?}", *timeout);

    // This won't compile - type safety!
    // let bad_config = ServerConfig::new(
    //     Hostname("localhost".to_string()),
    //     timeout,  // ❌ Wrong type! Expected Port, got Timeout
    //     port,     // ❌ Wrong type! Expected Timeout, got Port
    //     MaxConnections::new(100).unwrap(),
    // );
    println!("(Compiler prevents mixing up types at compile time!)");
    println!();

    // Example 5: Milestone 1 comparison
    println!("Example 5: Why Milestone 1 isn't enough");
    let basic = BasicServerConfig::new(
        "".to_string(), // Empty host - invalid!
        0,              // Invalid port!
        0,              // Zero timeout!
        0,              // Zero connections!
    );
    println!(
        "BasicServerConfig allows invalid values: port={}, timeout={}, max_conn={}",
        basic.port, basic.timeout_seconds, basic.max_connections
    );
    println!("(No compile-time or runtime validation!)");
    println!();

    // Example 6: Deref trait demonstration
    println!("Example 6: Deref trait for ergonomic access");
    let port = Port::new(8080).unwrap();
    println!("Port value: {}", *port); // Deref to u16
    if *port > 1024 {
        println!("Unprivileged port (> 1024)");
    }

    let timeout = Timeout::from_secs(30).unwrap();
    println!("Timeout: {} seconds", timeout.as_secs()); // Deref to Duration
}

//==============================================================================
// Tests
//==============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // Milestone 1 Tests
    #[test]
    fn test_basic_config() {
        let config = BasicServerConfig::new("localhost".to_string(), 8080, 30, 100);

        assert_eq!(config.host, "localhost");
        assert_eq!(config.port, 8080);
        assert_eq!(config.timeout_seconds, 30);
        assert_eq!(config.max_connections, 100);
    }

    #[test]
    fn test_can_create_invalid_config() {
        // This compiles but is semantically wrong!
        let bad_config = BasicServerConfig::new("".to_string(), 0, 0, 0);

        // No way to prevent this at compile time
        assert_eq!(bad_config.port, 0);
        assert_eq!(bad_config.timeout_seconds, 0);
    }

    // Milestone 2 Tests
    #[test]
    fn test_port_validation() {
        assert!(Port::new(8080).is_ok());
        assert!(Port::new(1).is_ok());
        assert!(Port::new(65535).is_ok());
        assert!(Port::new(0).is_err()); // Invalid port
    }

    #[test]
    fn test_timeout_validation() {
        assert!(Timeout::from_secs(30).is_ok());
        assert!(Timeout::from_secs(1).is_ok());
        assert!(Timeout::from_secs(0).is_err()); // Zero timeout invalid
    }

    #[test]
    fn test_max_connections() {
        assert!(MaxConnections::new(100).is_ok());
        assert!(MaxConnections::new(1).is_ok());
        assert!(MaxConnections::new(0).is_err()); // Zero connections invalid
    }

    #[test]
    fn test_valid_config() {
        let config = ServerConfig::new(
            Hostname("localhost".to_string()),
            Port::new(8080).unwrap(),
            Timeout::from_secs(30).unwrap(),
            MaxConnections::new(100).unwrap(),
        );

        assert_eq!(config.port.get(), 8080);
        assert_eq!(config.timeout.as_duration().as_secs(), 30);
        assert_eq!(config.max_connections.get(), 100);
    }

    #[test]
    fn test_newtype_validation() {
        assert!(Port::new(8080).is_ok());
        assert!(Port::new(0).is_err());
        assert!(Timeout::from_secs(30).is_ok());
        assert!(Timeout::from_secs(0).is_err());
        assert!(MaxConnections::new(100).is_ok());
        assert!(MaxConnections::new(0).is_err());
    }

    // Milestone 3 Tests
    #[test]
    fn test_builder_fluent_api() {
        let config = ServerConfig::builder()
            .host("localhost")
            .port(8080)
            .timeout_secs(30)
            .max_connections(100)
            .build()
            .unwrap();

        assert_eq!(*config.port, 8080); // Deref in action
        assert_eq!(config.timeout.as_duration().as_secs(), 30);
        assert_eq!(config.max_connections.get(), 100);
    }

    #[test]
    fn test_builder_defaults() {
        let config = ServerConfig::builder().host("localhost").build().unwrap();

        // Should use default values
        assert_eq!(*config.port, 8080);
        assert_eq!(config.timeout.as_duration().as_secs(), 30);
        assert_eq!(config.max_connections.get(), 100);
    }

    #[test]
    fn test_builder_validation_errors() {
        let result = ServerConfig::builder()
            .port(0) // Invalid
            .timeout_secs(0) // Invalid
            .build();

        assert!(result.is_err());
        let errors = result.unwrap_err();
        assert!(errors.len() >= 2); // At least port and timeout errors
        assert!(errors.iter().any(|e| e.contains("port")));
        assert!(errors.iter().any(|e| e.contains("timeout")));
    }

    #[test]
    fn test_builder_missing_required() {
        let result = ServerConfig::builder().port(8080).build();

        assert!(result.is_err());
        let errors = result.unwrap_err();
        assert!(errors.iter().any(|e| e.contains("Host")));
    }

    #[test]
    fn test_builder_empty_host() {
        let result = ServerConfig::builder().host("").build();

        assert!(result.is_err());
        let errors = result.unwrap_err();
        assert!(errors.iter().any(|e| e.contains("empty")));
    }

    #[test]
    fn test_builder_success() {
        let config = ServerConfig::builder()
            .host("localhost")
            .port(8080)
            .timeout_secs(30)
            .max_connections(100)
            .build();

        assert!(config.is_ok());
    }

    #[test]
    fn test_builder_multiple_errors() {
        let result = ServerConfig::builder()
            .port(0) // Invalid
            .timeout_secs(0) // Invalid
            .max_connections(0) // Invalid
            .build();

        assert!(result.is_err());
        let errors = result.unwrap_err();
        // Should have at least 4 errors: missing host, invalid port, timeout, max_connections
        assert!(errors.len() >= 3);
    }

    #[test]
    fn test_deref_trait() {
        let port = Port::new(8080).unwrap();
        assert_eq!(*port, 8080);

        let timeout = Timeout::from_secs(30).unwrap();
        assert_eq!(timeout.as_secs(), 30);

        let max_conn = MaxConnections::new(100).unwrap();
        assert_eq!(max_conn.get(), 100);
    }

    #[test]
    fn test_port_deref_comparison() {
        let port = Port::new(8080).unwrap();
        // Explicit deref for comparison
        assert!(*port > 1024);
        assert!(*port < 65535);
    }

    #[test]
    fn test_nonzero_u32_size_optimization() {
        use std::mem::size_of;

        // Niche optimization: Option<NonZeroU32> is same size as NonZeroU32
        assert_eq!(size_of::<NonZeroU32>(), size_of::<Option<NonZeroU32>>());

        // Regular u32 needs extra space for Option discriminant
        assert!(size_of::<u32>() < size_of::<Option<u32>>());
    }

    #[test]
    fn test_builder_with_string_types() {
        // Test that builder accepts &str, String, etc.
        let config1 = ServerConfig::builder().host("localhost").build().unwrap();
        assert_eq!(config1.host.as_str(), "localhost");

        let hostname = String::from("example.com");
        let config2 = ServerConfig::builder().host(hostname).build().unwrap();
        assert_eq!(config2.host.as_str(), "example.com");
    }

    #[test]
    fn test_zero_cost_abstraction() {
        use std::mem::size_of;

        // Newtypes have no runtime overhead
        assert_eq!(size_of::<Port>(), size_of::<u16>());
        assert_eq!(size_of::<Timeout>(), size_of::<Duration>());
        assert_eq!(size_of::<MaxConnections>(), size_of::<NonZeroU32>());
    }

    #[test]
    fn test_config_clone() {
        let config = ServerConfig::builder()
            .host("localhost")
            .port(8080)
            .build()
            .unwrap();

        let config2 = config.clone();
        assert_eq!(*config.port, *config2.port);
        assert_eq!(config.host.as_str(), config2.host.as_str());
    }
}

Streaming Iterator with HRTB

Problem Statement

Build a streaming iterator that yields borrowed elements with complex lifetime requirements using Higher-Ranked Trait Bounds (HRTB) and Generic Associated Types (GATs). Unlike standard Iterator which returns owned items, streaming iterators return items that borrow from the iterator itself, enabling zero-copy iteration over streaming data.

Performance Impact:

• Standard Iterator: Must allocate/copy for each item (50-100ns per item)
• Streaming Iterator: Zero-copy borrowing (1-2ns per item)
• 10-100x faster for large datasets
• Memory efficiency: No heap allocation, better cache locality

Understanding Streaming Iterators and Advanced Lifetimes

Before implementing streaming iterators, let’s understand the fundamental concepts of Generic Associated Types (GATs), Higher-Ranked Trait Bounds (HRTBs), and advanced lifetime patterns that make zero-copy iteration possible.

Why Standard Iterator Is Limited

The standard Iterator trait has a fundamental limitation: items cannot borrow from the iterator.

Standard Iterator Trait:

#![allow(unused)]
fn main() {
trait Iterator {
    type Item;  // Associated type, NO lifetime parameter
    fn next(&mut self) -> Option<Self::Item>;
}
}

The Problem:

#![allow(unused)]
fn main() {
struct WindowIterator {
    data: Vec<i32>,
    position: usize,
}

// ❌ Can't implement Iterator to return &[i32]
impl Iterator for WindowIterator {
    type Item = &[i32];  // ERROR: Missing lifetime parameter!
    //          ↑ What lifetime? Can't refer to 'self lifetime here!

    fn next(&mut self) -> Option<Self::Item> {
        // Want to return slice borrowing from self.data
        // But Item can't have a lifetime parameter!
    }
}
}

Why This Fails:

#![allow(unused)]
fn main() {
// Let's try adding a lifetime:
impl<'a> Iterator for WindowIterator<'a> {
    type Item = &'a [i32];  // 'a is from the struct

    fn next(&mut self) -> Option<Self::Item> {
        // Problem: 'a is FIXED when WindowIterator is created
        // But next() is called MULTIPLE times with DIFFERENT &mut self lifetimes!
        // Each call has a fresh lifetime that doesn't relate to 'a
        Some(&self.data[self.position..])  // ERROR: lifetime mismatch
    }
}

// Each next() call has its own lifetime:
let mut iter = WindowIterator { data: vec![1,2,3], position: 0 };
let window1 = iter.next(); // Lifetime 'call1
let window2 = iter.next(); // Lifetime 'call2 (DIFFERENT!)

// 'a can't be both 'call1 and 'call2 - it's fixed!
}

The Core Issue: Item is an associated type, not a type constructor. It can’t be parameterized by the lifetime of each next() call.

Generic Associated Types (GATs): The Solution

Generic Associated Types (GATs) allow associated types to have generic parameters, including lifetimes.

Enabled in Rust 1.65+, GATs are one of the most powerful type system features.

Streaming Iterator with GAT:

#![allow(unused)]
fn main() {
trait StreamingIterator {
    type Item<'a> where Self: 'a;  // ← GAT! Item is now a type constructor
    //          ↑ Takes a lifetime parameter

    fn next(&mut self) -> Option<Self::Item<'_>>;
    //                                      ↑ Anonymous lifetime from &mut self
}
}

How This Works:

#![allow(unused)]
fn main() {
impl StreamingIterator for WindowIterator {
    type Item<'a> = &'a [i32] where Self: 'a;
    //       ↑ Type constructor: given lifetime, produces type

    fn next(&mut self) -> Option<Self::Item<'_>> {
        //      ↑ &'a mut self
        // Returns Option<&'a [i32]> - borrows from THIS call's lifetime
        Some(&self.data[self.position..])  // ✓ OK!
    }
}

// Now each call can have its own lifetime:
let mut iter = WindowIterator { data: vec![1,2,3], position: 0 };
let window1 = iter.next(); // Returns Option<&'1 [i32]>
drop(window1);
let window2 = iter.next(); // Returns Option<&'2 [i32]> (fresh lifetime!)
}

Key Insight: Item<'a> is a type constructor (also called type-level function). Given a lifetime 'a, it produces a type &'a [i32].

The where Self: 'a Clause:

#![allow(unused)]
fn main() {
type Item<'a> where Self: 'a;
}

This says: “The lifetime 'a cannot outlive Self”. It’s necessary because:

#![allow(unused)]
fn main() {
// Without where clause:
type Item<'a>; // Could try to return &'a [i32] even if 'a > Self lifetime

// With where clause:
type Item<'a> where Self: 'a;
// Guarantees: Item<'a> can only borrow for as long as Self lives
// Prevents returning references that outlive the iterator
}

Higher-Ranked Trait Bounds (HRTB)

HRTBs allow you to express that a trait must hold for all possible lifetimes, not just one specific lifetime.

The Problem Without HRTB:

#![allow(unused)]
fn main() {
fn process_stream<'a, I, F>(iter: I, f: F)
where
    I: StreamingIterator,
    F: FnMut(I::Item<'a>),  // F works with ONE specific lifetime 'a
{
    while let Some(item) = iter.next() {
        //                 ↑ returns Item<'call>
        // But F expects Item<'a>!
        // These lifetimes don't match!
        f(item);  // ❌ ERROR
    }
}
}

Why This Fails: Each call to next() produces an item with a fresh lifetime, but F is bound to ONE specific lifetime 'a chosen when the function is called.

Solution with HRTB:

#![allow(unused)]
fn main() {
fn process_stream<I, F>(mut iter: I, mut f: F)
where
    I: StreamingIterator,
    F: for<'a> FnMut(I::Item<'a>),  // ← HRTB!
    //  ↑ "for ALL lifetimes 'a"
{
    while let Some(item) = iter.next() {
        // item has lifetime 'call
        // F must work for ANY lifetime, including 'call
        f(item);  // ✓ OK! F works for 'call because it works for ALL lifetimes
    }
}
}

Reading for<'a>: “for all lifetimes 'a” - the trait bound must hold universally, not just for one specific lifetime.

Analogy:

#![allow(unused)]
fn main() {
// Without HRTB: Pick ONE integer
fn takes_one_int<N: Integer>(f: impl Fn(N)) { }
// f works with ONE specific integer type (i32, i64, etc.)

// With HRTB: Works with ALL integers
fn takes_all_ints(f: impl for<N: Integer> Fn(N)) { }
// f works with EVERY integer type
}

Why Needed:

#![allow(unused)]
fn main() {
// Each next() call has different lifetime:
let mut iter = windows(&data, 3);

// Call 1:
let item1 = iter.next(); // item1: Option<&'1 [i32]>
process(item1);

// Call 2:
let item2 = iter.next(); // item2: Option<&'2 [i32]> (different!)
process(item2);

// Closure must work with BOTH '1 and '2 (and all other lifetimes)
// Hence: for<'a> FnMut(Item<'a>)
}

Lifetime Variance

Variance describes how subtyping works with generic parameters.

Three Kinds of Variance:

1. Covariant: If 'long: 'short, then F<'long>: F<'short> (longer lifetime subtypes shorter)
2. Contravariant: If 'long: 'short, then F<'short>: F<'long> (reversed!)
3. Invariant: No subtyping relationship

Shared References are Covariant:

#![allow(unused)]
fn main() {
// &'a T is covariant in both 'a and T

fn covariance_example<'long: 'short, 'short>(long_ref: &'long str) -> &'short str {
    long_ref  // ✓ OK: Can use &'long where &'short expected
    // Because 'long: 'short (long outlives short)
    // And &'a T is covariant in 'a
}

// Real example:
let long_lived = String::from("data");
{
    let short_ref: &str = &long_lived;  // &'long assigned to &'short
    // Covariance allows this!
}
}

Why Covariance is Safe for &T:

• Shared references are read-only
• Returning a longer-lived reference where a shorter-lived one is expected is always safe
• The data lives at least as long as required

Mutable References are Invariant:

#![allow(unused)]
fn main() {
// &'a mut T is invariant in 'a (but covariant in T)

fn invariance_example<'long: 'short, 'short>(
    long_ref: &'long mut str
) -> &'short mut str {
    long_ref  // ❌ ERROR: Can't do this!
    // &'a mut T is invariant in 'a
}
}

Why Invariance is Necessary for &mut T:

#![allow(unused)]
fn main() {
// If &mut was covariant, this would be unsound:
fn unsound_if_covariant() {
    let mut long_lived = String::from("long");
    {
        let short_lived = String::from("short");
        let short_ref: &mut String = &mut short_lived;

        // If covariant (IT'S NOT!), could do:
        // let long_ref: &mut String = &mut long_lived;
        // *short_ref = long_ref;  // Replace short with long

        // short_ref would now point to long_lived
    } // short_lived dropped, but short_ref still exists!
    // Use-after-free!
}
}

Variance Table:

Type              Variance in 'a    Variance in T
&'a T             Covariant         Covariant
&'a mut T         Invariant         Covariant
fn(T) -> U        -                 Contravariant in T, Covariant in U
Cell<T>           -                 Invariant
PhantomData<T>    -                 Covariant
PhantomData<fn(T)> -                Contravariant

Zero-Copy Iteration

The Allocation Problem:

#![allow(unused)]
fn main() {
// Standard iterator approach:
struct WindowIter {
    data: Vec<i32>,
    window_size: usize,
    position: usize,
}

impl Iterator for WindowIter {
    type Item = Vec<i32>;  // Must return OWNED Vec

    fn next(&mut self) -> Option<Vec<i32>> {
        if self.position + self.window_size <= self.data.len() {
            // ALLOCATION: Copy data into new Vec
            let window = self.data[self.position..self.position + self.window_size]
                .to_vec();
            self.position += 1;
            Some(window)
        } else {
            None
        }
    }
}

// For 1000 windows:
// - 1000 heap allocations (~50-100ns each = 50-100µs)
// - 1000 memcpy operations
// - 1000 deallocations
// Total overhead: ~150µs for small windows
}

Streaming Iterator Approach:

#![allow(unused)]
fn main() {
impl StreamingIterator for WindowIter {
    type Item<'a> = &'a [i32] where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        if self.position + self.window_size <= self.data.len() {
            // ZERO-COPY: Just create slice (pointer + length)
            let window = &self.data[self.position..self.position + self.window_size];
            self.position += 1;
            Some(window)  // ~1-2ns (just pointer arithmetic)
        } else {
            None
        }
    }
}

// For 1000 windows:
// - 0 heap allocations
// - 0 memcpy operations
// - Just pointer arithmetic
// Total time: ~2µs
// 75x faster!
}

Memory Comparison:

Standard Iterator Window:
┌───────────────────────────┐
│ Vec<i32>                  │
├───────────────────────────┤
│ ptr: *mut i32             │ 8 bytes
│ len: usize                │ 8 bytes
│ cap: usize                │ 8 bytes
└───────────────────────────┘
        ↓ points to
┌───────────────────────────┐
│ Heap allocation           │
│ [i32; window_size]        │ window_size * 4 bytes
└───────────────────────────┘

Total: 24 bytes + heap allocation + fragmentation

Streaming Iterator Window:
┌───────────────────────────┐
│ &[i32]                    │
├───────────────────────────┤
│ ptr: *const i32           │ 8 bytes
│ len: usize                │ 8 bytes
└───────────────────────────┘
        ↓ points into existing data
┌───────────────────────────┐
│ Original Vec<i32>         │
│ (no additional allocation)│
└───────────────────────────┘

Total: 16 bytes (no heap allocation)

Type Constructors vs Concrete Types

Concrete Type: A type you can create values of

#![allow(unused)]
fn main() {
i32                    // Concrete type
Vec<String>            // Concrete type
&'static str           // Concrete type
}

Type Constructor: A “function” that takes type/lifetime parameters and produces a concrete type

#![allow(unused)]
fn main() {
Vec<T>                 // Type constructor (needs T)
&'a T                  // Type constructor (needs 'a and T)
Option<T>              // Type constructor (needs T)
}

GATs Introduce Type Constructors in Traits:

#![allow(unused)]
fn main() {
trait StreamingIterator {
    type Item<'a> where Self: 'a;  // Type constructor!
    //       ↑ Takes lifetime, returns type
}

// Concrete instance:
impl StreamingIterator for WindowIter {
    type Item<'a> = &'a [i32] where Self: 'a;
    // Item is a type constructor:
    // Item<'call> = &'call [i32]
}
}

Using Type Constructors:

#![allow(unused)]
fn main() {
fn process<I: StreamingIterator>(mut iter: I) {
    // Item<'_> uses anonymous lifetime from next()
    let first: Option<I::Item<'_>> = iter.next();
    //                         ↑ Apply constructor to fresh lifetime

    // Different call, different lifetime:
    let second: Option<I::Item<'_>> = iter.next();
    //                          ↑ Fresh lifetime again
}
}

The Borrowing Constraint

Standard Iterator - Items Can Be Held:

#![allow(unused)]
fn main() {
let mut iter = vec![1, 2, 3].into_iter();
let first = iter.next();   // first: Option<i32>
let second = iter.next();  // second: Option<i32>

// Both can exist simultaneously:
if let (Some(a), Some(b)) = (first, second) {
    println!("{} {}", a, b);  // ✓ OK
}
}

Streaming Iterator - Items Borrow from Iterator:

#![allow(unused)]
fn main() {
let data = vec![1, 2, 3];
let mut iter = Iter::new(&data);

let first = iter.next();   // first: Option<&'a i32> where 'a = borrow of iter
// let second = iter.next();  // ❌ ERROR: Can't borrow iter mutably again!

// Can't hold two items at once:
// if let (Some(a), Some(b)) = (first, second) {  // Won't compile
//     println!("{} {}", a, b);
// }

// Must drop first before getting second:
if let Some(a) = first {
    println!("{}", a);
}
// first dropped here

let second = iter.next();  // ✓ OK now
}

Why This Limitation:

#![allow(unused)]
fn main() {
// Item borrows from iterator:
type Item<'a> = &'a T where Self: 'a;
//               ↑ This 'a is the lifetime of &mut self in next()

// When you call next():
fn next(&mut self) -> Option<Self::Item<'_>>;
//      ↑ Borrows self mutably
//                              ↑ Item borrows from this &mut self

// Holding the item = holding the borrow of self
// Can't borrow self again until item is dropped
}

Connection to This Project

In this project, you’ll implement all these concepts:

1. Milestone 1: StreamingIterator trait with GATs

   • Define type Item<'a> where Self: 'a
   • Understand why standard Iterator can’t borrow from self
   • Implement simple streaming iterator

2. Milestone 2: Windows iterator with zero-copy

   • Return slices borrowing from data
   • Demonstrate 10-100x speedup over allocating
   • Build step_by adapter

3. Milestone 3: Higher-Ranked Trait Bounds

   • Generic functions with for<'a> bounds
   • Universal quantification over lifetimes
   • Implement for_each, fold, all with HRTB

4. Milestone 4: GroupBy with lifetime variance

   • Demonstrate covariance of &’a T
   • Show why &’a mut T is invariant
   • Lifetime subtyping in practice

5. Milestone 5: Performance comparison

   • Benchmark streaming vs standard iterators
   • Understand trade-offs
   • Document use cases

Key Learning Points:

• GATs enable self-borrowing iterators
• HRTBs express universal lifetime constraints
• Zero-copy iteration eliminates allocation overhead
• Variance determines lifetime subtyping behavior
• Streaming iterators trade flexibility for performance

Real-World Applications:

• Log file parsing (zero-copy line iteration)
• Network packet inspection (borrow packet data)
• Database result sets (cursor-style iteration)
• Video/audio processing (frame/sample windows)
• Compression algorithms (sliding window decompression)

Milestone 1: Basic StreamingIterator Trait with GATs

Goal: Define the StreamingIterator trait using Generic Associated Types (GATs) to enable items that borrow from the iterator.

Concepts:

• Generic Associated Types (GATs): type Item<'a>
• Lifetime parameters in associated types
• Higher-kinded types (type constructors)
• Self-borrowing return types
• GAT where clauses: where Self: 'a

Implementation Steps:

1. Define StreamingIterator trait:

   • Associated type Item<'a> parameterized by lifetime
   • Where clause where Self: 'a (item can borrow from self)
   • Method next(&mut self) -> Option<Self::Item<'_>>
   • Method size_hint(&self) -> (usize, Option<usize>)

2. Implement simple streaming iterator:

   • SliceIter<T> that yields &[T] windows
   • Each call to next() returns a slice borrowing from internal data
   • Demonstrate why standard Iterator can’t do this

3. Compare with standard Iterator:

   • Show compilation error when trying to use Iterator
   • Explain why Item can’t depend on &self lifetime
   • Demonstrate GAT enables self-borrowing

Starter Code:

#![allow(unused)]
fn main() {
// Standard Iterator for comparison
trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

// Streaming Iterator with GATs
pub trait StreamingIterator {
    // TODO: Define Item<'a> as associated type
    // Hint: Generic Associated Type with lifetime parameter
    // Must have where clause: where Self: 'a
    type Item<'a> where Self: 'a;

    // TODO: Define next() method
    // Returns Option<Self::Item<'_>> (borrows from &mut self)
    fn next(&mut self) -> Option<Self::Item<'_>>;

    fn size_hint(&self) -> (usize, Option<usize>) {
        (0, None)
    }
}

// Simple implementation: iterate over references
pub struct Iter<'data, T> {
    data: &'data [T],
    position: usize,
}

impl<'data, T> Iter<'data, T> {
    pub fn new(data: &'data [T]) -> Self {
        Self { data, position: 0 }
    }
}

impl<'data, T> StreamingIterator for Iter<'data, T> {
    // TODO: Set Item<'a> to &'a T
    // This means: when you call next(&'a mut self), you get &'a T
    type Item<'a> = &'a T where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        // TODO: Check if position < data.len()
        // Return Some(&data[position]) and increment position
        // Otherwise return None

        if self.position < self.data.len() {
            let item = &self.data[self.position];
            self.position += 1;
            Some(item)
        } else {
            None
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.data.len() - self.position;
        (remaining, Some(remaining))
    }
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_streaming_iter_basic() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = Iter::new(&data);

        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.next(), Some(&2));
        assert_eq!(iter.next(), Some(&3));
        assert_eq!(iter.next(), Some(&4));
        assert_eq!(iter.next(), Some(&5));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_size_hint() {
        let data = vec![10, 20, 30];
        let mut iter = Iter::new(&data);

        assert_eq!(iter.size_hint(), (3, Some(3)));

        iter.next();
        assert_eq!(iter.size_hint(), (2, Some(2)));

        iter.next();
        assert_eq!(iter.size_hint(), (1, Some(1)));
    }

    #[test]
    fn test_lifetime_borrowing() {
        let data = vec![1, 2, 3];
        let mut iter = Iter::new(&data);

        // Item borrows from iter, which borrows from data
        let first = iter.next().unwrap();
        assert_eq!(*first, 1);

        // Can't move iter while first is borrowed
        // This should NOT compile (uncomment to verify):
        // let second = iter.next(); // ERROR: iter is borrowed
        // println!("{}", first);
    }

    // This demonstrates why standard Iterator won't work
    // #[test]
    // fn test_standard_iterator_fails() {
    //     struct BrokenIter<'a, T> {
    //         data: &'a [T],
    //         pos: usize,
    //     }
    //
    //     // This won't compile: Item can't depend on &self lifetime
    //     impl<'a, T> Iterator for BrokenIter<'a, T> {
    //         type Item = &'a T;  // ERROR: 'a is not related to next()'s lifetime
    //         fn next(&mut self) -> Option<Self::Item> {
    //             // ...
    //         }
    //     }
    // }
}
}

Check Your Understanding:

1. What does type Item<'a> where Self: 'a mean?
2. Why can’t standard Iterator have type Item<'a>?
3. How does the lifetime in next(&mut self) relate to Item<'_>?

Milestone 2: Window Iterator with Slice Borrowing

Goal: Implement Windows<'data, T> that yields overlapping slices of fixed size, demonstrating true streaming iteration.

Concepts:

• Yielding slices that borrow from data
• Window size as const generic
• Sliding window algorithm
• Item lifetime tied to method call lifetime
• Cannot collect into Vec (items borrow from iterator)

Implementation Steps:

1. Define Windows<'data, T> struct:

   • Field: data: &'data [T] (source data)
   • Field: window_size: usize (size of each window)
   • Field: position: usize (current start position)

2. Implement StreamingIterator for Windows:

   • Item<'a> = &'a [T] (slice of window_size elements)
   • next() returns slice from data[position..position+window_size]
   • Increment position by 1 (overlapping windows)
   • Return None when window exceeds data bounds

3. Add helper methods:

   • windows(data, size) constructor
   • step_by(n) adapter for non-overlapping windows
   • Demonstrate why this requires streaming iteration

Starter Code:

#![allow(unused)]
fn main() {
pub struct Windows<'data, T> {
    data: &'data [T],
    window_size: usize,
    position: usize,
}

impl<'data, T> Windows<'data, T> {
    pub fn new(data: &'data [T], window_size: usize) -> Self {
        assert!(window_size > 0, "Window size must be > 0");
        Self {
            data,
            window_size,
            position: 0,
        }
    }
}

impl<'data, T> StreamingIterator for Windows<'data, T> {
    // TODO: Set Item<'a> to &'a [T]
    // This means each window is a borrowed slice
    type Item<'a> = &'a [T] where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        // TODO: Check if we can create a window at current position
        // Need: position + window_size <= data.len()
        // TODO: If yes, get slice &data[position..position+window_size]
        // TODO: Increment position by 1 (overlapping)
        // TODO: Return Some(window)

        if self.position + self.window_size <= self.data.len() {
            let window = &self.data[self.position..self.position + self.window_size];
            self.position += 1;
            Some(window)
        } else {
            None
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        // TODO: Calculate remaining windows
        let remaining = if self.position + self.window_size <= self.data.len() {
            self.data.len() - self.position - self.window_size + 1
        } else {
            0
        };
        (remaining, Some(remaining))
    }
}

// Helper function to create windows
pub fn windows<T>(data: &[T], size: usize) -> Windows<'_, T> {
    Windows::new(data, size)
}

// Adapter for step-by iteration (non-overlapping)
pub struct StepBy<I> {
    iter: I,
    step: usize,
}

impl<I: StreamingIterator> StreamingIterator for StepBy<I> {
    type Item<'a> = I::Item<'a> where Self: 'a, I: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        // TODO: Get next item
        let item = self.iter.next()?;

        // TODO: Skip (step - 1) items
        for _ in 0..(self.step - 1) {
            self.iter.next();
        }

        Some(item)
    }
}

// Extension trait for adapters
pub trait StreamingIteratorExt: StreamingIterator {
    fn step_by(self, step: usize) -> StepBy<Self>
    where
        Self: Sized,
    {
        assert!(step > 0);
        StepBy { iter: self, step }
    }
}

impl<I: StreamingIterator> StreamingIteratorExt for I {}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_windows_overlapping() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = windows(&data, 3);

        assert_eq!(iter.next(), Some(&[1, 2, 3][..]));
        assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
        assert_eq!(iter.next(), Some(&[3, 4, 5][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_size_2() {
        let data = vec!['a', 'b', 'c', 'd'];
        let mut iter = windows(&data, 2);

        assert_eq!(iter.next(), Some(&['a', 'b'][..]));
        assert_eq!(iter.next(), Some(&['b', 'c'][..]));
        assert_eq!(iter.next(), Some(&['c', 'd'][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_exact_size() {
        let data = vec![10, 20, 30];
        let mut iter = windows(&data, 3);

        assert_eq!(iter.next(), Some(&[10, 20, 30][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_too_large() {
        let data = vec![1, 2];
        let mut iter = windows(&data, 5);

        assert_eq!(iter.next(), None); // Window larger than data
    }

    #[test]
    fn test_step_by() {
        let data = vec![1, 2, 3, 4, 5, 6];
        let mut iter = windows(&data, 2).step_by(2);

        assert_eq!(iter.next(), Some(&[1, 2][..]));
        assert_eq!(iter.next(), Some(&[3, 4][..]));
        assert_eq!(iter.next(), Some(&[5, 6][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_cannot_collect() {
        let data = vec![1, 2, 3, 4];
        let mut iter = windows(&data, 2);

        // Can consume and process
        while let Some(window) = iter.next() {
            println!("{:?}", window); // OK: process immediately
        }

        // Cannot collect because Item<'a> borrows from iter
        // This won't compile (no collect() for StreamingIterator):
        // let collected: Vec<_> = iter.collect(); // ERROR
    }

    #[test]
    fn test_lifetime_constraint() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = windows(&data, 3);

        let first = iter.next().unwrap();
        // first borrows from iter, which borrows from data

        // Can't get second window while first is borrowed
        // let second = iter.next(); // ERROR: iter is mutably borrowed

        println!("{:?}", first);
        // first dropped here, can continue iteration
    }
}
}

Check Your Understanding:

1. Why can’t you collect Windows into a Vec like standard iterators?
2. How does the window lifetime relate to the data lifetime?
3. What happens if you try to call next() while holding a previous window?

Milestone 3: Higher-Ranked Trait Bounds for Generic Functions

Goal: Implement generic functions that work with any StreamingIterator, using HRTB to abstract over all lifetimes.

Concepts:

• Higher-Ranked Trait Bounds: for<'a>
• Universal quantification over lifetimes
• Generic functions over streaming iterators
• Lifetime polymorphism
• for<'a> Fn(&'a T) pattern

Implementation Steps:

1. Implement for_each with HRTB:

   • Function that processes each item
   • Works with any StreamingIterator
   • Closure must work for any lifetime: for<'a> F: FnMut(&'a T)

2. Implement all predicate with HRTB:

   • Check if all items satisfy predicate
   • Predicate: for<'a> F: Fn(&'a T) -> bool

3. Implement fold with HRTB:

   • Accumulate value from streaming iterator
   • Closure: for<'a> F: FnMut(B, &'a T) -> B

4. Explain why HRTB is necessary:

   • Without for<'a>: closure tied to single lifetime
   • With for<'a>: closure works for all call lifetimes

Starter Code:

#![allow(unused)]
fn main() {
// Generic function using HRTB
pub fn for_each<I, F>(mut iter: I, mut f: F)
where
    I: StreamingIterator,
    // HRTB: F must work for ANY lifetime 'a
    F: for<'a> FnMut(I::Item<'a>),
{
    // TODO: Call f on each item from iter
    while let Some(item) = iter.next() {
        f(item);
    }
}

// Check if all items satisfy predicate
pub fn all<I, F>(mut iter: I, mut predicate: F) -> bool
where
    I: StreamingIterator,
    // TODO: Add HRTB for predicate
    // Hint: for<'a> Fn(I::Item<'a>) -> bool
    F: for<'a> FnMut(I::Item<'a>) -> bool,
{
    // TODO: Return false if any item fails predicate
    while let Some(item) = iter.next() {
        if !predicate(item) {
            return false;
        }
    }
    true
}

// Fold/reduce with accumulator
pub fn fold<I, B, F>(mut iter: I, init: B, mut f: F) -> B
where
    I: StreamingIterator,
    // TODO: Add HRTB for fold function
    // Hint: for<'a> FnMut(B, I::Item<'a>) -> B
    F: for<'a> FnMut(B, I::Item<'a>) -> B,
{
    // TODO: Fold items into accumulator
    let mut acc = init;
    while let Some(item) = iter.next() {
        acc = f(acc, item);
    }
    acc
}

// Count items
pub fn count<I>(mut iter: I) -> usize
where
    I: StreamingIterator,
{
    // TODO: Count all items
    let mut count = 0;
    while iter.next().is_some() {
        count += 1;
    }
    count
}

// Find first item matching predicate
pub fn find<I, F>(mut iter: I, mut predicate: F) -> bool
where
    I: StreamingIterator,
    // TODO: Add HRTB
    F: for<'a> FnMut(I::Item<'a>) -> bool,
{
    // TODO: Return true if any item matches
    while let Some(item) = iter.next() {
        if predicate(item) {
            return true;
        }
    }
    false
}

// Why HRTB is necessary - comparison:

// WITHOUT HRTB (doesn't work):
// fn broken_for_each<'a, I, F>(mut iter: I, mut f: F)
// where
//     I: StreamingIterator,
//     F: FnMut(I::Item<'a>),  // ERROR: 'a must outlive function
// {
//     while let Some(item) = iter.next() {
//         f(item);  // ERROR: item has different lifetime each call
//     }
// }

// WITH HRTB (works):
// for<'a> means "for ALL lifetimes 'a"
// Function works regardless of what lifetime next() returns
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_for_each() {
        let data = vec![1, 2, 3, 4, 5];
        let iter = windows(&data, 2);

        let mut sum = 0;
        for_each(iter, |window| {
            sum += window[0] + window[1];
        });

        // Windows: [1,2], [2,3], [3,4], [4,5]
        // Sum: 3 + 5 + 7 + 9 = 24
        assert_eq!(sum, 24);
    }

    #[test]
    fn test_all() {
        let data = vec![2, 4, 6, 8];
        let iter = Iter::new(&data);

        let all_even = all(iter, |&x| x % 2 == 0);
        assert!(all_even);

        let data = vec![2, 4, 5, 8];
        let iter = Iter::new(&data);
        let all_even = all(iter, |&x| x % 2 == 0);
        assert!(!all_even);
    }

    #[test]
    fn test_fold() {
        let data = vec![1, 2, 3, 4, 5];
        let iter = Iter::new(&data);

        let sum = fold(iter, 0, |acc, &x| acc + x);
        assert_eq!(sum, 15);
    }

    #[test]
    fn test_fold_windows() {
        let data = vec![1, 2, 3, 4];
        let iter = windows(&data, 2);

        // Concatenate all windows
        let result = fold(iter, Vec::new(), |mut acc, window| {
            acc.extend_from_slice(window);
            acc
        });

        // Windows: [1,2], [2,3], [3,4]
        assert_eq!(result, vec![1, 2, 2, 3, 3, 4]);
    }

    #[test]
    fn test_count() {
        let data = vec![10, 20, 30, 40, 50];
        let iter = windows(&data, 3);

        assert_eq!(count(iter), 3); // 3 windows of size 3
    }

    #[test]
    fn test_find() {
        let data = vec![1, 2, 3, 4, 5];
        let iter = windows(&data, 2);

        // Find window where first element is 3
        let has_window_starting_3 = find(iter, |window| window[0] == 3);
        assert!(has_window_starting_3);
    }

    #[test]
    fn test_hrtb_necessity() {
        let data = vec![1, 2, 3];
        let iter = windows(&data, 2);

        // Closure must work for ANY lifetime
        // Each call to next() returns item with different lifetime
        for_each(iter, |window| {
            // window: &'a [i32] where 'a is different each iteration
            println!("{:?}", window);
        });

        // Without for<'a>, we'd need to name the lifetime upfront
        // But we don't know it until next() is called!
    }
}
}

Check Your Understanding:

1. What does for<'a> FnMut(I::Item<'a>) mean in plain English?
2. Why can’t we use a regular lifetime parameter instead of HRTB?
3. How does the compiler verify the HRTB constraint is satisfied?

Milestone 4: GroupBy Iterator with Lifetime Variance

Goal: Implement GroupBy that yields consecutive equal elements, demonstrating covariance and lifetime relationships.

Concepts:

• Lifetime variance: covariant, contravariant, invariant
• Subtyping with lifetimes ('long: 'short)
• GroupBy algorithm with comparison
• Multiple borrows from same data
• Variance in &'a T (covariant in both ’a and T)

Implementation Steps:

1. Define GroupBy<'data, T> iterator:

   • Groups consecutive equal elements
   • Returns slices of equal elements
   • Item<'a> = &'a [T] where T: PartialEq

2. Implement comparison logic:

   • Scan forward while elements are equal
   • Return slice of all equal consecutive elements
   • Demonstrate lifetime covariance

3. Explain variance:

   • &'a T is covariant in ’a: if ’long: ’short, then &’long T: &’short T
   • &'a mut T is invariant in ’a: no subtyping
   • Function pointers contravariant in argument types

Starter Code:

#![allow(unused)]
fn main() {
pub struct GroupBy<'data, T> {
    data: &'data [T],
    position: usize,
}

impl<'data, T> GroupBy<'data, T> {
    pub fn new(data: &'data [T]) -> Self {
        Self { data, position: 0 }
    }
}

impl<'data, T: PartialEq> StreamingIterator for GroupBy<'data, T> {
    type Item<'a> = &'a [T] where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        // TODO: Check if at end
        if self.position >= self.data.len() {
            return None;
        }

        // TODO: Find end of group (while elements equal)
        let start = self.position;
        let first = &self.data[start];
        let mut end = start + 1;

        while end < self.data.len() && &self.data[end] == first {
            end += 1;
        }

        // TODO: Update position
        self.position = end;

        // TODO: Return slice of group
        Some(&self.data[start..end])
    }
}

// Demonstrate variance
pub fn demonstrate_variance() {
    let data = vec![1, 1, 2, 2, 2, 3];

    // 'data is the lifetime of data
    let group_iter = GroupBy::new(&data);

    // Each group borrows from data
    // &'data [i32] is covariant in 'data:
    // If we had 'long: 'short, we could use &'long in place of &'short

    // This is safe because & is read-only
}

// Variance comparison:
struct CovariantExample<'a, T> {
    reference: &'a T,  // Covariant in both 'a and T
}

struct InvariantExample<'a, T> {
    mutable: &'a mut T,  // Invariant in 'a, covariant in T
}

// Covariance example
fn covariance_works<'long: 'short, 'short>(long_ref: &'long str) -> &'short str {
    // Can return &'long as &'short because 'long: 'short
    // &'a T is covariant in 'a
    long_ref
}

// Invariance example
// fn invariance_fails<'long: 'short, 'short>(
//     long_ref: &'long mut str
// ) -> &'short mut str {
//     // ERROR: Can't return &'long mut as &'short mut
//     // &'a mut T is invariant in 'a
//     long_ref
// }
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_group_by_consecutive() {
        let data = vec![1, 1, 1, 2, 2, 3, 3, 3, 3];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
        assert_eq!(iter.next(), Some(&[2, 2][..]));
        assert_eq!(iter.next(), Some(&[3, 3, 3, 3][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_single_elements() {
        let data = vec![1, 2, 3, 4];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&[1][..]));
        assert_eq!(iter.next(), Some(&[2][..]));
        assert_eq!(iter.next(), Some(&[3][..]));
        assert_eq!(iter.next(), Some(&[4][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_all_equal() {
        let data = vec!['a', 'a', 'a', 'a'];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&['a', 'a', 'a', 'a'][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_strings() {
        let data = vec!["a", "a", "b", "c", "c", "c"];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&["a", "a"][..]));
        assert_eq!(iter.next(), Some(&["b"][..]));
        assert_eq!(iter.next(), Some(&["c", "c", "c"][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_variance_covariant() {
        fn takes_short<'short>(_: &'short str) {}

        let long_lived = String::from("long");
        {
            // long_lived: 'long
            let long_ref: &str = &long_lived;

            // Can pass &'long to function expecting &'short
            // because 'long: 'short (long outlives short)
            takes_short(long_ref); // Covariance!
        }
    }

    #[test]
    fn test_lifetime_subtyping() {
        let data = vec![1, 2, 3];

        // 'data lifetime
        let iter = GroupBy::new(&data);

        // Each group has lifetime tied to 'data
        // Groups can't outlive data (enforced by borrow checker)

        // This won't compile:
        // let group;
        // {
        //     let data2 = vec![4, 5, 6];
        //     let mut iter2 = GroupBy::new(&data2);
        //     group = iter2.next(); // ERROR: data2 doesn't live long enough
        // }
        // println!("{:?}", group);
    }
}
}

Check Your Understanding:

1. What does it mean for &'a T to be covariant in 'a?
2. Why is &'a mut T invariant in 'a but &'a T is covariant?
3. How does variance affect lifetime subtyping in GroupBy?

Milestone 5: Comparison with Standard Iterator and Performance

Goal: Compare streaming iterator with standard iterator, benchmark performance, and demonstrate when each is appropriate.

Concepts:

• Standard vs streaming iterator trade-offs
• Zero-copy vs allocation performance
• When to use each pattern
• Limitations of streaming iterators
• Performance benchmarking

Implementation Steps:

1. Create allocating window iterator:

   • Standard Iterator that returns Vec<T> (owned)
   • Compare with streaming Windows (borrowed)

2. Benchmark both approaches:

   • Measure allocations and time
   • Demonstrate 10-100x difference

3. Document limitations:

   • Can’t collect streaming iterators
   • Can’t hold multiple items simultaneously
   • More complex API

4. Show when streaming is appropriate:

   • Large datasets (log files, network streams)
   • Performance-critical code
   • Zero-copy requirements

Starter Code:

#![allow(unused)]
fn main() {
// Standard Iterator version (allocates)
pub struct AllocatingWindows<T: Clone> {
    data: Vec<T>,
    window_size: usize,
    position: usize,
}

impl<T: Clone> AllocatingWindows<T> {
    pub fn new(data: Vec<T>, window_size: usize) -> Self {
        Self {
            data,
            window_size,
            position: 0,
        }
    }
}

impl<T: Clone> Iterator for AllocatingWindows<T> {
    type Item = Vec<T>;  // Owned, allocated

    fn next(&mut self) -> Option<Self::Item> {
        if self.position + self.window_size <= self.data.len() {
            // ALLOCATION: Copy window into new Vec
            let window = self.data[self.position..self.position + self.window_size]
                .to_vec();
            self.position += 1;
            Some(window)
        } else {
            None
        }
    }
}

// Benchmark comparison
pub fn benchmark_windows(data_size: usize, window_size: usize, iterations: usize) {
    use std::time::Instant;

    let data: Vec<i32> = (0..data_size as i32).collect();

    // Streaming iterator (zero-copy)
    let start = Instant::now();
    for _ in 0..iterations {
        let mut iter = windows(&data, window_size);
        let mut sum = 0;
        while let Some(window) = iter.next() {
            sum += window[0]; // Just access, no allocation
        }
        std::hint::black_box(sum); // Prevent optimization
    }
    let streaming_time = start.elapsed();

    // Standard iterator (allocating)
    let start = Instant::now();
    for _ in 0..iterations {
        let iter = AllocatingWindows::new(data.clone(), window_size);
        let mut sum = 0;
        for window in iter {
            sum += window[0]; // Each window allocated
        }
        std::hint::black_box(sum);
    }
    let allocating_time = start.elapsed();

    println!("Data size: {}, Window: {}", data_size, window_size);
    println!("Streaming:   {:?}", streaming_time);
    println!("Allocating:  {:?}", allocating_time);
    println!(
        "Speedup: {:.2}x",
        allocating_time.as_secs_f64() / streaming_time.as_secs_f64()
    );

    let num_windows = data_size - window_size + 1;
    println!("Allocations saved: {}", num_windows * iterations);
}

// Trade-offs comparison
pub fn compare_iterators() {
    println!("=== Standard Iterator ===");
    println!("Pros:");
    println!("  - Can collect() into Vec, HashMap, etc.");
    println!("  - Can hold multiple items simultaneously");
    println!("  - Familiar API (map, filter, fold)");
    println!("  - Can be cloned if Item: Clone");
    println!("\nCons:");
    println!("  - Must allocate/copy data");
    println!("  - Higher memory usage");
    println!("  - Slower for large items");

    println!("\n=== Streaming Iterator ===");
    println!("Pros:");
    println!("  - Zero-copy (items borrow from iterator)");
    println!("  - 10-100x faster for large items");
    println!("  - Minimal memory footprint");
    println!("  - Can iterate over infinite streams");
    println!("\nCons:");
    println!("  - Can't collect() (no owned items)");
    println!("  - Can only hold one item at a time");
    println!("  - More complex lifetime requirements");
    println!("  - Requires GATs (Rust 1.65+)");
}

// When to use streaming iterators
pub fn use_cases() {
    println!("=== Use Streaming Iterator When: ===");
    println!("  - Processing large files (logs, CSVs)");
    println!("  - Network packet inspection");
    println!("  - Database result sets");
    println!("  - Sliding window algorithms");
    println!("  - Performance-critical hot paths");
    println!("  - Zero-copy parsing");

    println!("\n=== Use Standard Iterator When: ===");
    println!("  - Need to collect results");
    println!("  - Items are small (integers, chars)");
    println!("  - Need to process items multiple times");
    println!("  - Want familiar API (map, filter, etc.)");
    println!("  - Allocation cost is negligible");
}
}

Checkpoint Tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_allocating_windows() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = AllocatingWindows::new(data, 3);

        assert_eq!(iter.next(), Some(vec![1, 2, 3]));
        assert_eq!(iter.next(), Some(vec![2, 3, 4]));
        assert_eq!(iter.next(), Some(vec![3, 4, 5]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_allocating_can_collect() {
        let data = vec![1, 2, 3, 4];
        let iter = AllocatingWindows::new(data, 2);

        // CAN collect with standard Iterator
        let windows: Vec<Vec<i32>> = iter.collect();
        assert_eq!(windows, vec![vec![1, 2], vec![2, 3], vec![3, 4]]);
    }

    #[test]
    fn test_streaming_cannot_collect() {
        let data = vec![1, 2, 3, 4];
        let _iter = windows(&data, 2);

        // CANNOT collect with StreamingIterator
        // No collect() method available!
        // let windows: Vec<_> = iter.collect(); // ERROR

        // Must process immediately:
        // for window in iter {
        //     process(window);
        // }
    }

    #[test]
    fn test_benchmark_small() {
        // Small benchmark
        benchmark_windows(1000, 10, 100);
    }

    #[test]
    fn test_memory_comparison() {
        use std::mem::size_of_val;

        let data: Vec<i32> = (0..1000).collect();

        // Streaming: just slice metadata
        let mut streaming = windows(&data, 10);
        if let Some(window) = streaming.next() {
            println!("Streaming window size: {} bytes", size_of_val(window));
            // Just 16 bytes (pointer + length)
        }

        // Allocating: full Vec allocation
        let mut allocating = AllocatingWindows::new(data.clone(), 10);
        if let Some(window) = allocating.next() {
            println!("Allocating window size: {} bytes", size_of_val(&window));
            // 24 bytes (pointer + length + capacity) + heap allocation
            println!("  + {} bytes on heap", window.capacity() * 4);
        }
    }

    #[test]
    fn test_use_case_demonstration() {
        // Use case: Processing log file (streaming appropriate)
        let log_data = "ERROR: file not found\nWARN: deprecated API\nINFO: startup complete";

        // Streaming: zero-copy line processing
        let lines: Vec<&str> = log_data.lines().collect();
        for line in &lines {
            // Process without allocation
            if line.starts_with("ERROR") {
                println!("Found error: {}", line);
            }
        }

        // Use case: Building data structure (standard iterator appropriate)
        let numbers = vec![1, 2, 3, 4, 5];
        let doubled: Vec<i32> = numbers.iter().map(|&x| x * 2).collect();
        assert_eq!(doubled, vec![2, 4, 6, 8, 10]);
        // Need collect() here, so standard Iterator is better
    }
}
}

Check Your Understanding:

1. Why can’t you collect() a StreamingIterator into a Vec?
2. When would the allocation overhead of standard Iterator be acceptable?
3. How do the lifetime requirements differ between the two iterator types?

Complete Working Example

// Complete Streaming Iterator with HRTB Implementation
// Demonstrates GATs, HRTBs, and zero-copy iteration

//==============================================================================
// Milestone 1: Basic StreamingIterator Trait with GATs
//==============================================================================

/// StreamingIterator trait using Generic Associated Types
/// Unlike standard Iterator, items can borrow from the iterator
pub trait StreamingIterator {
    /// Item type constructor - takes a lifetime parameter
    /// The `where Self: 'a` clause ensures items can't outlive the iterator
    type Item<'a>
    where
        Self: 'a;

    /// Advances the iterator and returns the next item
    /// Item borrows from &mut self, so lifetime is tied to this call
    fn next(&mut self) -> Option<Self::Item<'_>>;

    /// Returns bounds on remaining length
    fn size_hint(&self) -> (usize, Option<usize>) {
        (0, None)
    }
}

//==============================================================================
// Iter: Simple streaming iterator over slice elements
//==============================================================================

/// Iterator that yields references to slice elements
pub struct Iter<'data, T> {
    data: &'data [T],
    position: usize,
}

impl<'data, T> Iter<'data, T> {
    pub fn new(data: &'data [T]) -> Self {
        Self { data, position: 0 }
    }
}

impl<'data, T> StreamingIterator for Iter<'data, T> {
    /// Each call to next() returns &'a T where 'a is the lifetime of that call
    type Item<'a> = &'a T where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        if self.position < self.data.len() {
            let item = &self.data[self.position];
            self.position += 1;
            Some(item)
        } else {
            None
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.data.len() - self.position;
        (remaining, Some(remaining))
    }
}

//==============================================================================
// Milestone 2: Windows Iterator with Zero-Copy Slices
//==============================================================================

/// Iterator that yields overlapping windows of fixed size
/// Returns borrowed slices - zero allocations!
pub struct Windows<'data, T> {
    data: &'data [T],
    window_size: usize,
    position: usize,
}

impl<'data, T> Windows<'data, T> {
    pub fn new(data: &'data [T], window_size: usize) -> Self {
        assert!(window_size > 0, "Window size must be > 0");
        Self {
            data,
            window_size,
            position: 0,
        }
    }
}

impl<'data, T> StreamingIterator for Windows<'data, T> {
    /// Yields slices borrowing from the data
    type Item<'a> = &'a [T] where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        if self.position + self.window_size <= self.data.len() {
            let window = &self.data[self.position..self.position + self.window_size];
            self.position += 1;
            Some(window)
        } else {
            None
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = if self.position + self.window_size <= self.data.len() {
            self.data.len() - self.position - self.window_size + 1
        } else {
            0
        };
        (remaining, Some(remaining))
    }
}

/// Helper function to create windows
pub fn windows<T>(data: &[T], size: usize) -> Windows<'_, T> {
    Windows::new(data, size)
}

//==============================================================================
// StepBy: Adapter for non-overlapping iteration
//==============================================================================

/// Adapter that advances by step items each time
pub struct StepBy<I> {
    iter: I,
    step: usize,
    first: bool,
}

impl<I: StreamingIterator> StreamingIterator for StepBy<I> {
    /// Forward the Item type from the inner iterator
    type Item<'a> = I::Item<'a> where Self: 'a, I: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        // On first call, just return the item
        if self.first {
            self.first = false;
            return self.iter.next();
        }

        // Otherwise, skip (step - 1) items, then return next
        for _ in 0..self.step - 1 {
            self.iter.next()?;
        }

        self.iter.next()
    }
}

/// Extension trait for adapter methods
pub trait StreamingIteratorExt: StreamingIterator {
    /// Creates an iterator that advances by `step` elements each time
    fn step_by(self, step: usize) -> StepBy<Self>
    where
        Self: Sized,
    {
        assert!(step > 0, "Step must be > 0");
        StepBy {
            iter: self,
            step,
            first: true,
        }
    }
}

// Implement for all StreamingIterators
impl<I: StreamingIterator> StreamingIteratorExt for I {}

//==============================================================================
// Milestone 3: Higher-Ranked Trait Bounds for Generic Functions
//==============================================================================

/// Process each item with a closure
/// HRTB: F must work for ANY lifetime 'a
pub fn for_each<'i, I, F>(mut iter: I, mut f: F)
where
    I: StreamingIterator + 'i,
    F: FnMut(I::Item<'_>),
{
    while let Some(item) = iter.next() {
        f(item);
    }
}

/// Check if all items satisfy predicate
pub fn all<'i, I, F>(mut iter: I, mut predicate: F) -> bool
where
    I: StreamingIterator + 'i,
    F: FnMut(I::Item<'_>) -> bool,
{
    while let Some(item) = iter.next() {
        if !predicate(item) {
            return false;
        }
    }
    true
}

/// Fold items into accumulator
pub fn fold<'i, I, B, F>(mut iter: I, init: B, mut f: F) -> B
where
    I: StreamingIterator + 'i,
    F: FnMut(B, I::Item<'_>) -> B,
{
    let mut acc = init;
    while let Some(item) = iter.next() {
        acc = f(acc, item);
    }
    acc
}

/// Count number of items
pub fn count<I>(mut iter: I) -> usize
where
    I: StreamingIterator,
{
    let mut count = 0;
    while iter.next().is_some() {
        count += 1;
    }
    count
}

/// Find if any item matches predicate
pub fn find<'i, I, F>(mut iter: I, mut predicate: F) -> bool
where
    I: StreamingIterator + 'i,
    F: FnMut(I::Item<'_>) -> bool,
{
    while let Some(item) = iter.next() {
        if predicate(item) {
            return true;
        }
    }
    false
}

//==============================================================================
// Milestone 4: GroupBy Iterator with Lifetime Variance
//==============================================================================

/// Groups consecutive equal elements
pub struct GroupBy<'data, T> {
    data: &'data [T],
    position: usize,
}

impl<'data, T> GroupBy<'data, T> {
    pub fn new(data: &'data [T]) -> Self {
        Self { data, position: 0 }
    }
}

impl<'data, T: PartialEq> StreamingIterator for GroupBy<'data, T> {
    type Item<'a> = &'a [T] where Self: 'a;

    fn next(&mut self) -> Option<Self::Item<'_>> {
        if self.position >= self.data.len() {
            return None;
        }

        let start = self.position;
        let first = &self.data[start];
        let mut end = start + 1;

        // Find end of group (while elements are equal)
        while end < self.data.len() && &self.data[end] == first {
            end += 1;
        }

        self.position = end;
        Some(&self.data[start..end])
    }
}

//==============================================================================
// Milestone 5: Comparison with Standard Iterator
//==============================================================================

/// Standard Iterator version that MUST allocate
pub struct AllocatingWindows<T: Clone> {
    data: Vec<T>,
    window_size: usize,
    position: usize,
}

impl<T: Clone> AllocatingWindows<T> {
    pub fn new(data: Vec<T>, window_size: usize) -> Self {
        Self {
            data,
            window_size,
            position: 0,
        }
    }
}

impl<T: Clone> Iterator for AllocatingWindows<T> {
    type Item = Vec<T>; // Must return OWNED Vec

    fn next(&mut self) -> Option<Self::Item> {
        if self.position + self.window_size <= self.data.len() {
            // ALLOCATION: Must copy data into new Vec
            let window = self.data[self.position..self.position + self.window_size].to_vec();
            self.position += 1;
            Some(window)
        } else {
            None
        }
    }
}

/// Benchmark comparison between streaming and allocating iterators
pub fn benchmark_windows(data_size: usize, window_size: usize, iterations: usize) {
    use std::time::Instant;

    let data: Vec<i32> = (0..data_size as i32).collect();

    // Streaming iterator (zero-copy)
    let start = Instant::now();
    for _ in 0..iterations {
        let mut iter = windows(&data, window_size);
        let mut sum = 0;
        while let Some(window) = iter.next() {
            sum += window[0]; // Just access, no allocation
        }
        std::hint::black_box(sum); // Prevent optimization
    }
    let streaming_time = start.elapsed();

    // Standard iterator (allocating)
    let start = Instant::now();
    for _ in 0..iterations {
        let iter = AllocatingWindows::new(data.clone(), window_size);
        let mut sum = 0;
        for window in iter {
            sum += window[0]; // Each window allocated
        }
        std::hint::black_box(sum);
    }
    let allocating_time = start.elapsed();

    println!("\n=== Benchmark Results ===");
    println!("Data size: {}, Window: {}, Iterations: {}", data_size, window_size, iterations);
    println!("Streaming:   {:?}", streaming_time);
    println!("Allocating:  {:?}", allocating_time);
    println!(
        "Speedup: {:.2}x",
        allocating_time.as_secs_f64() / streaming_time.as_secs_f64()
    );

    let num_windows = data_size - window_size + 1;
    println!("Allocations saved: {} per iteration", num_windows);
}

//==============================================================================
// Example Usage
//==============================================================================

fn main() {
    println!("=== Streaming Iterator Examples ===\n");

    // Example 1: Basic iteration
    println!("Example 1: Basic iteration");
    let data = vec![1, 2, 3, 4, 5];
    let mut iter = Iter::new(&data);

    print!("Elements: ");
    while let Some(&x) = iter.next() {
        print!("{} ", x);
    }
    println!("\n");

    // Example 2: Windows with zero-copy
    println!("Example 2: Overlapping windows (zero-copy)");
    let data = vec![1, 2, 3, 4, 5];
    let mut iter = windows(&data, 3);

    while let Some(window) = iter.next() {
        println!("Window: {:?}", window);
    }
    println!();

    // Example 3: Step by for non-overlapping
    println!("Example 3: Non-overlapping windows with step_by");
    let data = vec![1, 2, 3, 4, 5, 6];
    let data_clone = data.clone();
    let mut iter = windows(&data_clone, 2).step_by(2);

    while let Some(window) = iter.next() {
        println!("Window: {:?}", window);
    }
    println!();

    // Example 4: Higher-ranked trait bounds
    println!("Example 4: Using HRTB with for_each");
    {
        static DATA: &[i32] = &[1, 2, 3, 4, 5];
        let iter = windows(DATA, 2);

        for_each(iter, |window| {
            println!("Sum of window: {}", window.iter().sum::<i32>());
        });
    }
    println!();

    // Example 5: GroupBy consecutive elements
    println!("Example 5: GroupBy consecutive equal elements");
    let data = vec![1, 1, 1, 2, 2, 3, 3, 3, 3];
    let mut iter = GroupBy::new(&data);

    while let Some(group) = iter.next() {
        println!("Group: {:?} (length: {})", group, group.len());
    }
    println!();

    // Example 6: Fold with HRTB
    println!("Example 6: Fold to sum all windows");
    {
        static DATA: &[i32] = &[1, 2, 3, 4];
        let iter = windows(DATA, 2);

        let total = fold(iter, 0, |acc, window| acc + window[0] + window[1]);
        println!("Total: {}\n", total);
    }

    // Example 7: Performance comparison
    println!("Example 7: Performance comparison");
    benchmark_windows(1000, 10, 100);
}

//==============================================================================
// Tests
//==============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // Milestone 1 Tests
    #[test]
    fn test_streaming_iter_basic() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = Iter::new(&data);

        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.next(), Some(&2));
        assert_eq!(iter.next(), Some(&3));
        assert_eq!(iter.next(), Some(&4));
        assert_eq!(iter.next(), Some(&5));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_size_hint() {
        let data = vec![10, 20, 30];
        let mut iter = Iter::new(&data);

        assert_eq!(iter.size_hint(), (3, Some(3)));

        iter.next();
        assert_eq!(iter.size_hint(), (2, Some(2)));

        iter.next();
        assert_eq!(iter.size_hint(), (1, Some(1)));
    }

    // Milestone 2 Tests
    #[test]
    fn test_windows_overlapping() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = windows(&data, 3);

        assert_eq!(iter.next(), Some(&[1, 2, 3][..]));
        assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
        assert_eq!(iter.next(), Some(&[3, 4, 5][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_size_2() {
        let data = vec!['a', 'b', 'c', 'd'];
        let mut iter = windows(&data, 2);

        assert_eq!(iter.next(), Some(&['a', 'b'][..]));
        assert_eq!(iter.next(), Some(&['b', 'c'][..]));
        assert_eq!(iter.next(), Some(&['c', 'd'][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_exact_size() {
        let data = vec![10, 20, 30];
        let mut iter = windows(&data, 3);

        assert_eq!(iter.next(), Some(&[10, 20, 30][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_windows_too_large() {
        let data = vec![1, 2];
        let mut iter = windows(&data, 5);

        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_step_by() {
        let data = vec![1, 2, 3, 4, 5, 6];
        let mut iter = windows(&data, 2).step_by(2);

        assert_eq!(iter.next(), Some(&[1, 2][..]));
        assert_eq!(iter.next(), Some(&[3, 4][..]));
        assert_eq!(iter.next(), Some(&[5, 6][..]));
        assert_eq!(iter.next(), None);
    }

    // Milestone 3 Tests
    #[test]
    fn test_for_each() {
        static DATA: &[i32] = &[1, 2, 3, 4, 5];
        let iter = windows(DATA, 2);

        let mut sum = 0;
        for_each(iter, |window| {
            sum += window[0] + window[1];
        });

        // Windows: [1,2], [2,3], [3,4], [4,5]
        // Sum: 3 + 5 + 7 + 9 = 24
        assert_eq!(sum, 24);
    }

    #[test]
    fn test_all() {
        static DATA1: &[i32] = &[2, 4, 6, 8];
        let iter = Iter::new(DATA1);

        let all_even = all(iter, |&x| x % 2 == 0);
        assert!(all_even);

        static DATA2: &[i32] = &[2, 4, 5, 8];
        let iter = Iter::new(DATA2);
        let all_even = all(iter, |&x| x % 2 == 0);
        assert!(!all_even);
    }

    #[test]
    fn test_fold() {
        static DATA: &[i32] = &[1, 2, 3, 4, 5];
        let iter = Iter::new(DATA);

        let sum = fold(iter, 0, |acc, &x| acc + x);
        assert_eq!(sum, 15);
    }

    #[test]
    fn test_fold_windows() {
        static DATA: &[i32] = &[1, 2, 3, 4];
        let iter = windows(DATA, 2);

        // Concatenate all windows
        let result = fold(iter, Vec::new(), |mut acc, window| {
            acc.extend_from_slice(window);
            acc
        });

        // Windows: [1,2], [2,3], [3,4]
        assert_eq!(result, vec![1, 2, 2, 3, 3, 4]);
    }

    #[test]
    fn test_count() {
        let data = vec![10, 20, 30, 40, 50];
        let iter = windows(&data, 3);

        assert_eq!(count(iter), 3); // 3 windows of size 3
    }

    #[test]
    fn test_find() {
        static DATA: &[i32] = &[1, 2, 3, 4, 5];
        let iter = windows(DATA, 2);

        // Find window where first element is 3
        let has_window_starting_3 = find(iter, |window| window[0] == 3);
        assert!(has_window_starting_3);
    }

    // Milestone 4 Tests
    #[test]
    fn test_group_by_consecutive() {
        let data = vec![1, 1, 1, 2, 2, 3, 3, 3, 3];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
        assert_eq!(iter.next(), Some(&[2, 2][..]));
        assert_eq!(iter.next(), Some(&[3, 3, 3, 3][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_single_elements() {
        let data = vec![1, 2, 3, 4];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&[1][..]));
        assert_eq!(iter.next(), Some(&[2][..]));
        assert_eq!(iter.next(), Some(&[3][..]));
        assert_eq!(iter.next(), Some(&[4][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_all_equal() {
        let data = vec!['a', 'a', 'a', 'a'];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&['a', 'a', 'a', 'a'][..]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_group_by_strings() {
        let data = vec!["a", "a", "b", "c", "c", "c"];
        let mut iter = GroupBy::new(&data);

        assert_eq!(iter.next(), Some(&["a", "a"][..]));
        assert_eq!(iter.next(), Some(&["b"][..]));
        assert_eq!(iter.next(), Some(&["c", "c", "c"][..]));
        assert_eq!(iter.next(), None);
    }

    // Milestone 5 Tests
    #[test]
    fn test_allocating_windows() {
        let data = vec![1, 2, 3, 4, 5];
        let mut iter = AllocatingWindows::new(data, 3);

        assert_eq!(iter.next(), Some(vec![1, 2, 3]));
        assert_eq!(iter.next(), Some(vec![2, 3, 4]));
        assert_eq!(iter.next(), Some(vec![3, 4, 5]));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn test_allocating_can_collect() {
        let data = vec![1, 2, 3, 4];
        let iter = AllocatingWindows::new(data, 2);

        // CAN collect with standard Iterator
        let windows: Vec<Vec<i32>> = iter.collect();
        assert_eq!(windows, vec![vec![1, 2], vec![2, 3], vec![3, 4]]);
    }

    #[test]
    fn test_benchmark_small() {
        // Small benchmark to verify it runs
        benchmark_windows(100, 5, 10);
    }

    #[test]
    fn test_memory_comparison() {
        use std::mem::{size_of, size_of_val};

        let data: Vec<i32> = (0..100).collect();

        // Streaming: just slice metadata (pointer + length)
        let mut streaming = windows(&data, 10);
        let slice_ref_size = if let Some(window) = streaming.next() {
            // This measures the fat pointer (&[i32]) on the stack
            size_of_val(&window)  // Size of the reference itself
        } else {
            0
        };

        // Allocating: full Vec (pointer + length + capacity)
        let mut allocating = AllocatingWindows::new(data.clone(), 10);
        let vec_ref_size = if let Some(window) = allocating.next() {
            // This measures Vec<i32> on the stack
            size_of_val(&window)
        } else {
            0
        };

        // Both &[i32] and Vec<i32> are stack structures
        // &[i32] is 16 bytes (ptr + len)
        // Vec<i32> is 24 bytes (ptr + len + cap)
        println!("Slice reference size: {}", slice_ref_size);
        println!("Vec size: {}", vec_ref_size);
        println!("Expected &[T] size: {}", size_of::<&[i32]>());
        println!("Expected Vec<T> size: {}", size_of::<Vec<i32>>());

        // Just verify they have reasonable sizes
        assert!(slice_ref_size > 0 && vec_ref_size > 0);
    }

    #[test]
    fn test_zero_cost_abstraction() {
        // Streaming iterator is just data pointer + position
        let data = vec![1, 2, 3];
        let iter = Iter::new(&data);

        // Should be small - just a reference and index
        assert!(std::mem::size_of_val(&iter) <= 24);
    }
}

zero-copy-parser

JSON Parser

Problem Statement

Build a JSON parser and schema validator that uses Rust’s pattern matching to parse JSON strings into an AST and validate against type schemas. You’ll implement recursive pattern matching for nested structures, exhaustive enum matching for all JSON types, pattern guards for validation rules, and deep destructuring for complex document traversal.

Understanding JSON Syntax

Before diving into parsing, let’s understand JSON (JavaScript Object Notation) - a lightweight data interchange format that’s easy for humans to read and write, and easy for machines to parse and generate.

JSON Data Types

JSON supports exactly six data types:

1. Null

Represents an empty or non-existent value.

null

Properties:

• Only one possible value: null
• Often used to indicate “no value” or “unknown”
• Case-sensitive (must be lowercase)

2. Boolean

Logical true or false values.

true
false

Properties:

• Only two possible values: true or false
• Case-sensitive (must be lowercase)
• Not quoted (not strings)

3. Number

Numeric values including integers and floating-point numbers.

42
-17
3.14159
2.5e10
-1.23e-4

Properties:

• No distinction between integer and float in JSON spec
• Can be negative (prefix with -)
• Can use scientific notation (e or E)
• No octal or hexadecimal notation
• No leading zeros (except for 0.something)
• No NaN or Infinity (not valid JSON)

Examples:

0           // Valid
-42         // Valid
3.14        // Valid
1.5e3       // Valid (1500)
-2.5e-2     // Valid (-0.025)

4. String

Sequence of Unicode characters wrapped in double quotes.

"hello"
"Hello, World!"
"Line 1\nLine 2"
"Unicode: \u0048\u0065\u006C\u006C\u006F"

Properties:

• Must use double quotes (not single quotes)
• Can contain escape sequences:
  • \" - double quote
  • \\ - backslash
  • \/ - forward slash
  • \b - backspace
  • \f - form feed
  • \n - newline
  • \r - carriage return
  • \t - tab
  • \uXXXX - Unicode character (4 hex digits)
• Cannot contain unescaped control characters

Examples:

"simple"                    // Valid
"with \"quotes\""           // Valid (escaped quotes)
"path\\to\\file"            // Valid (escaped backslashes)
"tab\there"                 // Valid (tab character)
"unicode: \u0041"           // Valid (produces "unicode: A")
'single quotes'             // INVALID (must use double quotes)
"unescaped
newline"                    // INVALID (newlines must be escaped)

5. Array

Ordered list of values (can be of mixed types).

[1, 2, 3]
["apple", "banana", "cherry"]
[true, 42, "mixed", null]
[
  [1, 2],
  [3, 4]
]
[]

Properties:

• Enclosed in square brackets [ ]
• Values separated by commas ,
• Can contain any JSON value type
• Can be nested (arrays within arrays)
• Can be empty
• Trailing commas not allowed

Examples:

[1, 2, 3]                  // Valid
[]                         // Valid (empty array)
[1, "two", true, null]     // Valid (mixed types)
[[1, 2], [3, 4]]          // Valid (nested)
[1, 2, 3,]                // INVALID (trailing comma)

6. Object

Unordered collection of key-value pairs.

{
  "name": "John",
  "age": 30,
  "isStudent": false
}

Properties:

• Enclosed in curly braces { }
• Keys must be strings (in double quotes)
• Key-value pairs separated by colons :
• Pairs separated by commas ,
• Keys must be unique within an object
• Can contain any JSON value type as values
• Can be nested
• Trailing commas not allowed

Examples:

// Simple object
{
  "name": "Alice",
  "age": 25
}

// Nested objects
{
  "person": {
    "name": "Bob",
    "address": {
      "city": "NYC",
      "zip": "10001"
    }
  }
}

// Mixed values
{
  "id": 123,
  "active": true,
  "tags": ["rust", "programming"],
  "metadata": null
}

// Empty object
{}

// INVALID examples:
{ name: "value" }          // Keys must be quoted
{ "key": "value", }        // Trailing comma not allowed
{ "a": 1, "a": 2 }        // Duplicate keys (undefined behavior)

JSON Grammar Rules

Whitespace

JSON ignores whitespace between tokens:

• Space
• Tab \t
• Newline \n
• Carriage return \r

// These are equivalent:
{"name":"value"}
{
  "name": "value"
}
{ "name" : "value" }

Valid JSON Documents

A JSON document must have exactly one root value:

// Valid - single object
{ "key": "value" }

// Valid - single array
[1, 2, 3]

// Valid - single string
"hello"

// INVALID - multiple root values
{ "a": 1 } { "b": 2 }

// INVALID - just a comma
,

JSON Examples in Context of This Project

Example 1: Simple User Object

{
  "id": 42,
  "username": "alice",
  "email": "alice@example.com",
  "isActive": true,
  "lastLogin": null
}

Structure breakdown:

• Root: Object with 5 key-value pairs
• Keys: All strings
• Values: Number, String, String, Boolean, Null

Example 2: Nested Configuration

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem"
    }
  },
  "features": ["logging", "metrics", "auth"]
}

Structure breakdown:

• Root: Object
• Nested: 2 levels deep (server → tls)
• Array: Contains strings
• Mixed types: Objects, Strings, Numbers, Booleans, Arrays