Rust Ownership Patterns

---
name: rust-ownership-patterns
description: |
  Guides advanced Rust ownership and borrowing: lifetime annotations, smart pointer decision tree (Box vs Rc vs Arc vs Cow), borrow checker strategies, and zero-cost abstraction patterns.
  Use when the user asks about Rust ownership, borrowing, lifetimes, smart pointers, Box, Rc, Arc, Cow, borrow checker.
  Do NOT use when the user asks about Rust project setup (use `rust-project-setup`), Rust error handling (use `rust-error-handling`), Rust performance (use `rust-performance`).
license: Apache-2.0
metadata:
  author: foundry-skills
  version: "1.0.0"
  tags: "rust best-practices clean-code"
  category: "software-engineering"
  subcategory: "languages-runtimes"
  depends: ""
  disclaimer: "none"
  difficulty: "advanced"
---
# Rust Ownership Patterns

## When to Use

**Use this skill when:**
- The user is designing a data structure and needs to choose between owned types, references, or smart pointers (e.g., "should I store a `String` or `&str` in this struct?")
- The user is fighting the borrow checker -- getting E0502, E0505, E0506, E0515, or E0521 errors and needs to understand the root cause and fix
- The user needs to decide between `Box<T>`, `Rc<T>`, `Arc<T>`, `Cell<T>`, `RefCell<T>`, or `Cow<'a, T>` for a specific use case
- The user is writing generic code or trait objects and needs lifetime annotations (`'a`, `'static`, HRTB with `for<'a>`)
- The user is implementing a self-referential struct, a graph, a tree with parent pointers, or another cyclic/shared-ownership structure
- The user wants to understand when cloning is acceptable versus when to redesign ownership structure
- The user is hitting issues with `Send` + `Sync` bounds in async or multi-threaded code related to ownership
- The user is working with `unsafe` code that requires manual lifetime management (raw pointers, `transmute`, `ManuallyDrop`)

**Do NOT use this skill when:**
- The user asks about setting up a Rust project, workspace layout, Cargo.toml configuration, or feature flags -- use `rust-project-setup`
- The user asks about `Result`, `Option`, `?` operator, custom error types, `thiserror`, or `anyhow` -- use `rust-error-handling`
- The user asks about Rust performance profiling, SIMD, cache optimization, or zero-copy I/O tuning -- use `rust-performance`
- The user is asking about async Rust specifically (`.await`, `Future`, `tokio`, `async-std`) -- use `rust-async-patterns` if available, but note ownership concerns in async code may overlap
- The user asks about Rust macro authorship (`macro_rules!`, proc macros) -- those have distinct concerns not addressed here
- The user is asking about FFI (calling C from Rust or vice versa) -- ownership rules apply but the primary concern is ABI and safety invariants

---

## Process

### 1. Diagnose the Ownership Problem or Design Question

Before recommending any pattern, fully understand what the user is trying to express:

- Identify whether this is a **compiler error** (borrow checker rejection), a **design question** (choosing how to model ownership), or a **performance question** (unnecessary clones or allocations)
- For compiler errors, extract the exact error code (E0502 = cannot borrow as mutable because also borrowed as immutable, E0505 = cannot move out of value because borrowed, E0515 = cannot return reference to local variable, E0521 = borrowed data escapes outside of closure)
- Ask what the **lifetime of the data** should be -- who creates it, who is responsible for dropping it, and who needs to read or mutate it
- Identify whether shared ownership is truly required or whether a different data flow would eliminate the need for `Rc`/`Arc`
- Determine whether the struct owns its data or borrows it: structs that borrow data need lifetime parameters and are harder to use in async contexts and thread-spawning

### 2. Apply the Smart Pointer Decision Tree

Walk through this decision tree in order -- stop at the first match:

