Struct Ref 

pub struct Ref<'a, T: Payload<E>, E: Encoding> { /* private fields */ }

A proof that some bytes passed T::verify or were written by T::encode.

The fields are private and Ref::verify and Ref::encode are the only constructors. A crate outside ridl-rt builds a Ref by checking:

use ridl_rt::encoding::ReprC;
use ridl_rt::payload::{Payload, Ref, VerifyError};

fn check<'a, T>(bytes: &'a [u8]) -> Result<Ref<'a, T, ReprC>, VerifyError>
where
    T: Payload<ReprC, View<'a> = &'a [u8]>,
{
    Ref::verify(bytes)
}

and cannot build one from its fields:

use core::marker::PhantomData;
use ridl_rt::encoding::ReprC;
use ridl_rt::payload::{Payload, Ref};

fn forge<'a, T>(bytes: &'a [u8]) -> Ref<'a, T, ReprC>
where
    T: Payload<ReprC, View<'a> = &'a [u8]>,
{
    Ref { bytes, view: bytes, _e: PhantomData }
}

Implementations

impl<'a, T: Payload<E>, E: Encoding> Ref<'a, T, E>

pub fn verify(buf: &'a [u8]) -> Result<Self, VerifyError>

Checks buf with T::verify and returns the proof.

Examples found in repository

examples/read_sample.rs (line 145)

pub fn read_speed(port: &dyn SignalReader) -> Result<Sample<Speed>, ReadError> {
    let mut buf = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let raw = port.read(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal, &mut buf)?;
    let (value, provenance) = match raw.provenance {
        Provenance::Init | Provenance::Invalid(Cause::Declared) if raw.len == 0 => {
            (SpeedSignal::init(), raw.provenance)
        }
        _ => match Ref::<Speed, ReprC>::verify(&buf[..raw.len]) {
            Ok(proof) => (proof.decode(), raw.provenance),
            Err(VerifyError::Contract(violation)) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::InvalidValue(violation))),
            ),
            Err(_) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::Corrupt)),
            ),
        },
    };
    Ok(Sample {
        value,
        provenance,
        freshness: raw.freshness,
        envelope: raw.envelope,
    })
}

pub fn encode(value: &T, out: &'a mut [u8]) -> Result<Self, EncodeError>

Encodes value into out with T::encode and returns the proof.

It does not check the value’s typl constraints: a value is trusted to be valid when constructed, and the receiver’s verify reports a value that is not.

Examples found in repository

examples/read_sample.rs (line 318)

fn publish(runtime: &mut Memory, speed: Speed) {
    let mut buf = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let proof = Ref::<Speed, ReprC>::encode(&speed, &mut buf).expect("the buffer is MAX_SIZE");
    runtime
        .set(
            Drivetrain::NUMBER,
            SpeedSignal::MEMBER.ordinal,
            proof.bytes(),
        )
        .expect("the runtime owns speed");
    runtime.commit();
}

/// Moves `speed` through six states and returns the sample read after each:
/// the init value; a live value; the same value once its staleness bound has
/// passed; the invalid state the provider declares; a value the accessor's
/// check rejects; and bytes the accessor cannot decode.
pub fn walk() -> [Sample<Speed>; 6] {
    let mut init = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let proof = Ref::<Speed, ReprC>::encode(&SpeedSignal::init(), &mut init)
        .expect("the buffer is MAX_SIZE");
    let mut runtime = Memory::new(Timestamp(1_000_000), proof.bytes());
    let read = |runtime: &Memory| read_speed(runtime).expect("speed is in the catalog");

    let at_init = read(&runtime);

    runtime.advance(Duration(10_000));
    publish(&mut runtime, Speed(88));
    let live = read(&runtime);

    runtime.advance(Duration(600_000));
    let stale = read(&runtime);

    runtime
        .invalidate(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal)
        .expect("the runtime owns speed");
    runtime.commit();
    let declared = read(&runtime);

    runtime
        .set(
            Drivetrain::NUMBER,
            SpeedSignal::MEMBER.ordinal,
            &400u16.to_le_bytes(),
        )
        .expect("the runtime owns speed");
    runtime.commit();
    let detected = read(&runtime);

    // One byte where the encoding needs two.
    runtime
        .set(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal, &[1])
        .expect("the runtime owns speed");
    runtime.commit();
    let corrupt = read(&runtime);

    [at_init, live, stale, declared, detected, corrupt]
}

pub fn bytes(&self) -> &'a [u8]

The checked or encoded bytes.

Examples found in repository

examples/read_sample.rs (line 71)

    fn decode(r: Ref<'_, Self, ReprC>) -> Self {
        let b = r.bytes();
        Speed(u16::from_le_bytes([b[0], b[1]]))
    }
}

