Module umbra_pointer 

UmbraPointer<T> - generic content-prefixed pointer.

16-byte slot. Actual #[repr(C, align(16))] layout is: target: *const T at offset 0..8, prefix: u32 at offset 8..12, _pad: u32 at offset 12..16. The prefix is 4 bytes derived from the target’s content (either the first 4 bytes of an underlying byte-representation, or a 4-byte hash).

The architectural win: equality / lookup operations check the 4-byte prefix in-register BEFORE dereferencing target. For workloads where most comparisons fail (HashMap bucket-chain walks, dedup scans, RDF subject lookups), the prefix short- circuits the dereference, eliminating the cache miss on the pointed-to object.

This is the generic primitive that callers specialise per content type: a string-content overlay (prefix = first 4 bytes of the UTF-8 bytes) and a bit-sliced N-pointer tile overlay both fit inside the same 16-byte slot by reinterpreting prefix as content-specific bits.

Two prefix construction modes:

• UmbraPointer::with_content_prefix copies 4 bytes from the target’s byte-representation (caller supplies bytes).
• UmbraPointer::with_hash_prefix takes a 4-byte hash of the target’s identity. Near-perfect rejection rate (~2^-32 collision) at the cost of computing the hash on construction.

Structs

ArcUmbra

UmbraPointer<T> wrapping an Arc<T>. The Arc reference count keeps the target alive; the UmbraPointer is a copy of the Arc’s data pointer plus the prefix.

UmbraOwner

RAII wrapper for an UmbraPointer<T> whose target was heap-allocated via UmbraPointer::with_content_prefix or UmbraPointer::with_hash_prefix. Drops the boxed target when the owner is dropped.

UmbraPointer

16-byte content-prefixed pointer. Layout is fixed so SIMD scans over an array of UmbraPointer<T> see consistent prefix-byte positions.