- **Does only one place ever own this value at a time, and no heap allocation is needed?** -- Use a plain owned type (`T`) or reference (`&T` / `&mut T`). This is the default; all other options exist to escape limitations of this model.
- **Do you need heap allocation to break infinite type size (e.g., recursive types) or to store a trait object?** -- Use `Box<T>`. Zero runtime overhead beyond the heap allocation itself. Use `Box<dyn Trait>` for dynamic dispatch.
- **Do you need shared ownership within a single thread, with the ability to mutate through shared references?** -- Use `Rc<T>` for shared ownership. Combine with `RefCell<T>` for interior mutability (`Rc<RefCell<T>>`). `RefCell` panics at runtime on aliased mutable borrows; use only when the borrow checker cannot statically prove safety.
- **Do you need shared ownership across threads?** -- Use `Arc<T>`. Combine with `Mutex<T>` or `RwLock<T>` for interior mutability (`Arc<Mutex<T>>`). Prefer `RwLock` when reads vastly outnumber writes. `Mutex` adds 20-40ns per lock/unlock on x86_64 under contention; `RwLock` is faster for concurrent reads.
- **Do you have data that is usually borrowed but occasionally needs to be owned (e.g., function that accepts both `&str` and `String`)?** -- Use `Cow<'a, str>` (or `Cow<'a, [T]>` for slices). Clone only when mutation is required. This is the correct pattern for configuration structs that might hold constants or dynamic strings.
- **Do you need shared ownership within a single thread but with guaranteed single mutation access (no `RefCell` panics)?** -- Consider redesigning with a central owner and passing `&mut T` explicitly, or use an arena allocator (`bumpalo`, `typed-arena`) for data with the same lifetime.
- **Do you need to mutate a `T` through a shared `&T` reference without `Rc` or `Arc`?** -- Use `Cell<T>` for `Copy` types (zero overhead) or `RefCell<T>` for non-`Copy` types (small runtime borrow tracking overhead).

### 3. Design Lifetime Annotations

When a struct or function borrows data, lifetime annotations encode who owns the data and how long the borrow lasts:

- Start with **lifetime elision** -- do not add annotations the compiler can infer. The three elision rules cover most free functions.
- Add explicit lifetimes when a struct holds a reference: `struct Parser<'a> { input: &'a str }`. The lifetime parameter says "a `Parser` cannot outlive the `&str` it was given."
- When a function returns a reference derived from one of multiple input references, annotate to tell the compiler which input it comes from: `fn longest<'a>(x: &'a str, y: &'a str) -> &'a str`. The lifetime `'a` is the intersection (shorter) of the two inputs.
- Use `'static` only when data truly lives for the entire program -- string literals, `lazy_static!`/`once_cell` globals, or data explicitly leaked with `Box::leak`. Do NOT use `'static` as a workaround for lifetime problems; it signals permanent heap allocation or global state.
- Use Higher-Rank Trait Bounds (HRTB) with `for<'a>` when a trait must hold for all possible lifetimes: `where F: for<'a> Fn(&'a str) -> &'a str`. This appears in closures stored in structs and in `serde::Deserialize`.
- Prefer **named lifetimes** over single-letter ones in complex APIs: `'input`, `'arena`, `'env` communicate intent. Reserve `'a`, `'b` for simple, obvious cases.
- When a struct has multiple lifetime parameters, explicitly name the relationship if one outlives the other: `struct StrSplit<'haystack, 'delimiter>` where `'haystack: 'delimiter` means haystack outlives delimiter.

### 4. Resolve Borrow Checker Conflicts

When the compiler rejects code, apply these resolution strategies in order of preference:

- **Restructure borrow scopes using blocks**: Wrapping a borrow in `{ }` terminates it before the next borrow begins. This resolves most E0502 errors without changing logic.
- **Clone selectively**: Clone only the specific field needed, not the whole struct. Use `.clone()` on a `String` before passing ownership elsewhere. Cloning a `String` is ~10-50ns and heap-allocates; do it when the alternative is architectural complexity.
- **Use indices instead of references** in graph/tree structures: store `Vec<Node>` and refer to nodes by `usize` index. This is the idiomatic Rust solution for self-referential and graph structures -- no lifetimes, no `Rc`, O(1) lookup.
- **Split structs** to allow independent borrows: if methods borrow all of `self`, split fields into sub-structs so different methods can borrow different sub-structs simultaneously.
- **Use `split_at_mut`** or similar slice primitives when you need two mutable references into the same collection.
- **Reach for `unsafe` only as a last resort** after documenting exactly what invariant the unsafe code relies on, writing a safety comment, and confirming no safe alternative exists.

### 5. Apply Interior Mutability Correctly

