Skip to content
Linux Systems Field Manual

linux/rust/kernel/sync/arc.rs

Imported from _research/manual-study-linux/file-notes/linux__rust__kernel__sync__arc.rs.md.

File Notes: rust/kernel/sync/arc.rs

Status: reviewed.

Purpose

rust/kernel/sync/arc.rs implements kernel-specific reference-counted ownership for Rust code. It resembles std::sync::Arc, but adapts to kernel constraints: kernel refcounts, no weak references, saturation, implicit pinning, and no get_mut.

Key Types And Functions

  • Arc<T>: shared pinned reference-counted ownership.
  • ArcInner<T>: allocation layout containing Refcount plus data.
  • ArcBorrow<'a, T>: borrowed handle that avoids double indirection while still allowing conversion back to Arc.
  • UniqueArc<T>: refcounted allocation known to have exactly one reference.
  • Arc::new, Arc::from_raw, Arc::into_raw, Arc::as_arc_borrow, Arc::into_unique_or_drop.
  • UniqueArc::new, UniqueArc::new_uninit, write, assume_init, init_with, and pin_init_with.

Data Flow

Arc::new creates an ArcInner with Refcount::new(1), allocates it with KBox, leaks the box, and creates an Arc from the non-null inner pointer. Cloning increments the refcount and constructs another Arc owning that new count. Dropping decrements the count and frees the allocation only when the count reaches zero.

ArcBorrow does not own a count. It borrows a valid inner pointer for a lifetime and can be converted into an owned Arc by temporarily constructing an Arc view, preventing drop of the temporary, and cloning.

UniqueArc wraps an Arc whose inner refcount is known to be one. It allows mutation and staged initialization before converting to shared Arc.

Invariants And Safety Contracts

  • Arc refcount is always non-zero while an Arc exists.
  • Arc data is always pinned.
  • Arc<T> is Send and Sync only when T: Sync + Send.
  • from_inner, from_raw, and ArcBorrow::from_raw require callers to prove pointer origin and lifetime/refcount validity.
  • ArcBorrow forbids mutable references to the underlying allocation while the borrow exists.
  • UniqueArc requires the inner refcount to stay exactly one.
  • assume_init is immediate undefined behavior if called before initialization.

Rust Translation Guidance

A Rust kernel needs multiple ownership forms, not only Arc<T>:

  • shared pinned ownership for normal kernel objects;
  • borrowed refcount-capable handles for hot paths;
  • unique pre-publication ownership for initialization and mutation;
  • explicit unsafe conversion APIs for FFI boundaries.

This file is also a strong argument for designing kernel objects around typestate: uninitialized, unique initialized, pinned unique, and shared pinned states should be distinct types.

AI-Native Systems Guidance

Agent-visible resources should carry ownership state explicitly. An AI runtime should distinguish “borrowed view”, “unique editable object”, and “shared published object” instead of treating all handles as equivalent. That gives agents safer edit/apply semantics and makes provenance checks easier.

Evidence

  • rust/kernel/sync/arc.rs:3-15: kernel-specific differences from standard Arc.
  • rust/kernel/sync/arc.rs:41-50: Arc purpose and invariants.
  • rust/kernel/sync/arc.rs:130-149: Arc and ArcInner layout.
  • rust/kernel/sync/arc.rs:185-196: Send / Sync safety contracts.
  • rust/kernel/sync/arc.rs:218-236: allocation and initial refcount setup.
  • rust/kernel/sync/arc.rs:239-286: raw pointer conversion contracts.
  • rust/kernel/sync/arc.rs:340-361: unique conversion with race-aware refcount handling.
  • rust/kernel/sync/arc.rs:445-470: clone/drop refcount behavior.
  • rust/kernel/sync/arc.rs:485-610: ArcBorrow purpose, invariants, and conversion.
  • rust/kernel/sync/arc.rs:614-688: UniqueArc purpose and examples.
  • rust/kernel/sync/arc.rs:736-843: UniqueArc allocation, initialization, pinning, and mutable access.