home / skills / zhanghandong / rust-skills / m12-lifecycle

m12-lifecycle skill

safe

This skill helps you design robust resource lifecycles in Rust by applying RAII, lazy init, and pooling patterns across scopes.

npx playbooks add skill zhanghandong/rust-skills --skill m12-lifecycle

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

Files (1)

SKILL.md

4.3 KB

---
name: m12-lifecycle
description: "Use when designing resource lifecycles. Keywords: RAII, Drop, resource lifecycle, connection pool, lazy initialization, connection pool design, resource cleanup patterns, cleanup, scope, OnceCell, Lazy, once_cell, OnceLock, transaction, session management, when is Drop called, cleanup on error, guard pattern, scope guard, 资源生命周期, 连接池, 惰性初始化, 资源清理, RAII 模式"
user-invocable: false
---

# Resource Lifecycle

> **Layer 2: Design Choices**

## Core Question

**When should this resource be created, used, and cleaned up?**

Before implementing lifecycle:
- What's the resource's scope?
- Who owns the cleanup responsibility?
- What happens on error?

---

## Lifecycle Pattern → Implementation

| Pattern | When | Implementation |
|---------|------|----------------|
| RAII | Auto cleanup | `Drop` trait |
| Lazy init | Deferred creation | `OnceLock`, `LazyLock` |
| Pool | Reuse expensive resources | `r2d2`, `deadpool` |
| Guard | Scoped access | `MutexGuard` pattern |
| Scope | Transaction boundary | Custom struct + Drop |

---

## Thinking Prompt

Before designing lifecycle:

1. **What's the resource cost?**
   - Cheap → create per use
   - Expensive → pool or cache
   - Global → lazy singleton

2. **What's the scope?**
   - Function-local → stack allocation
   - Request-scoped → passed or extracted
   - Application-wide → static or Arc

3. **What about errors?**
   - Cleanup must happen → Drop
   - Cleanup is optional → explicit close
   - Cleanup can fail → Result from close

---

## Trace Up ↑

To domain constraints (Layer 3):

```
"How should I manage database connections?"
    ↑ Ask: What's the connection cost?
    ↑ Check: domain-* (latency requirements)
    ↑ Check: Infrastructure (connection limits)
```

| Question | Trace To | Ask |
|----------|----------|-----|
| Connection pooling | domain-* | What's acceptable latency? |
| Resource limits | domain-* | What are infra constraints? |
| Transaction scope | domain-* | What must be atomic? |

---

## Trace Down ↓

To implementation (Layer 1):

```
"Need automatic cleanup"
    ↓ m02-resource: Implement Drop
    ↓ m01-ownership: Clear owner for cleanup

"Need lazy initialization"
    ↓ m03-mutability: OnceLock for thread-safe
    ↓ m07-concurrency: LazyLock for sync

"Need connection pool"
    ↓ m07-concurrency: Thread-safe pool
    ↓ m02-resource: Arc for sharing
```

---

## Quick Reference

| Pattern | Type | Use Case |
|---------|------|----------|
| RAII | `Drop` trait | Auto cleanup on scope exit |
| Lazy Init | `OnceLock`, `LazyLock` | Deferred initialization |
| Pool | `r2d2`, `deadpool` | Connection reuse |
| Guard | `MutexGuard` | Scoped lock release |
| Scope | Custom struct | Transaction boundaries |

## Lifecycle Events

| Event | Rust Mechanism |
|-------|----------------|
| Creation | `new()`, `Default` |
| Lazy Init | `OnceLock::get_or_init` |
| Usage | `&self`, `&mut self` |
| Cleanup | `Drop::drop()` |

## Pattern Templates

### RAII Guard

```rust
struct FileGuard {
    path: PathBuf,
    _handle: File,
}

impl Drop for FileGuard {
    fn drop(&mut self) {
        // Cleanup: remove temp file
        let _ = std::fs::remove_file(&self.path);
    }
}
```

### Lazy Singleton

```rust
use std::sync::OnceLock;

static CONFIG: OnceLock<Config> = OnceLock::new();

fn get_config() -> &'static Config {
    CONFIG.get_or_init(|| {
        Config::load().expect("config required")
    })
}
```

---

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| Resource leak | Forgot Drop | Implement Drop or RAII wrapper |
| Double free | Manual memory | Let Rust handle |
| Use after drop | Dangling reference | Check lifetimes |
| E0509 move out of Drop | Moving owned field | `Option::take()` |
| Pool exhaustion | Not returned | Ensure Drop returns |

---

## Anti-Patterns

| Anti-Pattern | Why Bad | Better |
|--------------|---------|--------|
| Manual cleanup | Easy to forget | RAII/Drop |
| `lazy_static!` | External dep | `std::sync::OnceLock` |
| Global mutable state | Thread unsafety | `OnceLock` or proper sync |
| Forget to close | Resource leak | Drop impl |

---

## Related Skills

| When | See |
|------|-----|
| Smart pointers | m02-resource |
| Thread-safe init | m07-concurrency |
| Domain scopes | m09-domain |
| Error in cleanup | m06-error-handling |

Overview

This skill helps design resource lifecycles for Rust systems, focusing on when to create, use, and clean up resources. It distills patterns like RAII, lazy initialization, pools, and scope guards into practical guidance for safe, efficient resource management. Use it to choose the right ownership, scope, and error-handling strategy before implementation.

How this skill works

The skill inspects resource cost, intended scope, and error semantics to recommend a lifecycle pattern and concrete primitives (Drop, OnceLock, LazyLock, pools, guards). It maps design choices down to implementation steps and up to domain constraints so you can align lifecycle design with latency, concurrency, and infrastructure limits. It also provides templates and common fixes for leaks, double frees, and pool exhaustion.

When to use it

Deciding where and when a resource should be created and who cleans it up.
Designing connection pools, lazy singletons, or expensive cached resources.
Implementing transaction or request-scoped boundaries that need deterministic cleanup.
Choosing between automatic cleanup (RAII) and explicit close semantics.
Handling cleanup on error or when cleanup itself can fail.

Best practices

Prefer RAII (Drop) for guaranteed cleanup on scope exit; wrap resources in small guard structs.
Use OnceLock/LazyLock for thread-safe lazy initialization instead of global mutable state.
Pool expensive resources and ensure returned items are dropped/returned consistently to avoid exhaustion.
Design clear ownership: who calls close vs who relies on Drop; avoid ambiguous manual cleanup.
Model cleanup failures explicitly (return Result from close) when the cleanup can meaningfully fail.

Example use cases

Temp file or socket wrapper that deletes the file in Drop (RAII guard).
Application-wide config loaded once via OnceLock::get_or_init (lazy singleton).
Database connection pool using r2d2/deadpool with Arc sharing and Drop-aware checkout guards.
Transaction boundary implemented as a scope-guard struct that commits or rolls back in Drop.
Request-scoped session objects passed through handlers and dropped at request end.

FAQ

When should I implement Drop vs. provide an explicit close method?

Use Drop for mandatory cleanup that must always run on scope exit. Provide explicit close when cleanup can fail or when users should control timing; you can combine both (Drop calls close and ignores non-critical errors).

How do I avoid pool exhaustion?

Ensure checkout objects return to the pool in Drop or via explicit return. Use timeouts, capacity limits, and monitoring. Design fallbacks for when the pool is exhausted (queue, scale, or fail fast).