/// The catalog of the package `vehicle`.
pub const VEHICLE: CatalogRef = CatalogRef {
    name: "vehicle",
    hash: CatalogHash([7; 32]),
};

/// `interface Drivetrain { signal speed : Speed @[20ms..500ms] }`
pub struct Drivetrain;

impl Interface for Drivetrain {
    const CATALOG: &'static CatalogRef = &VEHICLE;
    const NUMBER: InterfaceNo = InterfaceNo(1);
    const PROVISIONAL: bool = false;
    const NAME: &'static str = "Drivetrain";
    const MEMBERS: &'static [Member] = &[Member {
        ordinal: Ordinal(1),
        kind: Kind::Signal,
        name: "speed",
        timing: Some(Timing {
            mode: TimingMode::Range,
            min: Some(Duration(20_000)),
            max: Some(Duration(500_000)),
        }),
        // A generated descriptor fills in every encoding that can carry the
        // payload. This program writes only the `repr(C)` codec, so it fills
        // in only that size.
        payloads: &[PayloadInfo {
            type_name: "Speed",
            max_size: EncodedSizes {
                proto3: None,
                flatbuffers: None,
                repr_c: Some(2),
            },
        }],
    }];
}

/// The descriptor of `Drivetrain.speed`.
pub struct SpeedSignal;

impl Interaction for SpeedSignal {
    type Iface = Drivetrain;
    const MEMBER: &'static Member = &Drivetrain::MEMBERS[0];
}

impl Signal for SpeedSignal {
    type Payload = Speed;
    fn init() -> Speed {
        Speed(30)
    }
}

/// The accessor a generated client writes for `speed`: read the bytes, check
/// them, decode them. The `Init`-or-`Invalid(Declared)`-with-no-bytes arm
/// below handles a port whose init or invalidated sample carries no bytes;
/// `walk` never produces that shape, because it seeds `Memory` with a real
/// 2-byte init encoding and `invalidate` keeps those bytes rather than
/// clearing them (`tests/read_sample.rs` exercises the arm directly, with a
/// `Memory` seeded from an empty init buffer). Otherwise the check runs;
/// when it fails, the accessor reports the detection as the provenance and
/// substitutes the init value. A generated accessor would substitute its own
/// last good value when it has one.
pub fn read_speed(port: &dyn SignalReader) -> Result<Sample<Speed>, ReadError> {
    let mut buf = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let raw = port.read(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal, &mut buf)?;
    let (value, provenance) = match raw.provenance {
        Provenance::Init | Provenance::Invalid(Cause::Declared) if raw.len == 0 => {
            (SpeedSignal::init(), raw.provenance)
        }
        _ => match Ref::<Speed, ReprC>::verify(&buf[..raw.len]) {
            Ok(proof) => (proof.decode(), raw.provenance),
            Err(VerifyError::Contract(violation)) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::InvalidValue(violation))),
            ),
            Err(_) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::Corrupt)),
            ),
        },
    };
    Ok(Sample {
        value,
        provenance,
        freshness: raw.freshness,
        envelope: raw.envelope,
    })
}

// ---- What a runtime writes ----------------------------------------------------

/// A runtime for one signal of at most 2 bytes: a manual clock, one slot, and
/// one staged change.
pub struct Memory {
    now: Cell<i64>,
    bytes: [u8; 2],
    len: usize,
    provenance: Provenance,
    envelope: Envelope,
    staged: Option<Staged>,
}

enum Staged {
    Value([u8; 2], usize),
    Invalid,
    Touch,
}

impl Memory {
    /// Creates the channel at `now`, holding the init value's bytes.
    pub fn new(now: Timestamp, init: &[u8]) -> Memory {
        let mut bytes = [0u8; 2];
        bytes[..init.len()].copy_from_slice(init);
        Memory {
            now: Cell::new(now.0),
            bytes,
            len: init.len(),
            provenance: Provenance::Init,
            envelope: Envelope { stamp: now, seq: 0 },
            staged: None,
        }
    }

    /// Moves the clock forward.
    pub fn advance(&self, by: Duration) {
        self.now.set(self.now.get() + by.0);
    }

    fn member(iface: InterfaceNo, ord: Ordinal) -> Option<&'static Member> {
        if iface != Drivetrain::NUMBER {
            return None;
        }
        Drivetrain::MEMBERS
            .iter()
            .find(|m| m.ordinal == ord && m.kind == Kind::Signal)
    }
}

impl Attached for Memory {
    fn catalog(&self) -> &CatalogRef {
        Drivetrain::CATALOG
    }
}

impl Clock for Memory {
    fn now(&self) -> Timestamp {
        Timestamp(self.now.get())
    }
}

impl SignalReader for Memory {
    fn read(
        &self,
        iface: InterfaceNo,
        ord: Ordinal,
        out: &mut [u8],
    ) -> Result<RawSample, ReadError> {
        let member =
            Memory::member(iface, ord).ok_or(ReadError::Contract(Contract::UnknownInteraction))?;
        let Some(front) = out.get_mut(..self.len) else {
            return Err(ReadError::Short { needed: self.len });
        };
        front.copy_from_slice(&self.bytes[..self.len]);
        let freshness = match member.timing.and_then(|t| t.max) {
            None => Freshness::Unbounded,
            Some(max) => {
                let age = self.now().0 - self.envelope.stamp.0;
                if age > max.0 {
                    Freshness::Stale {
                        by: Duration(age - max.0),
                    }
                } else {
                    Freshness::Fresh
                }
            }
        };
        Ok(RawSample {
            provenance: self.provenance,
            freshness,
            envelope: self.envelope,
            len: self.len,
        })
    }
}

impl SignalWriter for Memory {
    fn set(&mut self, iface: InterfaceNo, ord: Ordinal, bytes: &[u8]) -> Result<(), WriteError> {
        if Memory::member(iface, ord).is_none() {
            return Err(WriteError::Contract(Contract::UnknownInteraction));
        }
        let mut value = [0u8; 2];
        let Some(front) = value.get_mut(..bytes.len()) else {
            return Err(WriteError::TooLarge { cap: 2 });
        };
        front.copy_from_slice(bytes);
        self.staged = Some(Staged::Value(value, bytes.len()));
        Ok(())
    }

    fn invalidate(&mut self, iface: InterfaceNo, ord: Ordinal) -> Result<(), WriteError> {
        if Memory::member(iface, ord).is_none() {
            return Err(WriteError::Contract(Contract::UnknownInteraction));
        }
        self.staged = Some(Staged::Invalid);
        Ok(())
    }

    fn touch(&mut self, iface: InterfaceNo, ord: Ordinal) -> Result<(), WriteError> {
        if Memory::member(iface, ord).is_none() {
            return Err(WriteError::Contract(Contract::UnknownInteraction));
        }
        if self.staged.is_none() {
            self.staged = Some(Staged::Touch);
        }
        Ok(())
    }

