merge_machines 0.2.0

data/ext/merge_machines_native/core/src/gcounter.rs

@@ -0,0 +1,242 @@
+//! A counter that only goes up, held as one count per replica.
+
+#[cfg(feature = "alloc")]
+use crate::boxed_frame;
+use crate::{
+    COUNT_LEN, CapacityError, CodecError, FIELD_LEN, Merge, ReplicaId, SHAPE_LEN, TAG,
+    TAG_GCOUNTER, TAG_LEN, free_slot, read_small, read_u64, small_field, tagged_frame, write_into,
+};
+
+/// Bytes one slot record occupies: the replica id then its count.
+const RECORD_LEN: usize = 2 * FIELD_LEN;
+
+/// Where the replica id sits in a slot record.
+const REPLICA: core::ops::Range<usize> = 0..FIELD_LEN;
+
+/// Where the count sits in a slot record.
+const COUNT: core::ops::Range<usize> = FIELD_LEN..RECORD_LEN;
+
+/// Where the number of records carrying a slot sits in a body.
+const HELD: core::ops::Range<usize> = 0..COUNT_LEN;
+
+/// Where the slot records start in a body.
+const RECORDS: usize = HELD.end;
+
+/// Where the shape sits in a frame.
+const SHAPE: core::ops::Range<usize> = TAG_LEN..TAG_LEN + SHAPE_LEN;
+
+/// Where the body starts in a frame.
+const BODY: usize = SHAPE.end;
+
+/// One replica's contribution to a [`GCounter`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Entry {
+    /// The replica that owns this count.
+    pub replica: ReplicaId,
+    /// How much that replica has added.
+    pub count: u64,
+}
+
+/// A counter that only grows, counted separately by each replica.
+///
+/// ```
+/// use merge_machines::{GCounter, Merge};
+///
+/// let mut left = GCounter::<4>::new();
+/// let mut right = GCounter::<4>::new();
+///
+/// assert_eq!(left.increment(1, 3), Ok(()));
+/// assert_eq!(right.increment(2, 7), Ok(()));
+///
+/// assert_eq!(left.merge(&right), Ok(()));
+/// assert_eq!(left.value(), 10);
+///
+/// // Merging the same state again adds nothing.
+/// assert_eq!(left.merge(&right), Ok(()));
+/// assert_eq!(left.value(), 10);
+/// ```
+#[derive(Debug, Clone, Copy, Eq)]
+pub struct GCounter<const R: usize> {
+    slots: [Option<Entry>; R],
+}
+
+impl<const R: usize> GCounter<R> {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { slots: [None; R] }
+    }
+
+    /// Adds `by` to `replica`'s own count, saturating at [`u64::MAX`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CapacityError`] when `replica` has no slot yet and all `R` are
+    /// taken.
+    pub fn increment(&mut self, replica: ReplicaId, by: u64) -> Result<(), CapacityError> {
+        let entry = self.entry_mut(replica).ok_or(CapacityError)?;
+        entry.count = entry.count.saturating_add(by);
+        Ok(())
+    }
+
+    /// What `replica` has added, zero if it has no slot here.
+    #[must_use]
+    pub fn count(&self, replica: ReplicaId) -> u64 {
+        self.slots
+            .iter()
+            .flatten()
+            .find(|entry| entry.replica == replica)
+            .map_or(0, |entry| entry.count)
+    }
+
+    /// Every replica's count, totalled wide enough never to clamp.
+    #[must_use]
+    pub fn value(&self) -> u128 {
+        self.entries().map(|entry| u128::from(entry.count)).sum()
+    }
+
+    /// The per-replica counts, in no particular order.
+    pub fn entries(&self) -> impl Iterator<Item = Entry> + '_ {
+        self.slots.iter().flatten().copied()
+    }
+
+    /// Raises `replica`'s count to `count` if that is higher.
+    fn raise(&mut self, replica: ReplicaId, count: u64) -> Result<(), CapacityError> {
+        let entry = self.entry_mut(replica).ok_or(CapacityError)?;
+        if count > entry.count {
+            entry.count = count;
+        }
+        Ok(())
+    }
+
+    /// Length of the [`encode`](Self::encode) frame.
+    pub const ENCODED_LEN: usize = BODY + Self::BODY_LEN;
+
+    /// Length of the slot table a frame carries after its tag and shape.
+    pub(crate) const BODY_LEN: usize = RECORDS + R * RECORD_LEN;
+
+    /// Writes the counter into `out`, returning the number of bytes written.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `out` is shorter than
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN).
+    pub fn encode(&self, out: &mut [u8]) -> Result<usize, CodecError> {
+        write_into(out, Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// The counter's frame, exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    #[cfg(feature = "alloc")]
+    #[must_use]
+    pub fn encoded(&self) -> alloc::boxed::Box<[u8]> {
+        boxed_frame(Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// Fills a frame of exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    fn write_frame(&self, frame: &mut [u8]) {
+        frame[TAG] = TAG_GCOUNTER;
+        frame[SHAPE].copy_from_slice(&small_field(R));
+        self.write_body(&mut frame[BODY..]);
+    }
+
+    /// Fills a slot table of exactly [`BODY_LEN`](Self::BODY_LEN) bytes.
+    pub(crate) fn write_body(&self, body: &mut [u8]) {
+        body.fill(0);
+        body[HELD].copy_from_slice(&small_field(self.entries().count()));
+
+        let (records, _) = body[RECORDS..].as_chunks_mut::<RECORD_LEN>();
+        for (record, entry) in records.iter_mut().zip(self.entries()) {
+            record[REPLICA].copy_from_slice(&entry.replica.to_le_bytes());
+            record[COUNT].copy_from_slice(&entry.count.to_le_bytes());
+        }
+    }
+
+    /// Reads a counter written by [`encode`](Self::encode).
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `bytes` is too short, [`CodecError::Tag`]
+    /// when it holds another structure, [`CodecError::Parameters`] when it was
+    /// written with another replica count.
+    pub fn decode(bytes: &[u8]) -> Result<Self, CodecError> {
+        let mut counter = Self::new();
+        counter.decode_into(bytes)?;
+        Ok(counter)
+    }
+
+    /// Reads a frame over a counter the caller already holds.
+    ///
+    /// The counter is untouched when the frame is rejected.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`decode`](Self::decode).
+    pub fn decode_into(&mut self, bytes: &[u8]) -> Result<(), CodecError> {
+        let frame = tagged_frame(bytes, Self::ENCODED_LEN, TAG_GCOUNTER)?;
+        if read_small(&frame[SHAPE]) != R {
+            return Err(CodecError::Parameters);
+        }
+
+        self.read_body(&frame[BODY..]);
+        Ok(())
+    }
+
+    /// Reads a slot table of exactly [`BODY_LEN`](Self::BODY_LEN) bytes.
+    pub(crate) fn read_body(&mut self, body: &[u8]) {
+        let held = read_small(&body[HELD]);
+        let (records, _) = body[RECORDS..].as_chunks::<RECORD_LEN>();
+
+        self.slots = [None; R];
+        for (slot, record) in self.slots.iter_mut().zip(records.iter().take(held)) {
+            *slot = Some(Entry {
+                replica: read_u64(&record[REPLICA]),
+                count: read_u64(&record[COUNT]),
+            });
+        }
+    }
+
+    fn entry_mut(&mut self, replica: ReplicaId) -> Option<&mut Entry> {
+        let held = self
+            .slots
+            .iter()
+            .position(|slot| matches!(slot, Some(entry) if entry.replica == replica));
+        if let Some(index) = held {
+            return self.slots[index].as_mut();
+        }
+
+        let free = free_slot(&self.slots)?;
+        self.slots[free] = Some(Entry { replica, count: 0 });
+        self.slots[free].as_mut()
+    }
+}
+
+impl<const R: usize> Merge for GCounter<R> {
+    type Error = CapacityError;
+
+    fn merge(&mut self, other: &Self) -> Result<(), Self::Error> {
+        for entry in other.entries() {
+            self.raise(entry.replica, entry.count)?;
+        }
+        Ok(())
+    }
+}
+
+/// Two counters are equal when every replica's count is, whatever order the
+/// slots were filled in.
+impl<const R: usize> PartialEq for GCounter<R> {
+    fn eq(&self, other: &Self) -> bool {
+        self.entries()
+            .all(|entry| other.count(entry.replica) == entry.count)
+            && other
+                .entries()
+                .all(|entry| self.count(entry.replica) == entry.count)
+    }
+}
+
+impl<const R: usize> Default for GCounter<R> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/merge_machines_native/core/src/gset.rs

@@ -0,0 +1,181 @@
+//! A set that only grows.
+
+#[cfg(feature = "alloc")]
+use crate::boxed_frame;
+use crate::{
+    COUNT_LEN, CapacityError, CodecError, FIELD_LEN, Merge, SHAPE_LEN, TAG, TAG_GSET, TAG_LEN,
+    free_slot, read_small, read_u64, same_elements, small_field, tagged_frame, write_into,
+};
+
+/// Where the shape sits in a frame.
+const SHAPE: core::ops::Range<usize> = TAG_LEN..TAG_LEN + SHAPE_LEN;
+
+/// Where the number of records carrying an element sits in a frame.
+const HELD: core::ops::Range<usize> = SHAPE.end..SHAPE.end + COUNT_LEN;
+
+/// Where the element records start in a frame.
+const RECORDS: usize = HELD.end;
+
+/// A set nothing is ever taken out of.
+///
+/// ```
+/// use merge_machines::{GSet, Merge};
+///
+/// let mut left = GSet::<u16, 8>::new();
+/// let mut right = GSet::<u16, 8>::new();
+///
+/// assert_eq!(left.insert(1), Ok(()));
+/// assert_eq!(left.insert(1), Ok(()));
+/// assert_eq!(right.insert(2), Ok(()));
+///
+/// assert_eq!(left.merge(&right), Ok(()));
+/// assert_eq!(left.len(), 2);
+/// assert!(left.contains(&2));
+/// ```
+#[derive(Debug, Clone, Copy, Eq)]
+pub struct GSet<T, const N: usize> {
+    slots: [Option<T>; N],
+}
+
+impl<T: Copy + PartialEq, const N: usize> GSet<T, N> {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            slots: [const { None }; N],
+        }
+    }
+
+    /// Adds `element`, which is a no-op if it is already in.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CapacityError`] when `element` is new and all `N` slots are
+    /// taken.
+    pub fn insert(&mut self, element: T) -> Result<(), CapacityError> {
+        if self.contains(&element) {
+            return Ok(());
+        }
+        let free = free_slot(&self.slots).ok_or(CapacityError)?;
+        self.slots[free] = Some(element);
+        Ok(())
+    }
+
+    #[must_use]
+    pub fn contains(&self, element: &T) -> bool {
+        self.slots.iter().flatten().any(|held| held == element)
+    }
+
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.slots.iter().flatten().count()
+    }
+
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// The elements, in no particular order.
+    pub fn iter(&self) -> impl Iterator<Item = T> + '_ {
+        self.slots.iter().flatten().copied()
+    }
+}
+
+impl<const N: usize> GSet<u64, N> {
+    /// Length of the [`encode`](Self::encode) frame.
+    pub const ENCODED_LEN: usize = RECORDS + N * FIELD_LEN;
+
+    /// Writes the set into `out`, returning the number of bytes written.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `out` is shorter than
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN).
+    pub fn encode(&self, out: &mut [u8]) -> Result<usize, CodecError> {
+        write_into(out, Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// The set's frame, exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    #[cfg(feature = "alloc")]
+    #[must_use]
+    pub fn encoded(&self) -> alloc::boxed::Box<[u8]> {
+        boxed_frame(Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// Fills a frame of exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    fn write_frame(&self, frame: &mut [u8]) {
+        frame.fill(0);
+        frame[TAG] = TAG_GSET;
+        frame[SHAPE].copy_from_slice(&small_field(N));
+        frame[HELD].copy_from_slice(&small_field(self.len()));
+
+        let (records, _) = frame[RECORDS..].as_chunks_mut::<FIELD_LEN>();
+        for (record, element) in records.iter_mut().zip(self.iter()) {
+            *record = element.to_le_bytes();
+        }
+    }
+
+    /// Reads a set written by [`encode`](Self::encode).
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `bytes` is too short, [`CodecError::Tag`]
+    /// when it holds another structure, [`CodecError::Parameters`] when it was
+    /// written with another capacity.
+    pub fn decode(bytes: &[u8]) -> Result<Self, CodecError> {
+        let mut set = Self::new();
+        set.decode_into(bytes)?;
+        Ok(set)
+    }
+
+    /// Reads a frame over a set the caller already holds.
+    ///
+    /// The set is untouched when the frame is rejected.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`decode`](Self::decode).
+    pub fn decode_into(&mut self, bytes: &[u8]) -> Result<(), CodecError> {
+        let frame = tagged_frame(bytes, Self::ENCODED_LEN, TAG_GSET)?;
+        if read_small(&frame[SHAPE]) != N {
+            return Err(CodecError::Parameters);
+        }
+
+        let held = read_small(&frame[HELD]);
+        let (records, _) = frame[RECORDS..].as_chunks::<FIELD_LEN>();
+
+        self.slots = [None; N];
+        for (slot, record) in self.slots.iter_mut().zip(records.iter().take(held)) {
+            *slot = Some(read_u64(record));
+        }
+        Ok(())
+    }
+}
+
+impl<T: Copy + PartialEq, const N: usize> Merge for GSet<T, N> {
+    type Error = CapacityError;
+
+    fn merge(&mut self, other: &Self) -> Result<(), Self::Error> {
+        for element in other.iter() {
+            self.insert(element)?;
+        }
+        Ok(())
+    }
+}
+
+/// Two sets are equal when they hold the same elements, whatever order the
+/// slots were filled in.
+impl<T: PartialEq, const N: usize> PartialEq for GSet<T, N> {
+    fn eq(&self, other: &Self) -> bool {
+        same_elements(&self.slots, &other.slots)
+    }
+}
+
+impl<T: Copy + PartialEq, const N: usize> Default for GSet<T, N> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/merge_machines_native/core/src/hybrid.rs

@@ -0,0 +1,222 @@
+//! A hybrid logical clock: timestamps near physical time that still order.
+
+#[cfg(feature = "alloc")]
+use crate::boxed_frame;
+use crate::{
+    ClockExhausted, CodecError, FIELD_LEN, STAMP_HYBRID, Stamp, TAG, TAG_HYBRID_CLOCK, TAG_LEN,
+    read_u64, tagged_frame, write_into,
+};
+
+/// Bytes a [`HybridTimestamp`] occupies in a frame.
+const TIMESTAMP_LEN: usize = 2 * FIELD_LEN;
+
+/// Where the wall-clock reading sits in a timestamp field.
+const WALL: core::ops::Range<usize> = 0..FIELD_LEN;
+
+/// Where the counter sits in a timestamp field.
+const COUNTER: core::ops::Range<usize> = FIELD_LEN..TIMESTAMP_LEN;
+
+/// Where the last timestamp issued sits in a clock frame.
+const LAST: core::ops::Range<usize> = TAG_LEN..TAG_LEN + TIMESTAMP_LEN;
+
+/// A wall-clock reading paired with a counter that breaks its ties.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct HybridTimestamp {
+    /// The wall-clock reading this was issued at, in nanoseconds.
+    pub wall_ns: u64,
+    /// How many timestamps have been issued at this reading.
+    pub counter: u64,
+}
+
+impl Stamp for HybridTimestamp {
+    const KIND: u8 = STAMP_HYBRID;
+    const ENCODED_LEN: usize = TIMESTAMP_LEN;
+
+    fn write(self, field: &mut [u8]) {
+        field[WALL].copy_from_slice(&self.wall_ns.to_le_bytes());
+        field[COUNTER].copy_from_slice(&self.counter.to_le_bytes());
+    }
+
+    fn read(field: &[u8]) -> Self {
+        Self {
+            wall_ns: read_u64(&field[WALL]),
+            counter: read_u64(&field[COUNTER]),
+        }
+    }
+}
+
+/// Issues timestamps that track physical time without ever going backwards.
+///
+/// # The reading this wants
+///
+/// `wall_ns` is physical time that two machines can compare: nanoseconds since
+/// the Unix epoch. It is allowed to jump backwards, which is exactly why the
+/// counter exists.
+///
+/// It is not a monotonic reading, and nothing derived from it is a deadline, a
+/// timeout or a budget. Measuring how long something took needs the monotonic
+/// clock, which this crate neither reads nor models. Wiring a monotonic reading
+/// in here produces timestamps that no other machine can order against its own.
+///
+/// ```
+/// use merge_machines::{ClockExhausted, HybridClock, HybridTimestamp};
+///
+/// const MS: u64 = 1_000_000;
+/// let mut clock = HybridClock::new();
+///
+/// let first = clock.tick(10 * MS)?;
+/// assert_eq!(first.counter, 0);
+///
+/// // Same reading twice: the counter separates them.
+/// let second = clock.tick(10 * MS)?;
+/// assert!(second > first);
+///
+/// // The wall clock is corrected backwards; the timestamps are not.
+/// let third = clock.tick(4 * MS)?;
+/// assert!(third > second);
+/// assert_eq!(third.wall_ns, 10 * MS);
+///
+/// // A reading that really did advance resets the counter.
+/// let fourth = clock.tick(11 * MS)?;
+/// assert_eq!(fourth.counter, 0);
+///
+/// // A counter with nothing left reports it instead of repeating itself.
+/// let crowded = HybridTimestamp { wall_ns: 11 * MS, counter: u64::MAX };
+/// assert_eq!(clock.observe(0, crowded), Err(ClockExhausted));
+/// assert_eq!(clock.last(), fourth);
+/// # Ok::<(), ClockExhausted>(())
+/// ```
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct HybridClock {
+    last: HybridTimestamp,
+}
+
+const fn larger(left: u64, right: u64) -> u64 {
+    if left > right { left } else { right }
+}
+
+impl HybridClock {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            last: HybridTimestamp {
+                wall_ns: 0,
+                counter: 0,
+            },
+        }
+    }
+
+    /// The last timestamp this clock issued.
+    #[must_use]
+    pub const fn last(&self) -> HybridTimestamp {
+        self.last
+    }
+
+    /// Stamps a local event at wall-clock reading `wall_ns`.
+    ///
+    /// # Errors
+    ///
+    /// [`ClockExhausted`] when the reading has not advanced and the counter
+    /// that separates two events at the same reading holds its highest value,
+    /// which leaves the clock where it was.
+    pub const fn tick(&mut self, wall_ns: u64) -> Result<HybridTimestamp, ClockExhausted> {
+        if wall_ns > self.last.wall_ns {
+            self.last = HybridTimestamp {
+                wall_ns,
+                counter: 0,
+            };
+            return Ok(self.last);
+        }
+        let Some(counter) = self.last.counter.checked_add(1) else {
+            return Err(ClockExhausted);
+        };
+        self.last.counter = counter;
+        Ok(self.last)
+    }
+
+    /// Stamps the receipt of `observed` at wall-clock reading `wall_ns`.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`tick`](Self::tick), and the observed timestamp is not
+    /// adopted either.
+    pub const fn observe(
+        &mut self,
+        wall_ns: u64,
+        observed: HybridTimestamp,
+    ) -> Result<HybridTimestamp, ClockExhausted> {
+        let latest = larger(wall_ns, larger(self.last.wall_ns, observed.wall_ns));
+        let counter = if latest == self.last.wall_ns && latest == observed.wall_ns {
+            larger(self.last.counter, observed.counter).checked_add(1)
+        } else if latest == self.last.wall_ns {
+            self.last.counter.checked_add(1)
+        } else if latest == observed.wall_ns {
+            observed.counter.checked_add(1)
+        } else {
+            Some(0)
+        };
+        let Some(counter) = counter else {
+            return Err(ClockExhausted);
+        };
+
+        self.last = HybridTimestamp {
+            wall_ns: latest,
+            counter,
+        };
+        Ok(self.last)
+    }
+
+    /// Length of the [`encode`](Self::encode) frame.
+    pub const ENCODED_LEN: usize = TAG_LEN + TIMESTAMP_LEN;
+
+    /// Writes the clock into `out`, returning the number of bytes written.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `out` is shorter than
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN).
+    pub fn encode(&self, out: &mut [u8]) -> Result<usize, CodecError> {
+        write_into(out, Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// The clock's frame, exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    #[cfg(feature = "alloc")]
+    #[must_use]
+    pub fn encoded(&self) -> alloc::boxed::Box<[u8]> {
+        boxed_frame(Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// Fills a frame of exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    fn write_frame(&self, frame: &mut [u8]) {
+        frame[TAG] = TAG_HYBRID_CLOCK;
+        self.last.write(&mut frame[LAST]);
+    }
+
+    /// Reads a clock written by [`encode`](Self::encode).
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `bytes` is too short, [`CodecError::Tag`]
+    /// when it holds another structure.
+    pub fn decode(bytes: &[u8]) -> Result<Self, CodecError> {
+        let mut clock = Self::new();
+        clock.decode_into(bytes)?;
+        Ok(clock)
+    }
+
+    /// Reads a frame over a clock the caller already holds.
+    ///
+    /// The clock is untouched when the frame is rejected.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`decode`](Self::decode).
+    pub fn decode_into(&mut self, bytes: &[u8]) -> Result<(), CodecError> {
+        let frame = tagged_frame(bytes, Self::ENCODED_LEN, TAG_HYBRID_CLOCK)?;
+        self.last = HybridTimestamp::read(&frame[LAST]);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests;