Skip to main content

tenferro_mpi/wire/
mod.rs

1//! Wire frames, the dtype code table and the payload views.
2//!
3//! Frames are byte-oriented on purpose: the header, the ack and the payload all go
4//! through the same probe-then-receive path, so a frame is never received into a
5//! buffer shorter than its probed length and MPI truncation is never reached.
6//! [`docs/design/mpi-transport.md`] specifies the format.
7
8use tenferro_tensor::{Complex32, Complex64, DType, TensorScalar};
9
10mod bool_wire;
11
12#[cfg(test)]
13mod tests;
14
15/// A point-to-point tag, matching the MPI and rsmpi `Tag` type.
16pub type Tag = i32;
17
18/// Protocol version carried in every frame.
19pub const PROTOCOL_VERSION: u16 = 1;
20
21/// Largest rank a header can carry.
22pub const MAX_WIRE_RANK: usize = 64;
23
24/// Largest element count one message may carry.
25///
26/// The protocol rejects anything larger instead of chunking or truncating.
27pub const MAX_WIRE_ELEMENTS: u64 = i32::MAX as u64;
28
29pub(crate) const HEADER_PROLOGUE: usize = 24;
30pub(crate) const SHAPE_STRIDE: usize = 8;
31pub(crate) const MAX_HEADER_LEN: usize = HEADER_PROLOGUE + SHAPE_STRIDE * MAX_WIRE_RANK;
32pub(crate) const ACK_LEN: usize = 8;
33/// Largest frame this receiver will allocate for to classify a malformed one.
34///
35/// A frame above this is consumed without a verdict: it is not a header this protocol
36/// could ever have produced, so it belongs to a different tag user.
37pub(crate) const MAX_MALFORMED_FRAME: i64 = 1 << 20;
38pub(crate) const MAGIC: [u8; 4] = *b"TFMP";
39pub(crate) const KIND_HEADER: u8 = 1;
40pub(crate) const KIND_ACK: u8 = 2;
41pub(crate) const STATUS_OK: u8 = 0;
42
43/// Byte order marker for a little-endian peer.
44pub(crate) const BYTE_ORDER_LE: u8 = 1;
45/// Byte order marker for a big-endian peer.
46pub(crate) const BYTE_ORDER_BE: u8 = 2;
47
48/// This host's byte-order marker.
49pub(crate) const HOST_BYTE_ORDER: u8 = if cfg!(target_endian = "little") {
50    BYTE_ORDER_LE
51} else {
52    BYTE_ORDER_BE
53};
54
55/// A header frame, decoded.
56#[derive(Clone, Copy, Debug, PartialEq, Eq)]
57pub(crate) struct Header {
58    pub(crate) version: u16,
59    pub(crate) dtype_code: u8,
60    pub(crate) status: u8,
61    pub(crate) byte_order: u8,
62    pub(crate) elements: u64,
63    shape: [usize; MAX_WIRE_RANK],
64    rank: usize,
65}
66
67impl Header {
68    pub(crate) fn new(dtype_code: u8, byte_order: u8, elements: u64, shape: &[usize]) -> Self {
69        let mut extents = [0usize; MAX_WIRE_RANK];
70        for (slot, extent) in extents.iter_mut().zip(shape) {
71            *slot = *extent;
72        }
73        Self {
74            version: PROTOCOL_VERSION,
75            dtype_code,
76            status: STATUS_OK,
77            byte_order,
78            elements,
79            shape: extents,
80            rank: shape.len(),
81        }
82    }
83
84    /// A header that carries only an abort status: no dtype, rank or payload.
85    pub(crate) fn abort(reason: u8) -> Self {
86        Self {
87            version: PROTOCOL_VERSION,
88            dtype_code: 0,
89            status: reason,
90            byte_order: 0,
91            elements: 0,
92            shape: [0usize; MAX_WIRE_RANK],
93            rank: 0,
94        }
95    }
96
97    pub(crate) fn rank(&self) -> usize {
98        self.rank
99    }
100
101    pub(crate) fn shape(&self) -> &[usize] {
102        &self.shape[..self.rank]
103    }
104
105    /// Encoded length in bytes.
106    pub(crate) fn encoded_len(&self) -> usize {
107        HEADER_PROLOGUE + SHAPE_STRIDE * self.rank
108    }
109
110    /// Encode into `buffer`, which must hold at least [`Self::encoded_len`] bytes.
111    pub(crate) fn encode(&self, buffer: &mut [u8]) -> usize {
112        let len = self.encoded_len();
113        let out = &mut buffer[..len];
114        out[..4].copy_from_slice(&MAGIC);
115        out[4..6].copy_from_slice(&self.version.to_le_bytes());
116        out[6] = KIND_HEADER;
117        out[7] = self.dtype_code;
118        out[8] = self.status;
119        out[9] = self.byte_order;
120        out[10..12].fill(0);
121        out[12..16].copy_from_slice(&(self.rank as u32).to_le_bytes());
122        out[16..24].copy_from_slice(&self.elements.to_le_bytes());
123        for (index, extent) in self.shape().iter().enumerate() {
124            let start = HEADER_PROLOGUE + SHAPE_STRIDE * index;
125            out[start..start + SHAPE_STRIDE].copy_from_slice(&(*extent as u64).to_le_bytes());
126        }
127        len
128    }
129
130    /// Decode a header frame.
131    ///
132    /// Structural checks only: the magic, the declared rank bound and the frame
133    /// length. The version, dtype code, element count and byte order are checked by
134    /// the caller so that each has its own typed rejection.
135    pub(crate) fn decode(bytes: &[u8]) -> std::result::Result<Self, DecodeError> {
136        if bytes.len() < HEADER_PROLOGUE {
137            return Err(DecodeError::Length("shorter than the fixed header"));
138        }
139        if bytes[..4] != MAGIC {
140            return Err(DecodeError::Magic);
141        }
142        if bytes[6] != KIND_HEADER {
143            return Err(DecodeError::Kind(bytes[6]));
144        }
145        let version = u16::from_le_bytes([bytes[4], bytes[5]]);
146        let rank = u32::from_le_bytes([bytes[12], bytes[13], bytes[14], bytes[15]]) as usize;
147        if rank > MAX_WIRE_RANK {
148            return Err(DecodeError::Length("declared rank exceeds MAX_WIRE_RANK"));
149        }
150        if bytes.len() != HEADER_PROLOGUE + SHAPE_STRIDE * rank {
151            return Err(DecodeError::Length(
152                "length does not match the declared rank",
153            ));
154        }
155        let mut shape = [0usize; MAX_WIRE_RANK];
156        for (index, extent) in shape.iter_mut().enumerate().take(rank) {
157            let start = HEADER_PROLOGUE + SHAPE_STRIDE * index;
158            let raw = u64::from_le_bytes(
159                bytes[start..start + SHAPE_STRIDE]
160                    .try_into()
161                    .map_err(|_| DecodeError::Length("truncated shape extent"))?,
162            );
163            *extent = usize::try_from(raw).map_err(|_| DecodeError::Extent)?;
164        }
165        Ok(Self {
166            version,
167            dtype_code: bytes[7],
168            status: bytes[8],
169            byte_order: bytes[9],
170            elements: u64::from_le_bytes(
171                bytes[16..24]
172                    .try_into()
173                    .map_err(|_| DecodeError::Length("truncated element count"))?,
174            ),
175            shape,
176            rank,
177        })
178    }
179}
180
181/// An ack frame, decoded.
182#[derive(Clone, Copy, Debug, PartialEq, Eq)]
183pub(crate) struct Ack {
184    pub(crate) version: u16,
185    pub(crate) verdict: u8,
186}
187
188impl Ack {
189    pub(crate) fn new(verdict: u8) -> Self {
190        Self {
191            version: PROTOCOL_VERSION,
192            verdict,
193        }
194    }
195
196    pub(crate) fn encode(&self) -> [u8; ACK_LEN] {
197        let mut out = [0u8; ACK_LEN];
198        out[..4].copy_from_slice(&MAGIC);
199        out[4..6].copy_from_slice(&self.version.to_le_bytes());
200        out[6] = KIND_ACK;
201        out[7] = self.verdict;
202        out
203    }
204
205    pub(crate) fn decode(bytes: &[u8]) -> std::result::Result<Self, DecodeError> {
206        if bytes.len() < ACK_LEN {
207            return Err(DecodeError::Length("ack frame is shorter than 8 bytes"));
208        }
209        if bytes[..4] != MAGIC {
210            return Err(DecodeError::Magic);
211        }
212        if bytes[6] != KIND_ACK {
213            return Err(DecodeError::Kind(bytes[6]));
214        }
215        Ok(Self {
216            version: u16::from_le_bytes([bytes[4], bytes[5]]),
217            verdict: bytes[7],
218        })
219    }
220}
221
222/// Why a frame could not be decoded.
223#[derive(Debug, Clone, Copy, PartialEq, Eq)]
224pub(crate) enum DecodeError {
225    /// The frame does not carry this protocol's magic.
226    Magic,
227    /// The frame has an unexpected length or declared rank.
228    Length(&'static str),
229    /// The frame's kind byte is not the expected one.
230    Kind(u8),
231    /// A shape extent does not fit this platform's `usize`.
232    Extent,
233}
234
235/// The wire code for a dtype, or `None` when the dtype has no encoding.
236pub(crate) fn dtype_code(dtype: DType) -> Option<u8> {
237    match dtype {
238        DType::Bool => Some(1),
239        DType::I32 => Some(2),
240        DType::I64 => Some(3),
241        DType::F32 => Some(4),
242        DType::F64 => Some(5),
243        DType::C32 => Some(6),
244        DType::C64 => Some(7),
245        DType::External(_) => None,
246    }
247}
248
249/// The dtype a wire code stands for, or `None` for an unknown or reserved code.
250pub(crate) fn dtype_from_code(code: u8) -> Option<DType> {
251    match code {
252        1 => Some(DType::Bool),
253        2 => Some(DType::I32),
254        3 => Some(DType::I64),
255        4 => Some(DType::F32),
256        5 => Some(DType::F64),
257        6 => Some(DType::C32),
258        7 => Some(DType::C64),
259        _ => None,
260    }
261}
262
263/// Byte length of one element of a wire code.
264pub(crate) fn element_bytes(code: u8) -> Option<usize> {
265    dtype_from_code(code).map(|dtype| match dtype {
266        DType::Bool => std::mem::size_of::<bool>(),
267        DType::I32 => std::mem::size_of::<i32>(),
268        DType::I64 => std::mem::size_of::<i64>(),
269        DType::F32 => std::mem::size_of::<f32>(),
270        DType::F64 => std::mem::size_of::<f64>(),
271        DType::C32 => std::mem::size_of::<Complex32>(),
272        DType::C64 => std::mem::size_of::<Complex64>(),
273        DType::External(_) => 0,
274    })
275}
276
277/// Checked shape product.
278pub(crate) fn checked_elements(shape: &[usize]) -> Option<u64> {
279    let mut total: u64 = 1;
280    for extent in shape {
281        total = total.checked_mul(*extent as u64)?;
282    }
283    Some(total)
284}
285
286/// Checked payload byte length for `elements` items of `element_bytes`.
287pub(crate) fn checked_payload_bytes(elements: u64, element_bytes: usize) -> Option<i64> {
288    let bytes = elements.checked_mul(element_bytes as u64)?;
289    i64::try_from(bytes).ok()
290}
291
292/// Scalars this crate can put on the wire.
293///
294/// Sealed: the seven tenferro preset scalars and nothing else. A caller-owned
295/// external scalar needs an explicit codec, because a process-local Rust
296/// `TypeId` cannot be a wire identifier.
297pub(crate) trait WireScalar: TensorScalar + Default + WireScalarSealed {
298    /// Whether a received byte may hold a value of `Self` that does not exist.
299    ///
300    /// Only `bool` does: one byte of payload can be `2`. A receiver must then fill the
301    /// destination from validated values instead of writing into it, because a `bool`
302    /// holding `2` is undefined behaviour the moment anything reads it.
303    const VALIDATES_PAYLOAD: bool;
304
305    /// View the slice as wire bytes.
306    fn bytes(slice: &[Self]) -> &[u8];
307    /// View the slice as mutable wire bytes.
308    fn bytes_mut(slice: &mut [Self]) -> &mut [u8];
309    /// Fill `out` from received `bytes`, and report whether every byte was a value of
310    /// `Self`. On `false`, `out` is left untouched.
311    fn assign_from_bytes(out: &mut [Self], bytes: &[u8]) -> bool;
312}
313
314mod sealed {
315    pub(crate) trait WireScalarSealed {}
316}
317
318use sealed::WireScalarSealed;
319
320/// The six scalars that need no validation: no padding, and every bit pattern is a
321/// valid value.
322macro_rules! plain_wire_scalar {
323    ($($ty:ty),* $(,)?) => {$(
324        impl WireScalarSealed for $ty {}
325
326        impl WireScalar for $ty {
327            const VALIDATES_PAYLOAD: bool = false;
328
329            fn bytes(slice: &[Self]) -> &[u8] {
330                view_as_bytes(slice)
331            }
332
333            fn bytes_mut(slice: &mut [Self]) -> &mut [u8] {
334                view_as_bytes_mut(slice)
335            }
336
337            fn assign_from_bytes(_out: &mut [Self], _bytes: &[u8]) -> bool {
338                // Unused: with `VALIDATES_PAYLOAD = false` the receiver copies straight
339                // into the destination, so no byte buffer is ever assigned from.
340                unreachable!("a plain scalar payload is received in place")
341            }
342        }
343    )*};
344}
345
346plain_wire_scalar!(f32, f64, i32, i64, Complex32, Complex64);
347
348impl WireScalarSealed for bool {}
349
350impl WireScalar for bool {
351    const VALIDATES_PAYLOAD: bool = true;
352
353    fn bytes(slice: &[Self]) -> &[u8] {
354        bool_wire::as_bytes(slice)
355    }
356
357    fn bytes_mut(slice: &mut [Self]) -> &mut [u8] {
358        // Sound in itself: every `bool` in the slice is already 0 or 1. A receiver must
359        // not use it, which is why `VALIDATES_PAYLOAD` sends a payload through a byte
360        // scratch buffer instead.
361        bool_wire::as_bytes_mut(slice)
362    }
363
364    fn assign_from_bytes(out: &mut [Self], bytes: &[u8]) -> bool {
365        bool_wire::assign(out, bytes)
366    }
367}
368
369/// View a slice of a padding-free, all-bit-patterns-valid scalar as bytes.
370///
371/// # Safety
372///
373/// The caller must be an instantiation of [`plain_wire_scalar`], whose types are
374/// `f32`, `f64`, `i32`, `i64`, `Complex32` and `Complex64`: each has no padding
375/// bytes and every bit pattern is a valid value, so the byte view is always a valid
376/// view of the same memory.
377fn view_as_bytes<T>(slice: &[T]) -> &[u8] {
378    // SAFETY: see the function contract; `size_of_val` covers exactly the slice.
379    unsafe { std::slice::from_raw_parts(slice.as_ptr().cast::<u8>(), std::mem::size_of_val(slice)) }
380}
381
382/// Mutable counterpart of [`view_as_bytes`], with the same contract.
383fn view_as_bytes_mut<T>(slice: &mut [T]) -> &mut [u8] {
384    // SAFETY: see `view_as_bytes`; the exclusive borrow keeps the view unique.
385    unsafe {
386        std::slice::from_raw_parts_mut(
387            slice.as_mut_ptr().cast::<u8>(),
388            std::mem::size_of_val(slice),
389        )
390    }
391}