playbooks

home / skills / zhanghandong / rust-skills / m02-resource

m02-resource skill

/skills/m02-resource

This skill helps you select appropriate Rust smart pointers for resource management, guiding ownership, threading, and cycle avoidance.

npx playbooks add skill zhanghandong/rust-skills --skill m02-resource

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.3 KB
---
name: m02-resource
description: "CRITICAL: Use for smart pointers and resource management. Triggers: Box, Rc, Arc, Weak, RefCell, Cell, smart pointer, heap allocation, reference counting, RAII, Drop, should I use Box or Rc, when to use Arc vs Rc, 智能指针, 引用计数, 堆分配"
user-invocable: false
---

# Resource Management

> **Layer 1: Language Mechanics**

## Core Question

**What ownership pattern does this resource need?**

Before choosing a smart pointer, understand:
- Is ownership single or shared?
- Is access single-threaded or multi-threaded?
- Are there potential cycles?

---

## Error → Design Question

| Error | Don't Just Say | Ask Instead |
|-------|----------------|-------------|
| "Need heap allocation" | "Use Box" | Why can't this be on stack? |
| Rc memory leak | "Use Weak" | Is the cycle necessary in design? |
| RefCell panic | "Use try_borrow" | Is runtime check the right approach? |
| Arc overhead complaint | "Accept it" | Is multi-thread access actually needed? |

---

## Thinking Prompt

Before choosing a smart pointer:

1. **What's the ownership model?**
   - Single owner → Box or owned value
   - Shared ownership → Rc/Arc
   - Weak reference → Weak

2. **What's the thread context?**
   - Single-thread → Rc, Cell, RefCell
   - Multi-thread → Arc, Mutex, RwLock

3. **Are there cycles?**
   - Yes → One direction must be Weak
   - No → Regular Rc/Arc is fine

---

## Trace Up ↑

When pointer choice is unclear, trace to design:

```
"Should I use Arc or Rc?"
    ↑ Ask: Is this data shared across threads?
    ↑ Check: m07-concurrency (thread model)
    ↑ Check: domain-* (performance constraints)
```

| Situation | Trace To | Question |
|-----------|----------|----------|
| Rc vs Arc confusion | m07-concurrency | What's the concurrency model? |
| RefCell panics | m03-mutability | Is interior mutability right here? |
| Memory leaks | m12-lifecycle | Where should cleanup happen? |

---

## Trace Down ↓

From design to implementation:

```
"Need single-owner heap data"
    ↓ Use: Box<T>

"Need shared immutable data (single-thread)"
    ↓ Use: Rc<T>

"Need shared immutable data (multi-thread)"
    ↓ Use: Arc<T>

"Need to break reference cycle"
    ↓ Use: Weak<T>

"Need shared mutable data"
    ↓ Single-thread: Rc<RefCell<T>>
    ↓ Multi-thread: Arc<Mutex<T>> or Arc<RwLock<T>>
```

---

## Quick Reference

| Type | Ownership | Thread-Safe | Use When |
|------|-----------|-------------|----------|
| `Box<T>` | Single | Yes | Heap allocation, recursive types |
| `Rc<T>` | Shared | No | Single-thread shared ownership |
| `Arc<T>` | Shared | Yes | Multi-thread shared ownership |
| `Weak<T>` | Weak ref | Same as Rc/Arc | Break reference cycles |
| `Cell<T>` | Single | No | Interior mutability (Copy types) |
| `RefCell<T>` | Single | No | Interior mutability (runtime check) |

## Decision Flowchart

```
Need heap allocation?
├─ Yes → Single owner?
│        ├─ Yes → Box<T>
│        └─ No → Multi-thread?
│                ├─ Yes → Arc<T>
│                └─ No → Rc<T>
└─ No → Stack allocation (default)

Have reference cycles?
├─ Yes → Use Weak for one direction
└─ No → Regular Rc/Arc

Need interior mutability?
├─ Yes → Thread-safe needed?
│        ├─ Yes → Mutex<T> or RwLock<T>
│        └─ No → T: Copy? → Cell<T> : RefCell<T>
└─ No → Use &mut T
```

---

## Common Errors

| Problem | Cause | Fix |
|---------|-------|-----|
| Rc cycle leak | Mutual strong refs | Use Weak for one direction |
| RefCell panic | Borrow conflict at runtime | Use try_borrow or restructure |
| Arc overhead | Atomic ops in hot path | Consider Rc if single-threaded |
| Box unnecessary | Data fits on stack | Remove Box |

---

## Anti-Patterns

| Anti-Pattern | Why Bad | Better |
|--------------|---------|--------|
| Arc everywhere | Unnecessary atomic overhead | Use Rc for single-thread |
| RefCell everywhere | Runtime panics | Design clear ownership |
| Box for small types | Unnecessary allocation | Stack allocation |
| Ignore Weak for cycles | Memory leaks | Design parent-child with Weak |

---

## Related Skills

| When | See |
|------|-----|
| Ownership errors | m01-ownership |
| Interior mutability details | m03-mutability |
| Multi-thread context | m07-concurrency |
| Resource lifecycle | m12-lifecycle |

Overview

This skill guides smart pointer and resource management decisions in Rust. It helps you pick between Box, Rc, Arc, Weak, Cell, and RefCell based on ownership, threading, and potential reference cycles. It focuses on practical trade-offs and common pitfalls to prevent leaks, panics, and unnecessary overhead.

How this skill works

The skill inspects the ownership model, thread context, and mutability needs to recommend appropriate smart pointers. It traces from high-level design questions (single vs shared ownership, single- vs multi-threaded) down to concrete types and compositions (e.g., Rc<RefCell<T>> vs Arc<Mutex<T>>). It highlights failure modes and suggests checks or alternatives when common errors appear.

When to use it

  • Need heap allocation for a single owner or recursive type → consider Box<T>.
  • Shared ownership on a single thread → use Rc<T>.
  • Shared ownership across threads → use Arc<T>.
  • Need to break cycles → introduce Weak<T> on one direction.
  • Require interior mutability: single-thread → Cell/RefCell, multi-thread → Mutex/RwLock inside Arc.

Best practices

  • Always identify the ownership model first: single owner, shared, or weak reference.
  • Determine thread context early; default to Rc and RefCell for single-threaded code to avoid atomic overhead.
  • Avoid using Arc everywhere—accept the cost only if true cross-thread sharing is required.
  • Break potential cycles by converting one strong reference to Weak to prevent leaks.
  • Prefer stack allocation and plain values until heap allocation is justified; don’t Box small types unnecessarily.

Example use cases

  • Storing a recursive AST node: use Box<T> for child pointers to avoid infinite size.
  • Shared configuration data accessed only on the main thread: use Rc<T> to share immutable data.
  • Shared cache accessed by worker threads: use Arc<T> for safe cross-thread sharing.
  • Parent-child graph where children hold references back to parent: use Weak<T> for the parent link to avoid cycles.
  • Mutable shared state in a single-threaded GUI: use Rc<RefCell<T>> for interior mutability without locks.

FAQ

When should I choose Rc over Arc?

Pick Rc when data is shared only within one thread; Rc has no atomic overhead. Choose Arc when the data must be shared safely across threads.

How do I avoid RefCell panics at runtime?

Prefer static ownership where possible. If runtime borrow conflicts may happen, use try_borrow/try_borrow_mut to handle failures or redesign to use Mutex/RwLock for explicit synchronization.