Interior mutability bypasses the static borrow checker at the cost of runtime checks or atomic operations:

- `Cell<T>` -- only for `Copy` types. Provides `get()` and `set()`. No runtime borrow tracking. Zero overhead. Use for shared counters, flags, simple values.
- `RefCell<T>` -- for non-`Copy` types on a single thread. `borrow()` returns `Ref<T>`, `borrow_mut()` returns `RefMut<T>`. Panics if you call `borrow_mut()` while any `borrow()` is live. Keep `borrow_mut()` scopes as small as possible. Prefer `try_borrow_mut()` in library code to return an error instead of panicking.
- `Mutex<T>` -- for multi-threaded mutation. Blocks on contention. Always lock for the shortest duration possible -- do not hold a `MutexGuard` across an `.await` point (this is a common bug in async Rust that causes deadlocks or `Send` bound violations).
- `RwLock<T>` -- multiple readers OR one writer. On Linux with `pthreads`, a writer can starve under heavy read load. Use `parking_lot::RwLock` for better performance and starvation resistance (parking_lot locks are 2-5x faster than `std` under contention).
- `AtomicUsize`, `AtomicBool`, etc. -- for primitive values in lock-free contexts. Use `Ordering::SeqCst` when uncertain, then optimize to `Relaxed`/`Acquire`/`Release` only after understanding the memory model implications.

### 6. Handle Cow<'a, B> Properly

`Cow` (Clone on Write) is underused and frequently misunderstood:

- The type constraint is `B: ToOwned` -- `Cow<'a, str>` wraps either `&'a str` (borrowed) or `String` (owned), `Cow<'a, [T]>` wraps either `&'a [T]` or `Vec<T>`.
- Construct with `Cow::Borrowed(&data)` or `Cow::Owned(data)`. Use `Cow::from()` which infers the variant.
- Call `.to_mut()` to get a `&mut <B as ToOwned>::Owned` -- this clones the borrowed data the first time, then mutates in place on subsequent calls.
- Primary use cases: (1) functions that return either a borrowed slice of their input or a newly allocated transformation, (2) config/message structs that hold string fields which are usually `'static` string literals but occasionally runtime strings, (3) avoiding allocation in hot paths that rarely need mutation.
- `Cow<'a, str>` implements `Deref<Target = str>`, so it works anywhere `&str` does.

### 7. Verify Trait Bounds: Send and Sync

Ownership patterns have direct implications for concurrency:

