What to do when the design wants a struct that owns data and holds references into it, or a graph whose nodes point at each other: the cases plain lifetimes cannot express. Choose the simplest option that works; reach for crates only when ownership-based designs are clearly worse.
Contents
- Why self-reference cannot be written
- Option 1: store offsets or ranges
- Option 2: split owner and view
- Option 3: own the pieces
- Option 4: arenas and indices
- Option 5:
Rc/Arcgraphs withWeak - Option 6: crates built for self-reference
Pinis not a lifetime tool- Decision table
Why self-reference cannot be written
struct Doc {
text: String,
words: Vec<&'??? str>, // no lifetime names "borrowed from my own `text` field"
}Even with a lifetime parameter (struct Doc<'a> { text: String, words: Vec<&'a str> }), you cannot construct
it: words would borrow text while text is being moved into the struct, and moving a Doc later would
move the String (its heap buffer stays put, but the type system cannot know that). The compiler rejects
every attempt with E0505/E0597; the fix is a different shape, not a different lifetime.
Option 1: store offsets or ranges
The cheapest and most robust: keep the owner, store positions instead of references, borrow on demand.
use std::ops::Range;
struct Doc {
text: String,
words: Vec<Range<usize>>,
}
impl Doc {
fn parse(text: String) -> Doc {
let mut words = Vec::new();
let mut start = None;
for (i, c) in text.char_indices() {
match (c.is_whitespace(), start) {
(false, None) => start = Some(i),
(true, Some(s)) => { words.push(s..i); start = None; }
_ => {}
}
}
if let Some(s) = start { words.push(s..text.len()); }
Doc { text, words }
}
fn words(&self) -> impl Iterator<Item = &str> + '_ {
self.words.iter().map(|r| &self.text[r.clone()])
}
}
fn main() {
let d = Doc::parse("owned text survives moves".to_string());
let moved = d; // moving is fine: ranges stay valid
assert_eq!(moved.words().nth(1), Some("text"));
}Ranges cost 16 bytes each on 64-bit targets (a Range<u32> halves that for inputs under 4 GiB).
Option 2: split owner and view
Let the caller own the data and build a borrowing view next to it. This is how most zero-copy parsers work.
struct Tokens<'a> {
words: Vec<&'a str>,
}
impl<'a> Tokens<'a> {
fn new(text: &'a str) -> Self {
Tokens { words: text.split_whitespace().collect() }
}
}
fn main() {
let text = std::fs::read_to_string("Cargo.toml").unwrap_or_else(|_| "a b c".into()); // owner
let tokens = Tokens::new(&text); // view
println!("{} words", tokens.words.len());
}The cost: two values instead of one, and the view cannot outlive the owner (cannot be returned from the function that created the owner, or stored in a long-lived struct).
Option 3: own the pieces
Allocate per piece: Vec<String>, or Arc<str> when pieces are shared. Simplest code, more allocations.
Fine for configs, CLI arguments, error messages and anything not on a hot path.
use std::sync::Arc;
struct Record { fields: Vec<Arc<str>> }
fn parse(line: &str) -> Record {
Record { fields: line.split(',').map(Arc::from).collect() }
}Option 4: arenas and indices
For graphs and trees (parent pointers, cycles), store nodes in a Vec and link by index. A typed index keeps
ids from different arenas apart.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct NodeId(usize);
struct Node { label: String, parent: Option<NodeId>, children: Vec<NodeId> }
#[derive(Default)]
struct Tree { nodes: Vec<Node> }
impl Tree {
fn add(&mut self, label: &str, parent: Option<NodeId>) -> NodeId {
let id = NodeId(self.nodes.len());
self.nodes.push(Node { label: label.into(), parent, children: vec![] });
if let Some(p) = parent { self.nodes[p.0].children.push(id); }
id
}
fn depth(&self, mut id: NodeId) -> usize {
let mut d = 0;
while let Some(p) = self.nodes[id.0].parent { d += 1; id = p; }
d
}
}When nodes are removed, use generational indices (slotmap, thunderdome) so stale ids are detected. A
bump arena such as bumpalo or typed-arena gives real references &'arena Node that may point at each
other, all freed together; the arena's lifetime is then the only one in the API.
Option 5: Rc/Arc graphs with Weak
Shared ownership with runtime-checked mutation. Use Weak for back edges to avoid leaks from cycles.
use std::cell::RefCell;
use std::rc::{Rc, Weak};
struct Node {
name: String,
parent: RefCell<Weak<Node>>,
children: RefCell<Vec<Rc<Node>>>,
}
fn link(parent: &Rc<Node>, child: Rc<Node>) {
*child.parent.borrow_mut() = Rc::downgrade(parent);
parent.children.borrow_mut().push(child);
}
fn main() {
let root = Rc::new(Node { name: "root".into(), parent: RefCell::new(Weak::new()), children: RefCell::new(vec![]) });
let leaf = Rc::new(Node { name: "leaf".into(), parent: RefCell::new(Weak::new()), children: RefCell::new(vec![]) });
link(&root, leaf.clone());
assert_eq!(leaf.parent.borrow().upgrade().map(|p| p.name.clone()), Some("root".to_string()));
}Costs: a heap allocation per node, refcount traffic, possible BorrowMutError panics, more verbose code.
Prefer the arena unless nodes really have independent owners.
Option 6: crates built for self-reference
| Crate | Approach | Good for |
|---|---|---|
self_cell | declarative macro, owner + dependent in one value, no proc macro | "owned text + parsed view" in one struct |
ouroboros | proc macro generating builders and accessors | several borrowed fields; heavier compile |
yoke | Yoke<Y, C>: a zero-copy deserialized value plus its backing cart (Rc<[u8]>, Arc) | caching parsed data from owned buffers (ICU4X) |
owning_ref | historical; has known soundness issues | do not use in new code |
// self_cell: one value that owns the text and a view into it.
use self_cell::self_cell;
struct Ast<'a>(Vec<&'a str>);
self_cell!(
struct OwnedAst {
owner: String,
#[covariant]
dependent: Ast,
}
);
let ast = OwnedAst::new("a b c".to_string(), |s| Ast(s.split(' ').collect()));
assert_eq!(ast.borrow_dependent().0.len(), 3);Hand-rolled unsafe with raw pointers into your own fields is easy to get wrong (moves, drops, variance);
use a crate whose soundness has been reviewed.
Pin is not a lifetime tool
Pin<P> promises that a value will not move again, which async state machines need (a future may hold
references into its own fields across .await). It does not let your structs borrow from themselves in
safe code, and it does not change lifetimes. You meet it when implementing Future/Stream by hand (use
pin-project-lite for field projection) or when boxing futures (Pin<Box<dyn Future + 'a>>).
Decision table
| Need | Choose |
|---|---|
| Owned buffer + positions into it, value is moved around | ranges/offsets (Option 1) |
| Short-lived processing of caller-owned input | owner + view (Option 2) |
| Small or infrequent data, simplicity first | own the pieces, Arc<str> for sharing (Option 3) |
| Trees/graphs with parent links or cycles | arena + typed indices; slotmap if nodes are removed (Option 4) |
| Nodes with independent owners across the program | Rc/Arc + Weak back edges (Option 5) |
| One value that must own data and expose a borrowed view, and options 1-3 are clearly worse | self_cell / yoke (Option 6) |
rust-borrow-checker-error-explainer
Explain and fix Rust borrow-checker, ownership, move and lifetime compiler errors: E0382 use of moved value, E0499 cannot borrow as mutable more than once, E0502 also borrowed as immutable, E0505, E0506, E0503, E0507 cannot move out of index/Rc/reference, E0515 return reference to local, E0597 does not live long enough, E0716 temporary value dropped while borrowed, E0373 closure may outlive (spawn needs move), E0521 borrowed data escapes, E0384, E0596, E0594, E0381, E0713, 'lifetime may not live long enough', RefCell 'already borrowed: BorrowMutError' panics. Ranks fixes from restructuring (split borrows, entry API, split_at_mut, get_disjoint_mut, mem::take, Option::take, indices, thread::scope) down to clone and Rc<RefCell>/Arc<Mutex>; never unsafe. Covers NLL limits (get-or-insert), iterator invalidation, closure captures, self-referential structs. Ships std-only Rust triage tools.
rust-cargo-workspace-designer
Design, review and fix Cargo workspaces: when to split a crate (compile time, boundaries, publishing, proc-macros), crates/* vs apps/ + crates/ layouts, virtual manifest vs root package, members/exclude/default-members, resolver 2 vs 3 (MSRV-aware, edition 2024), [workspace.package] and [workspace.dependencies] inheritance, [workspace.lints], root-only profiles (lto, codegen-units), additive features with dep: and weak ?/ syntax, feature unification pitfalls, internal path + version deps, publish = false, Cargo.lock and MSRV policy, xtask, CI with --locked, nextest, rust-cache, sccache, cargo-hack/deny/machete/udeps/semver-checks, and cargo build --timings. Ships a workspace auditor and crate-graph tool.
rust-error-handling-thiserror-anyhow-designer
Design and review Rust error handling with thiserror 2 and anyhow 1: library vs application split, typed error enums with #[from], #[source], #[error(transparent)] and #[non_exhaustive], ErrorKind patterns, context via .context()/.with_context(), bail!/ensure!, source() chains, {:#} and {:?} reports, RUST_BACKTRACE/RUST_LIB_BACKTRACE, Box<dyn Error + Send + Sync>, main -> anyhow::Result or ExitCode, unwrap/expect/panic policy, Option to Result, collecting iterators of Results, axum IntoResponse mapping, retryable errors, tracing, async Send bounds, testing with matches! and downcast_ref, no_std core::error::Error, and snafu, eyre/color-eyre, miette, error-stack.
rust-tokio-async-service-builder
Build and review production async Rust services on Tokio 1.x and axum 0.8: runtime choice (#[tokio::main] multi_thread vs current_thread, Builder), axum routing with /{id} paths, State, extractors, IntoResponse error types, axum::serve with_graceful_shutdown, tower/tower-http middleware (TraceLayer, TimeoutLayer, CorsLayer, ConcurrencyLimitLayer, RequestBodyLimitLayer), Arc<AppState>, std vs tokio Mutex, JoinSet, TaskTracker, CancellationToken, select! cancel safety, bounded mpsc, oneshot, broadcast, watch, actors, Semaphore, timeouts, retries, spawn_blocking, sqlx PgPool, reqwest Client reuse, tracing, tests with start_paused and oneshot, Dockerfile. Fixes 'future cannot be sent between threads safely', E0373, Rc or MutexGuard held across await, 'Cannot start a runtime from within a runtime', 'Path segments must not start with :'. Ships std-only Rust scanners and a compiling axum 0.8 scaffold.
rust-trait-design-reviewer
Review and design Rust traits and generic APIs: generics vs impl Trait vs dyn Trait (static vs dynamic dispatch), dyn compatibility / object safety (generic methods, Self returns, where Self: Sized, error[E0038] not dyn compatible / cannot be made into an object), associated types vs generic parameters, blanket impls, coherence and orphan rule (E0117, E0119, E0210), newtype, extension, sealed and marker traits, supertraits and trait upcasting (1.86), async fn in traits (1.75) and the Send bound problem (trait_variant, async-trait), RPITIT, GATs, From/Into/TryFrom/AsRef/Borrow, std trait checklist (Debug, Clone, PartialEq, Hash, Default, Display, Error, Send/Sync, serde feature), #[must_use], #[non_exhaustive], semver hazards, Deref abuse, builders, typestate, PhantomData, Box<dyn Error + Send + Sync>, Fn traits, mockall.
rust-unsafe-block-auditor
Audit unsafe Rust for soundness: inventory every unsafe block, unsafe fn, unsafe impl/trait, extern block and unsafe attribute, check // SAFETY: comments and # Safety docs, and classify each as sound, needs-justification or likely UB, proposing safe alternatives first. Covers the five unsafe superpowers, aliasing (Stacked/Tree Borrows), invalid values, MaybeUninit vs mem::zeroed/uninitialized, transmute, slice::from_raw_parts, Vec::set_len/from_raw_parts, get_unchecked, CString::as_ptr dangling, unsafe impl Send/Sync, Pin projection, FFI (extern "C", repr(C), C-unwind, Box::into_raw/from_raw), strict provenance, static mut and &raw, edition 2024 (unsafe extern, #[unsafe(no_mangle)], unsafe_op_in_unsafe_fn, env::set_var), Miri, sanitizers, cargo-fuzz, loom, cargo-geiger and clippy safety lints.