Enum CapHashOrRef 

pub enum CapHashOrRef<O = Box<Cap>> {
    Hash(CapHash),
    Owned(O),
}

Slot/field reference: a content-addressed blob in cache.blobs (Hash), or a single-owner cap held inline by the running kernel frame (Owned).

Owned(Box<Cap>) is the zero-copy ownership form: a cap the kernel frame owns outright and moves between cnode slots (and between frames, at HALT) with no cache round-trip and no data copy — the move is a Box pointer swap. It is runtime-only: it never crosses the wire and is never hashed. The recompiler mints it on derive_spawn and moves it through host_call; it never settles one (the host-side settle arm folds it into a blob for the deferred persist path).

SSZ note: CapHashOrRef’s HashTreeRoot impl is hand-rolled, not derived. The pass-through semantics — Hash(h) hashes to h — let a freshly-published cap substitute for a content reference without changing the hash of any cap that holds it. The Owned arm panics: callers must settle a cap graph before hashing it. Encode mirrors HashTreeRoot (panic on the runtime-only arm); Decode only ever produces Hash (the wire carries selector 0).

Generic over the owned payload O (default Box<Cap>). The wire form (the cnode inside a serialised Cap) is always CapHashOrRef<Box<Cap>>, so Cap and its hash are unaffected. An engine may instantiate a running frame’s cnode with a richer, deliberately non-wire payload (e.g. Box<CachedCap>); the serialisation impls below are gated on O: rkyv::Archive, so such a payload makes the cnode non-hashable and non-serialisable at compile time (a strictly stronger guarantee than the runtime Owned panic).

Not Copy: the Owned(O) arm carries the (usually heap-allocated) payload, so the enum is Clone-only (when O: Clone).

PartialEq/Eq/Hash are hand-written: a Box<Cap> payload blocks the derive (Cap is not Eq/Hash). The Hash arm compares/hashes its 32-byte digest by value; the Owned arm uses pointer identity of the inline payload (sound — Owned is single-owner runtime state, never content-compared — and O-agnostic, so it needs no bound).

Variants

Hash(CapHash)

Owned(O)

Trait Implementations

impl<O: WireOwned> Archive for CapHashOrRef<O>

type Archived = <[u8; 32] as Archive>::Archived

The archived representation of this type.

type Resolver = <[u8; 32] as Archive>::Resolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

impl<O: Clone> Clone for CapHashOrRef<O>

fn clone(&self) -> CapHashOrRef<O>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<O: Debug> Debug for CapHashOrRef<O>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<O: WireOwned> Decode for CapHashOrRef<O>

fn is_ssz_fixed_len() -> bool

true iff this type is fixed-length.

fn ssz_fixed_len() -> usize

Number of bytes this type occupies in the fixed-length portion of a container encoding. Variable-length types return [BYTES_PER_LENGTH_OFFSET].

fn from_ssz_bytes(bytes: &[u8]) -> Result<Self, DecodeError>

Decode a full instance from bytes, rejecting trailing input.

impl<O, D> Deserialize<CapHashOrRef<O>, D> for [u8; 32]

where D: Fallible + ?Sized,

fn deserialize( &self, _deserializer: &mut D, ) -> Result<CapHashOrRef<O>, <D as Fallible>::Error>

Deserializes using the given deserializer

impl<O: WireOwned> Encode for CapHashOrRef<O>

fn is_ssz_fixed_len() -> bool

true iff this type is fixed-length (no variable-length fields).

fn ssz_fixed_len() -> usize

Number of bytes this type occupies in the fixed-length portion of a container encoding. For variable-length types this returns [BYTES_PER_LENGTH_OFFSET] (i.e. the size of the offset slot).

fn ssz_bytes_len(&self) -> usize

Total size of self when serialized.

fn ssz_append(&self, buf: &mut Vec<u8>)

Append the encoding of self to buf.

fn is_basic_type() -> bool

true for “basic” SSZ types (uintN, bool), which pack adjacent elements into shared 32-byte chunks for merkleization. Composite types (containers, lists, structs) return false (the default).

fn as_ssz_bytes(&self) -> Vec<u8>

Serialize into a fresh Vec<u8> allocated through the global allocator.

impl<O> Hash for CapHashOrRef<O>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<O: WireOwned> HashTreeRoot for CapHashOrRef<O>

fn hash_tree_root<D: Digest<OutputSize = U32>>(&self) -> [u8; 32]

Compute the hash tree root using D as the underlying hash.

impl<O> PartialEq for CapHashOrRef<O>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<O, S> Serialize<S> for CapHashOrRef<O>

where O: WireOwned, S: Fallible + ?Sized, <S as Fallible>::Error: Source, CapHash: Serialize<S>,

fn serialize( &self, serializer: &mut S, ) -> Result<Self::Resolver, <S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl<O> Eq for CapHashOrRef<O>