UmbraPointer<T>, UmbraOwner<T>, ArcUmbra<T>

A generic content-prefixed pointer that fits in one XMM register (16 bytes: 8-byte pointer + 4-byte content prefix + 4-byte padding). Equality and lookup operations check the 4-byte prefix in-register before touching the pointed-to allocation. For workloads where most candidates miss (HashMap bucket walks, dedup scans, RDF subject lookups, scattered large-payload accesses), the prefix shortcircuits the deref and eliminates the cache miss on the target.

The generic version of the Umbra-strings prefix trick. The Umbra paper (Neumann + Freitag, CIDR 2020) introduced 16-byte string pointers that pack a 4-byte content prefix alongside the pointer to enable in-register equality fast-rejection. This primitive is the same idea, parameterised over any T instead of just &str; it works for any heap-allocated payload. The MMF-resident sibling for cross-process use is SharedUmbraPointer .

Constraints (read first):

• In-process only. target: *const T is a raw machine address; the pointer is not portable across processes. For cross-process Umbra-style pointers, see SharedUmbraPointer .
• T: Sized. The struct stores a thin pointer (*const T, exactly 8 bytes). Unsized targets ([u8], str, dyn Trait) require wrapping in a sized container (Box<[u8]>, Arc<str>, etc.) at the application layer first.
• UmbraPointer::from_raw is unsafe. Caller is responsible for keeping the target alive AND for choosing a prefix that is a deterministic function of the content; arbitrary prefixes make prefix_eq semantically meaningless. The safe entry points are with_content_prefix (returns Box<UmbraOwner<T>>), with_hash_prefix (same), and from_arc (returns ArcUmbra<T>).
• with_content_prefix reads T’s first 4 bytes in native byte order. On a little-endian host the prefix is the low-address 4 bytes; on big-endian it is the high-address 4 bytes. The same T value produces different prefixes on hosts of opposite endianness. Persistence and cross-host workflows must use with_hash_prefix or from_raw with an explicit deterministic hash.
• with_hash_prefix uses std::collections::hash_map::DefaultHasher, truncated to the low 32 bits. DefaultHasher may be randomized per process in some Rust versions. Two processes hashing the same content may compute different prefixes; this is NOT a content-addressing-stable hash.
• Prefix is 4 bytes (32 bits). Birthday-bound collision probability is ~50% at ~65 K distinct prefixes. Treat prefix-equality as a candidate-filter, not a definitive content-match.
• UmbraOwner<T> is returned wrapped in a Box. Both with_content_prefix and with_hash_prefix return Box<UmbraOwner<T>>, not a raw UmbraOwner<T>. The Box is the RAII handle; dropping it runs UmbraOwner::drop, which reclaims the heap allocation via Box::from_raw.

Table of contents

• What they are
• When to reach for it
• Memory layout
• Three construction modes
• The skip-on-mismatch protocol
• API at a glance
• Worked example
• Benchmark results
• Where Umbra wins, where it loses
• Use case patterns
• Known limitations (verified)
• Common pitfalls

What they are

UmbraPointer<T> is the raw 16-byte slot:

#[repr(C, align(16))]
pub struct UmbraPointer<T> {
    target: *const T,      // offset 0..8  (8 bytes)
    prefix: u32,           // offset 8..12 (4 bytes)
    _pad: u32,             // offset 12..16 (explicit padding to 16)
    _phantom: PhantomData<T>,
}

The pointer is laid out so the target occupies bytes 0..8 (the natural pointer-alignment slot) and the prefix occupies bytes 8..12 with explicit _pad filling the 16-byte slot. SIMD scans over an array of UmbraPointer<T> see consistent prefix-byte positions at offset 8 in every slot, enabling a packed-quadword gather on the prefix half-register.

UmbraOwner<T> is the RAII wrapper for the Box-heap path: it owns the pointed-to allocation, with Drop that reclaims it via Box::from_raw:

pub struct UmbraOwner<T> {
    ptr: UmbraPointer<T>,
}

ArcUmbra<T> is the RAII wrapper for the Arc-sharing path: the Arc<T> keeps the target alive; ArcUmbra::Clone bumps the Arc’s reference count:

pub struct ArcUmbra<T> {
    ptr: UmbraPointer<T>,
    _arc: Arc<T>,
}

The three types compose: UmbraPointer<T> is the bare 16-byte fact, UmbraOwner<T> and ArcUmbra<T> are the two safe entry points for constructing one with a managed target lifetime.

When to reach for it

Reach for UmbraPointer<T> (via UmbraOwner or ArcUmbra) when:

• The workload does scans over collections of pointers looking for a match; most candidates miss; the candidate test is cheap but the deref of T is expensive.
• Deref-and-compare on T would touch a separate cache line per pointer (large payloads, scattered allocations, no prefetch). The 16-byte slot keeps the prefix scan dense; only the rare prefix-hit pays the cache-miss cost.
• The data structure is a HashMap bucket chain, a dedup set, or an RDF/triple-store subject index where the expected miss rate is high (most lookups walk past most candidates).
• You need a deterministic content-derived prefix for fast rejection and you control the hash function. with_hash_prefix is convenient but not cross-host stable; for persistence, construct via from_raw with an explicit hash.

