Struct SharedUmbraPointer

Source

pub struct SharedUmbraPointer<T: Copy + 'static> {
    pub target: OffsetPtr<T>,
    pub prefix: u32,
    /* private fields */
}

Expand description

16-byte cross-process content-prefixed pointer.

Layout is fixed and PoD so SIMD scans over an array see a stable prefix-byte position.

offset 0   : OffsetPtr<T>     (u32 index; NIL = u32::MAX)
offset 4   : u32 prefix
offset 8   : u8 ext_tag       (0 = unset; 1..=255 = registered)
offset 9   : [u8; 7] ext_payload  (interpretation per tag)
offset 16  : end

§User-addressable extension bytes

Bytes 8..16 are a TAG (1 byte) + PAYLOAD (7 bytes) that callers can use to attach typed metadata to the pointer. Access via the UmbraExtension trait + set_ext / ext methods:

Guard 1 (compile-time size): set_ext<E> and ext<E> both monomorphize a const-assertion that size_of::<E>() <= 7. Larger types fail to compile.
Guard 2 (runtime tag): each UmbraExtension declares a unique TAG: u8 constant. ext<E>() returns None if the pointer’s tag does not match E::TAG, preventing two consumers from interpreting the same bytes differently.
Guard 3 (type bound): E: Copy + 'static ensures no Drop side effects and no lifetimes to manage.

Fields§

§target: OffsetPtr<T>

Index of the target slot in some SharedRegion<T>. The region itself is held by the caller; this pointer is just the cross-process-stable address.

§prefix: u32

4-byte content prefix derived from the target’s bytes (or a 4-byte hash). Constant for the lifetime of the pointer.

Implementations§

Source §

impl<T: Copy + 'static> SharedUmbraPointer<T>

Source

pub const SIGNATURE: AxisMask

Direction signature of SharedUmbraPointer<T>. Engages the K_content_prefix axis (4-byte prefix stored at slot for short-circuit equality before MMF deref).

Source

pub const NIL: Self

NIL sentinel: target is OffsetPtr::NIL and prefix is 0; extension tag is 0 (unset). Equivalent to a freshly-zeroed 16-byte slot.

Source

pub const fn new(target: OffsetPtr<T>, prefix: u32) -> Self

Construct from an existing region-allocated OffsetPtr and a caller-computed prefix. Extension is unset (tag=0).

Source

pub fn set_ext<E: UmbraExtension>(&mut self, value: E)

Write a typed extension. Sets the tag to E::TAG and copies the value bytes into the payload. Caller guarantees E::TAG is globally unique.

Source

pub unsafe fn ext<E: UmbraExtension>(&self) -> Option<E>

Read a typed extension. Returns None if no extension is set (tag=0) OR if the stored tag does not match E::TAG.

§Safety

Even with tag validation, this is unsafe because the tag-uniqueness contract is on the caller. Two UmbraExtension implementations sharing a TAG value will silently misinterpret each other’s payloads. The payload bytes must also be a valid representation of E (relevant for enums with restricted discriminants).

Source

pub fn clear_ext(&mut self)

Clear the extension. Tag and payload set to 0.

Source

pub fn ext_tag(&self) -> u8

The current extension tag (0 = unset).

Source

pub fn ext_payload_raw(&self) -> &[u8; 7]

Raw byte access to the extension payload. Use this for debugging or when interfacing with untyped consumers.

Source

pub fn from_region_alloc_content_prefix( region: &SharedRegion<T>, value: T, ) -> Result<Self, RegionError>

Allocate value in region and build a pointer whose prefix is the first 4 bytes of the in-memory representation of T (little-endian native). Useful when T’s first bytes are a meaningful key field (row IDs, packet headers).

Source

pub fn from_region_alloc_hash_prefix( region: &SharedRegion<T>, value: T, ) -> Result<Self, RegionError>
where T: Hash,

Allocate value in region and build a pointer whose prefix is the low 32 bits of std::hash::DefaultHasher applied to value. Near-perfect rejection rate; requires T: Hash.

Source