- `T: Send` means `T` can be transferred to another thread. `Rc<T>` is NOT `Send` because its reference count is not atomic.
- `T: Sync` means `&T` can be shared across threads. `Cell<T>` and `RefCell<T>` are NOT `Sync` because their interior mutability is not thread-safe.
- `Arc<T>` is `Send + Sync` if and only if `T: Send + Sync`.
- `Arc<Mutex<T>>` is `Send + Sync` if `T: Send`, which covers most practical cases.
- When the compiler says "the trait `Send` is not implemented for `Rc<...>`", the fix is almost always to replace `Rc` with `Arc` and `RefCell` with `Mutex`/`RwLock`.
- In async code, values held across `.await` points must be `Send` if the executor is multi-threaded (tokio's default). If a `MutexGuard` is held across `.await`, the future is not `Send`. The fix is to drop the guard before `.await` by scoping it in a block.

### 8. Document Ownership Decisions in Code

Every non-obvious ownership choice must be documented at the point of declaration:

- Comment why `Rc<RefCell<T>>` is used instead of redesigning: "// Shared ownership required: multiple UI components update this model. Single-threaded context only."
- Comment `unsafe` blocks with a `// SAFETY:` line explaining the invariant being upheld.
- Comment `'static` bounds when they are not obvious: "// 'static required because this is stored in a global registry."
- Use type aliases to give complex types readable names: `type SharedConfig = Arc<RwLock<Config>>`. Name the alias at module level.
- If the lifetime of a struct is not obvious, add a module-level doc comment explaining the ownership model of the data it processes.

---

## Output Format

When answering a Rust ownership question, structure the response as follows:

```
## Diagnosis
[One paragraph identifying the core ownership problem: what the compiler is enforcing and why]

## Smart Pointer / Pattern Recommendation

| Scenario | Recommended Type | Why |
|---|---|---|
| Single owner, stack or heap | T or Box<T> | Zero overhead; default choice |
| Shared, single-thread, no mutation | Rc<T> | Non-atomic refcount; cheaper than Arc |
| Shared, single-thread, with mutation | Rc<RefCell<T>> | Interior mutability; panics on aliased borrows |
| Shared, multi-thread, no mutation | Arc<T> | Atomic refcount; T must be Sync |
| Shared, multi-thread, with mutation | Arc<Mutex<T>> or Arc<RwLock<T>> | Thread-safe interior mutability |
| Borrowed or owned string/slice | Cow<'a, str> / Cow<'a, [T]> | Avoids allocation when no mutation needed |
| Cell-like, Copy type, single-thread | Cell<T> | Zero overhead; no borrow tracking |
| Dynamic dispatch, heap | Box<dyn Trait> | Trait objects; 8-byte fat pointer |

## Lifetime Annotation Guide
[Explanation of which lifetimes to add and why, with annotated code]

## Corrected / Recommended Implementation

```rust
// [Full, compilable code example with doc comments explaining ownership decisions]
```

## Trade-offs
[Table or bullet list: performance cost, ergonomics, thread safety, and failure mode of the chosen pattern]

## Alternatives Considered
[Brief note on why other patterns were rejected for this specific case]
```

---

## Rules

1. **Never recommend `Rc<RefCell<T>>` without first verifying the use case is truly single-threaded.** If there is any chance of threading, `Arc<Mutex<T>>` is required. Mixing `Rc` into a multi-threaded context causes undefined behavior that the compiler will catch at the `Send`/`Sync` bound.

2. **Never use `'static` as a lifetime workaround.** `'static` means the data lives forever or is leaked. Using `Box::leak` to satisfy a `'static` bound is a memory leak unless you have a specific reclamation strategy. When a user is tempted by `'static`, explore whether an owned type or a shorter lifetime solves the problem.

3. **Never advise holding a `MutexGuard` across an `.await` point.** This makes the `Future` non-`Send` and, if it compiles at all (e.g., with a single-threaded executor), risks deadlock. Always scope guards to the smallest possible block.

4. **Never recommend `unsafe` before exhausting safe alternatives.** Safe alternatives include: restructuring borrow scopes, using indices, splitting structs, using `Cell`/`RefCell`, or using `Arc`. Document when `unsafe` is truly the only option and always include a `// SAFETY:` comment.

5. **Always prefer the simplest ownership model that satisfies the requirements.** The preference order is: owned value > shared reference > `Box` > `Rc`/`Arc` > `RefCell`/`Mutex`. Each step adds complexity or overhead; justify each step up.

6. **Never clone unnecessarily, but never avoid cloning dogmatically.** Cloning a `String` is ~10-50ns and is often the right trade-off. The problem is cloning in hot loops or cloning entire large data structures when only a field is needed. Profile before optimizing clone behavior.

7. **Never put a `RefCell<T>` in a struct without documenting the borrow discipline.** Because `RefCell` panics at runtime, callers must know not to hold a `borrow()` while also calling a method that takes `borrow_mut()`. This is invisible from the type signature.

8. **Always make `Cow<'a, T>` fields explicit about the lifetime in public APIs.** `Cow<'static, str>` in a public struct means the struct owns its string data or uses string literals -- this is a meaningful API contract. Omitting the lifetime or hiding it prevents callers from understanding storage behavior.

9. **Never apply graph/tree pointer structures with `Rc` when an arena allocator fits.** For trees where nodes share a single lifetime (they're all allocated together and freed together), an arena (`bumpalo`, `typed-arena`) is faster (bump allocation ~1ns vs `Rc` allocation ~10-20ns) and produces simpler code with plain references.

10. **Always check `Send + Sync` implications when introducing a new smart pointer.** If a type wraps `Rc`, `Cell`, or `RefCell`, the wrapping type is automatically not `Send`/`Sync`. This silently infects any type that contains it. Run `cargo check` and look for `Send`/`Sync` errors before finalizing a design.

---

## Edge Cases

### Self-Referential Structs
Rust's ownership model makes self-referential structs (a struct with a field that contains a reference to another of its own fields) impossible with safe references. The standard solutions are: (1) Use indices into a `Vec` instead of references -- this is always the correct first choice. (2) Use `Pin<Box<T>>` with `unsafe` for truly intrusive structures like async futures or certain linked list implementations. (3) Use the `ouroboros` or `self_cell` crates which generate safe wrappers around `unsafe` self-referential code. (4) Use an arena allocator so all nodes share a lifetime and can hold plain `&'arena Node` references. Never use `Rc<RefCell<T>>` for self-referential structs -- it adds overhead and does not solve the lifetime problem.

### Cyclic References with Rc
`Rc<T>` uses reference counting, which cannot detect cycles. A cycle of `Rc` pointers leaks memory because the reference count never reaches zero. The solution is to designate one direction of the relationship as `Rc` (strong, owns the child) and the other as `Weak<T>` (weak, does not own). Obtain a `Weak<T>` with `Rc::downgrade(&rc)`. Upgrade to `Rc<T>` with `weak.upgrade()` which returns `Option<Rc<T>>` -- `None` if the value has been dropped. The classic pattern: a tree where parent holds `Vec<Rc<Child>>` and each child holds `Weak<Parent>`.

### Lifetime Variance and Subtyping
Rust lifetimes are covariant in most positions -- a `&'long T` can be used where `&'short T` is expected because `'long` outlives `'short`. However, `&mut T` is invariant in `T`: you cannot use `&mut &'long str` where `&mut &'short str` is expected. This causes surprising errors when storing mutable references to references. The fix is usually to avoid mutable references to references (use owned types) or to add explicit variance annotations via `PhantomData<fn(T) -> T>` in unsafe code.

### Returning References from Methods Across Branches
When a method tries to return a reference from one branch of an `if` or `match` that is computed differently in each branch, the compiler cannot always prove the lifetimes match. A common case: trying to return either `self.cache` (borrowed from self) or a newly computed value (local to the method). You cannot return both from the same function because the local value is dropped. The solution is to either: (1) store the computed value in `self` before returning a reference to it, (2) return an owned value instead of a reference, or (3) use `Cow` to allow returning either borrowed or owned.

### Interior Mutability and Iterator Invalidation
`RefCell<Vec<T>>` does not protect against iterator invalidation because `borrow_mut()` is a runtime check, not a static one. If code borrows the `Vec` for iteration and then calls a function that `borrow_mut()`s the same `Vec` during iteration, it panics. Structure code so that the full iteration completes before any mutation, or collect the iteration results first (`.collect::<Vec<_>>()`) and then process mutations.

### `Arc<Mutex<T>>` Poisoning
When a thread panics while holding a `Mutex`, the mutex is "poisoned." Subsequent calls to `lock()` return `Err(PoisonError)`. Most codebases should handle this: either call `.unwrap()` to propagate the panic (appropriate if the poisoned state is unrecoverable) or call `.unwrap_or_else(|e| e.into_inner())` to recover the data (appropriate if the panic was in unrelated code and the data is still valid). Never silently ignore a `PoisonError` -- it means another thread panicked while mutating shared state.

### Cow with Non-str Types
`Cow<'a, [u8]>` (byte slices) is common in I/O and serialization code. A subtle issue: when you call `.to_mut()` on a `Cow::Borrowed(&[u8])`, it clones the slice into a `Vec<u8>`. If the slice is large (e.g., a multi-megabyte buffer), this is a significant allocation. Profile `Cow` usage in hot paths and consider whether the "rarely needs mutation" assumption actually holds for the data sizes in production.

### Lifetime Bounds on Trait Objects
`Box<dyn Trait>` has an implicit `'static` lifetime bound: it is actually `Box<dyn Trait + 'static>`. This means the trait object cannot contain any borrowed data. If a trait object needs to borrow data, write the bound explicitly: `Box<dyn Trait + 'a>` where `'a` is a lifetime parameter of the enclosing struct or function. Forgetting this is a common source of confusing "does not live long enough" errors when first using trait objects.

---

## Example

**Input:** "I'm building a simple in-memory key-value store that will be accessed by multiple threads. The store holds `String` keys and `Vec<u8>` values. I need to return a reference to values to avoid copying them, and I want multiple readers to be able to read simultaneously. I'm getting lifetime errors when I try to return `&Vec<u8>` from a method that takes `&self`."

---

**Output:**

## Diagnosis

The core problem is that you are trying to return a reference (`&Vec<u8>`) to data inside a `Mutex` or `RwLock` guard, but the guard is a local variable in the method -- when the method returns, the guard is dropped and the reference becomes dangling. The compiler correctly rejects this. Additionally, multi-reader access with single-writer semantics is exactly the use case for `RwLock<T>` rather than `Mutex<T>`.

The fix requires one of two approaches: (1) return an owned value (`Vec<u8>` or `Arc<Vec<u8>>`) instead of a reference, or (2) change the API to accept a closure that operates on the reference while the lock is held. Returning a reference across a lock boundary is fundamentally unsafe in Rust without `unsafe` code or crates like `parking_lot`'s `MappedRwLockReadGuard`.

The recommended production solution is to store values as `Arc<Vec<u8>>` so that returning a clone of the `Arc` is cheap (~5ns, just an atomic increment) and gives callers a stable reference to the data with no lifetime entanglement.

---

## Smart Pointer / Pattern Recommendation

| Scenario | Recommended Type | Why |
|---|---|---|
| Shared store across threads | `Arc<RwLock<HashMap<...>>>` | Multi-reader, single-writer; thread-safe |
| Values in the store | `Arc<Vec<u8>>` | Cheap clone; callers get stable reference |
| Returning value to caller | Clone the `Arc<Vec<u8>>` | ~5ns; avoids lifetime-across-lock-boundary problem |
| Key type | `String` (owned) | No lifetime complications in HashMap key |

---

## Lifetime Annotation Guide

The reason `&Vec<u8>` cannot be returned from a method that locks a `RwLock` is that the reference's lifetime would be tied to the `RwLockReadGuard`, which is local to the method. The lifetime would need to be `'guard` which does not exist at the call site.

By switching values to `Arc<Vec<u8>>`, we return an owned handle. The lifetime of the underlying `Vec<u8>` is managed by the `Arc` reference count, not by any borrow scope. This is the idiomatic solution when references cannot escape lock scope.

---

## Corrected / Recommended Implementation

```rust
use std::collections::HashMap;
use std::sync::{Arc, RwLock};

/// Thread-safe in-memory key-value store.
///
/// Values are stored as `Arc<Vec<u8>>` so that callers receive a cheap,
/// owned handle (just an atomic refcount increment) rather than a reference
/// tied to the internal lock guard's lifetime.
///
/// Use `RwLock` rather than `Mutex` because reads vastly outnumber writes
/// in typical KV store workloads. Multiple readers proceed concurrently;
/// writers have exclusive access.
#[derive(Clone, Default)]
pub struct KvStore {
    // Arc here allows KvStore itself to be cheaply cloned and shared
    // across threads (e.g., passed to multiple tokio tasks).
    inner: Arc<RwLock<HashMap<String, Arc<Vec<u8>>>>>,
}

impl KvStore {
    pub fn new() -> Self {
        Self::default()
    }

    /// Returns a clone of the Arc<Vec<u8>> for the given key, or None.
    ///
    /// Cloning an Arc is ~5ns (one atomic fetch-add). The returned Arc
    /// keeps the data alive independently of the store -- safe to hold
    /// across await points or pass to other threads.
    pub fn get(&self, key: &str) -> Option<Arc<Vec<u8>>> {
        // Acquire a read lock. Multiple threads can hold this simultaneously.
        // The guard is dropped at the end of this block, before we return.
        let guard = self.inner.read().expect(
            // Panic on poison: if a writer panicked mid-mutation,
            // the HashMap may be in an inconsistent state.
            "KvStore RwLock poisoned: a writer panicked during mutation",
        );
        // Clone the Arc, not the Vec<u8>. This is O(1).
        guard.get(key).cloned()
    }

    /// Inserts or replaces a value for the given key.
    ///
    /// The caller passes a Vec<u8>; we wrap it in Arc before storing.
    /// If the caller already has an Arc<Vec<u8>> (e.g., shared with
    /// another part of the system), use `insert_arc` to avoid double-wrapping.
    pub fn insert(&self, key: String, value: Vec<u8>) {
        let mut guard = self.inner.write().expect(
            "KvStore RwLock poisoned",
        );
        guard.insert(key, Arc::new(value));
    }

    /// Inserts a pre-wrapped Arc<Vec<u8>>. Useful when the value is
    /// already shared elsewhere and you want the store to participate
    /// in the same Arc refcount rather than creating a new allocation.
    pub fn insert_arc(&self, key: String, value: Arc<Vec<u8>>) {
        let mut guard = self.inner.write().expect(
            "KvStore RwLock poisoned",
        );
        guard.insert(key, value);
    }

    /// Removes a key. Returns the Arc if it was present.
    pub fn remove(&self, key: &str) -> Option<Arc<Vec<u8>>> {
        let mut guard = self.inner.write().expect(
            "KvStore RwLock poisoned",
        );
        guard.remove(key)
    }

    /// Applies a function to the value for a key while holding the read lock.
    ///
    /// Use this when you need to operate on the &Vec<u8> directly without
    /// cloning. The closure must not acquire the KvStore lock (deadlock).
    pub fn with_value<F, R>(&self, key: &str, f: F) -> Option<R>
    where
        F: FnOnce(&[u8]) -> R,
    {
        let guard = self.inner.read().expect("KvStore RwLock poisoned");
        guard.get(key).map(|v| f(v.as_slice()))
    }
}

// Verify thread-safety at compile time.
// If any field were Rc or RefCell, these would not compile.
static_assertions::assert_impl_all!(KvStore: Send, Sync);

#[cfg(test)]
mod tests {
    use super::*;
    use std::thread;

    #[test]
    fn concurrent_reads_are_allowed() {
        let store = KvStore::new();
        store.insert("key".into(), b"hello world".to_vec());

        let handles: Vec<_> = (0..8).map(|_| {
            let store = store.clone(); // Clone the Arc inside; ~5ns
            thread::spawn(move || {
                let val = store.get("key").expect("key missing");
                assert_eq!(val.as_ref(), b"hello world");
            })
        }).collect();

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

    #[test]
    fn with_value_avoids_clone() {
        let store = KvStore::new();
        store.insert("greeting".into(), b"hi".to_vec());

        // No Vec<u8> is allocated; we process in-place.
        let length = store.with_value("greeting", |bytes| bytes.len());
        assert_eq!(length, Some(2));
    }
}
```

---

## Trade-offs

| Dimension | This Approach (`Arc<RwLock<HashMap<String, Arc<Vec<u8>>>>>`) | Alternative: Return cloned `Vec<u8>` |
|---|---|---|
| `get()` cost | ~5ns (atomic increment) | ~50-500ns (memcpy proportional to value size) |
| Caller holds stale data | Yes -- Arc clone is a snapshot | Yes -- same problem |
| Lifetime complexity | None -- fully owned | None -- fully owned |
| Memory usage | Slightly higher (two heap objects per entry) | Same per entry, more per read |
| Thread safety | `Send + Sync` verified by compiler | Same |
| Failure mode | `RwLock` poison on writer panic | Same |

---

## Alternatives Considered

- **`Mutex<HashMap<...>>` instead of `RwLock`**: Rejected because `Mutex` serializes all reads. Under a workload of 95% reads, `RwLock` provides significantly higher throughput. Use `parking_lot::RwLock` in production for ~2x faster lock/unlock than `std::sync::RwLock`.

- **Returning `MappedRwLockReadGuard<Vec<u8>>` from `parking_lot`**: Technically possible with `parking_lot`'s `RwLockReadGuard::map()`, which returns a guard that holds the lock open. Rejected because it forces callers to hold the read lock for the duration of their processing, reducing write throughput. Only appropriate for very short-lived access patterns.

- **`DashMap` (concurrent HashMap crate)**: A valid alternative for high-contention workloads. `DashMap` shards the map into 64 sub-maps, each with its own `RwLock`, reducing contention significantly. Appropriate when benchmarking reveals the single `RwLock` is a bottleneck. Not chosen here to keep the example dependency-free.

- **`Arc<Vec<u8>>` stored in a `Vec` with `usize` index keys**: Appropriate if keys are sequential integers rather than strings. Eliminates `HashMap` overhead (~40ns per lookup) in favor of direct index access (~1ns).