Reach for something else when:

• The payload is small (a few bytes). The deref is free; the prefix scan is overhead. See the cache_pressure bench loss (0.69x) below for the quantified case.
• The workload accesses elements sequentially with high hit rate (e.g. Vec<T> iteration where every element is processed). The shortcircuit never fires; the prefix becomes dead weight.
• You need cross-process visibility. Use an MMF-backed primitive instead.
• You need cryptographically-stable content-addressing. DefaultHasher is not cryptographic; supply your own via from_raw.

Memory layout

    flowchart LR
    subgraph XMM["UmbraPointer: 16 bytes (one XMM register)"]
      direction LR
      T["bytes 0..8<br/>*const T<br/>(machine address)"]
      P["bytes 8..12<br/>prefix (u32)<br/>content-derived"]
      Q["bytes 12..16<br/>_pad (u32)<br/>explicit padding"]
    end

    classDef ptr fill:#1e3a8a,stroke:#1e40af,color:#ffffff
    classDef pre fill:#7c3aed,stroke:#5b21b6,color:#ffffff
    classDef pad fill:#6b7280,stroke:#374151,color:#ffffff
    class T ptr
    class P pre
    class Q pad
  

The explicit _pad: u32 field is what gives UmbraPointer<T> its 16-byte size regardless of T. Without it, Rust would size the struct to sizeof(ptr) + sizeof(u32) = 12 bytes (with 4-byte trailing alignment to the next u32 boundary), which would make every slot 12 bytes - awkward for SIMD scans because slots would not be 16-aligned in an array.

The pointer occupies bytes 0..8 (its natural 8-byte alignment slot); the prefix sits at bytes 8..12. A SIMD scan that loads one slot per XMM register sees the prefix in the high half of the register, in a position consistent across all slots in the array.

Three construction modes

    flowchart TD
    Start([want UmbraPointer]) --> Has{Have value of T?}
    Has -->|yes, want exclusive ownership| Mode1[with_content_prefix<br/>or<br/>with_hash_prefix]
    Has -->|yes, have Arc already| Mode2[from_arc<br/>caller supplies prefix]
    Has -->|already have raw ptr| Mode3[from_raw<br/>unsafe, caller owns lifetime]
    Mode1 --> Owner[Box of UmbraOwner T<br/>RAII frees on drop]
    Mode2 --> Arc[ArcUmbra T<br/>Arc keeps target alive]
    Mode3 --> Bare[UmbraPointer T<br/>caller manages lifetime]

    classDef startend fill:#0e7490,stroke:#0e7490,color:#ffffff
    classDef decision fill:#fbbf24,stroke:#92400e,color:#1f2937
    classDef mode fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef out fill:#059669,stroke:#065f46,color:#ffffff
    class Start startend
    class Has decision
    class Mode1,Mode2,Mode3 mode
    class Owner,Arc,Bare out
  

The skip-on-mismatch protocol

    flowchart TD
    Start([scan candidates]) --> Next[next candidate]
    Next --> Mp{matches_prefix?<br/>4-byte compare}
    Mp -->|no| Skip[SKIP<br/>no deref; no cache miss]
    Skip --> More{more candidates?}
    More -->|yes| Next
    More -->|no| Done([scan complete])
    Mp -->|yes| Deref[load *target<br/>cache miss possible]
    Deref --> Check{full equality?}
    Check -->|no, false positive| More
    Check -->|yes, true match| Hit([Found!])

    classDef startend fill:#0e7490,stroke:#0e7490,color:#ffffff
    classDef decision fill:#fbbf24,stroke:#92400e,color:#1f2937
    classDef action fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef skip fill:#059669,stroke:#065f46,color:#ffffff
    classDef hit fill:#b91c1c,stroke:#7f1d1d,color:#ffffff
    class Start,Done,Hit startend
    class Mp,More,Check decision
    class Next,Deref action
    class Skip skip
  

The architectural win is eliminating dereferences whose target is on a cold cache line. The 16-byte slot ensures the scan itself stays dense (one cache line covers 4 slots); only the prefix-hit path pays the cost of loading the target’s bytes.

When the prefix is content-derived AND the target is unpredictable (scattered heap allocations, no prefetch), this turns into a multi-x speedup. When the target is small or always in cache, the shortcircuit adds overhead without saving anything.

API at a glance

Worked example

use std::sync::Arc;
use subetha_pointers::umbra_pointer::{ArcUmbra, UmbraPointer};

// 1024 records, each with a 4-byte hash prefix and 8-byte payload.
// Build them as ArcUmbras so they can be cloned cheaply.
let records: Vec<ArcUmbra<u64>> = (0..1024u64)
    .map(|i| {
        let arc = Arc::new(i * 1000);
        let prefix = (i ^ 0xDEAD_BEEF) as u32;  // content-derived hash
        UmbraPointer::from_arc(arc, prefix)
    })
    .collect();