    fn commit(&mut self) {
        let Some(staged) = self.staged.take() else {
            return;
        };
        match staged {
            Staged::Value(bytes, len) => {
                self.bytes = bytes;
                self.len = len;
                self.provenance = Provenance::Live;
            }
            Staged::Invalid => self.provenance = Provenance::Invalid(Cause::Declared),
            Staged::Touch => {}
        }
        self.envelope = Envelope {
            stamp: self.now(),
            seq: self.envelope.seq + 1,
        };
    }
}

// ---- The program --------------------------------------------------------------

/// Publishes `speed` the way a generated publisher does: encode, stage, commit.
fn publish(runtime: &mut Memory, speed: Speed) {
    let mut buf = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let proof = Ref::<Speed, ReprC>::encode(&speed, &mut buf).expect("the buffer is MAX_SIZE");
    runtime
        .set(
            Drivetrain::NUMBER,
            SpeedSignal::MEMBER.ordinal,
            proof.bytes(),
        )
        .expect("the runtime owns speed");
    runtime.commit();
}

/// Moves `speed` through six states and returns the sample read after each:
/// the init value; a live value; the same value once its staleness bound has
/// passed; the invalid state the provider declares; a value the accessor's
/// check rejects; and bytes the accessor cannot decode.
pub fn walk() -> [Sample<Speed>; 6] {
    let mut init = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let proof = Ref::<Speed, ReprC>::encode(&SpeedSignal::init(), &mut init)
        .expect("the buffer is MAX_SIZE");
    let mut runtime = Memory::new(Timestamp(1_000_000), proof.bytes());
    let read = |runtime: &Memory| read_speed(runtime).expect("speed is in the catalog");

    let at_init = read(&runtime);

    runtime.advance(Duration(10_000));
    publish(&mut runtime, Speed(88));
    let live = read(&runtime);

    runtime.advance(Duration(600_000));
    let stale = read(&runtime);

    runtime
        .invalidate(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal)
        .expect("the runtime owns speed");
    runtime.commit();
    let declared = read(&runtime);

    runtime
        .set(
            Drivetrain::NUMBER,
            SpeedSignal::MEMBER.ordinal,
            &400u16.to_le_bytes(),
        )
        .expect("the runtime owns speed");
    runtime.commit();
    let detected = read(&runtime);

    // One byte where the encoding needs two.
    runtime
        .set(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal, &[1])
        .expect("the runtime owns speed");
    runtime.commit();
    let corrupt = read(&runtime);

    [at_init, live, stale, declared, detected, corrupt]
}

pub fn view(&self) -> &T::View<'a>

Lends the view.

pub fn into_view(self) -> T::View<'a>

Moves the view out.

pub fn decode(self) -> T

Builds the value with T::decode.

Examples found in repository

examples/read_sample.rs (line 146)

pub fn read_speed(port: &dyn SignalReader) -> Result<Sample<Speed>, ReadError> {
    let mut buf = [0u8; <Speed as Payload<ReprC>>::MAX_SIZE];
    let raw = port.read(Drivetrain::NUMBER, SpeedSignal::MEMBER.ordinal, &mut buf)?;
    let (value, provenance) = match raw.provenance {
        Provenance::Init | Provenance::Invalid(Cause::Declared) if raw.len == 0 => {
            (SpeedSignal::init(), raw.provenance)
        }
        _ => match Ref::<Speed, ReprC>::verify(&buf[..raw.len]) {
            Ok(proof) => (proof.decode(), raw.provenance),
            Err(VerifyError::Contract(violation)) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::InvalidValue(violation))),
            ),
            Err(_) => (
                SpeedSignal::init(),
                Provenance::Invalid(Cause::Detected(Detection::Corrupt)),
            ),
        },
    };
    Ok(Sample {
        value,
        provenance,
        freshness: raw.freshness,
        envelope: raw.envelope,
    })
}