Skip to content
v0.1.1latest release34 skills2 categories4 sub-categories79 tested scripts157 reference docsContact us

Self-Referential Structs and Escape Hatches

Reference for rust-lifetime-annotation-advisor · 224 lines

Programming / Rustv1.0.0Updated OCT 21 20267 references6 scripts

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

rust
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.

rust
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.

rust
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.

rust
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.

rust
#[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.

rust
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

CrateApproachGood for
self_celldeclarative macro, owner + dependent in one value, no proc macro"owned text + parsed view" in one struct
ouroborosproc macro generating builders and accessorsseveral borrowed fields; heavier compile
yokeYoke<Y, C>: a zero-copy deserialized value plus its backing cart (Rc<[u8]>, Arc)caching parsed data from owned buffers (ICU4X)
owning_refhistorical; has known soundness issuesdo not use in new code
rust
// 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

NeedChoose
Owned buffer + positions into it, value is moved aroundranges/offsets (Option 1)
Short-lived processing of caller-owned inputowner + view (Option 2)
Small or infrequent data, simplicity firstown the pieces, Arc<str> for sharing (Option 3)
Trees/graphs with parent links or cyclesarena + typed indices; slotmap if nodes are removed (Option 4)
Nodes with independent owners across the programRc/Arc + Weak back edges (Option 5)
One value that must own data and expose a borrowed view, and options 1-3 are clearly worseself_cell / yoke (Option 6)
More in Rust

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.