// Lookup a record by prefix. The 4-byte compare runs against all
// 1024 candidates in O(N); most miss without dereferencing.
let query_prefix = (777u64 ^ 0xDEAD_BEEF) as u32;
let mut hits = 0;
for r in records.iter() {
    if r.ptr().matches_prefix(query_prefix) {
        // Only deref when prefix matches. For a 32-bit prefix
        // over 1024 entries, false-positive probability is
        // ~1024 / 2^32 = negligible.
        if *r.value() == 777_000 {
            hits += 1;
        }
    }
}
assert_eq!(hits, 1);

// Box-owned variant. The Box<UmbraOwner<T>> manages the target
// lifetime; drop the Box, the inner Box is freed.
let owner = UmbraPointer::with_content_prefix(0xCAFE_BABE_DEAD_BEEF_u64);
// On little-endian: first 4 bytes of u64 are 0xEF 0xBE 0xAD 0xDE
// -> u32 = 0xDEAD_BEEF.
assert_eq!(owner.prefix(), 0xDEAD_BEEF);
assert_eq!(*owner.value(), 0xCAFE_BABE_DEAD_BEEF_u64);

Benchmark results

Baseline: a Vec<Arc<T>> of 1024 entries, scanned in a loop with **arc == query per candidate. The Umbra path uses Vec<ArcUmbra<T>> and matches_prefix(query_prefix) before any deref.

Bench: crates/subetha-pointers/benches/umbra_pointer.rs. Measured on Windows 11 / Zen+ R7 2700, criterion at --measurement-time 2 --warm-up-time 1 --sample-size 30 (middle estimate of each [low, mid, high] triple).

Why each result lands where it does

Where Umbra wins, where it loses

Two-axis decision matrix:

The “low miss rate, small payload” cell is the failure mode - avoid UmbraPointer there. Everything else is a candidate.

Use case patterns

for triple in ingest_stream {
    let prefix = hash_subject(&triple.subject) as u32;
    if !subjects.iter().any(|s| s.matches_prefix(prefix)
                              && s.value() == &triple.subject) {
        // new subject; allocate via with_hash_prefix
        subjects.push(*UmbraPointer::with_hash_prefix(triple.subject.clone()));
    }
}

Known limitations (verified)

1. UmbraPointer<T> is in-process only. The target field is a raw machine address. Cross-process storage requires layering this over MMF and using OffsetPtr for the cross-process leg.

2. from_raw is unsafe. No lifetime tracking; caller must guarantee the target outlives the pointer AND must supply a prefix derived deterministically from content.

3. T: Sized. Unsized targets do not fit the 8-byte thin- pointer slot. Wrap in Box<[u8]>, Arc<str>, or similar at the application layer.

4. with_content_prefix byte order is native. Little-endian and big-endian hosts produce different prefixes for the same T. Persistence and IPC must not rely on with_content_prefix for prefix stability.

5. with_hash_prefix uses DefaultHasher. Not cryptographically strong; not stable across Rust versions; may be randomized per process in some Rust versions. Use from_raw with an explicit hash for stable content-addressing.

6. Prefix is 4 bytes (32 bits). Birthday-bound collision at ~50% probability around ~65 K distinct prefixes; expected collisions for any pair of entries at ~1 in 4 billion. The prefix is a candidate-filter, not an equality test.

7. UmbraOwner<T> does not implement Clone. Owning the target by Box means there is no shared-ownership path; ArcUmbra<T> is the shared-ownership variant.

8. with_content_prefix and with_hash_prefix always heap-allocate via Box::new. There is no in-place variant. The Box is reclaimed when UmbraOwner drops.

9. PhantomData<T> not PhantomData<*const T>. This means UmbraPointer<T> is Send when T: Send and Sync when T: Sync, matching the auto-trait behavior for Box<T> / Arc<T>. Callers needing different variance must construct wrappers.

10. No Hash, PartialEq, Eq, PartialOrd, Ord impls. The crate explicitly chose not to derive these because the “correct” equality is application-dependent (prefix-only, prefix + deref, identity-only). Callers using UmbraPointer as a map key must implement these manually.

Common pitfalls

// WRONG: 32-bit prefix collides at the birthday bound.
if a.ptr().prefix_eq(b.ptr()) {
    return true;  // BUG: false positives possible
}

// CORRECT
if a.ptr().prefix_eq(b.ptr()) && a.value() == b.value() {
    return true;
}

use blake3::Hasher;
fn stable_prefix<T: AsRef<[u8]>>(v: &T) -> u32 {
    let mut h = Hasher::new();
    h.update(v.as_ref());
    let d = h.finalize();
    u32::from_le_bytes(d.as_bytes()[..4].try_into().unwrap())
}

// Pattern that LOOKS right but allocates ownership inside Box:
let owner = UmbraPointer::with_content_prefix(42u64);
// owner is Box<UmbraOwner<u64>>, not UmbraOwner<u64>.
// To dereference twice (once through Box, once through value):
let v: &u64 = owner.value();

back to subetha-pointers docs