merge_machines 0.2.0

data/ext/merge_machines_native/ffi/src/orset.rs

@@ -0,0 +1,240 @@
+//! `MergeMachines::OrSet`: a set elements can leave, where a concurrent add
+//! survives a remove.
+
+use std::cell::RefCell;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use bytes::Bytes;
+use magnus::scan_args::scan_args;
+use magnus::typed_data::Obj;
+use magnus::{Error, RArray, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use merge_machines::{OrSet, ReplicaId, Tag};
+
+use crate::hash::hash64;
+use crate::names::{self, Names};
+use crate::shape::{frame_len_of, shaped};
+use crate::{
+    CAPACITIES, Whole, blob_shape, capacity, mismatch, required_kwarg, tags_exhausted, unsupported,
+    unsupported_blob,
+};
+
+/// Tags minted in this process, so no two sets allocate the same one.
+static MINTED: AtomicU64 = AtomicU64::new(0);
+
+/// The set at a single capacity, over the 64-bit hash each key becomes.
+type Held<const N: usize> = OrSet<u64, N>;
+
+shaped!(Set over Held { N64 = 64, N256 = 256, N1024 = 1024 });
+
+/// Runs `body` against whichever variant is held.
+macro_rules! set {
+    ($set:expr, |$inner:ident| $body:expr) => {
+        match $set {
+            Set::N64($inner) => $body,
+            Set::N256($inner) => $body,
+            Set::N1024($inner) => $body,
+        }
+    };
+}
+
+/// The set holds 64-bit key hashes, and `names` holds the string each one came
+/// from.
+#[magnus::wrap(class = "MergeMachines::OrSet", free_immediately, size)]
+struct Wrapper {
+    set: RefCell<Set>,
+    names: RefCell<Names>,
+}
+
+const fn capacity_of<const N: usize>(_: &Held<N>) -> usize {
+    N
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(capacity): Whole<usize> = required_kwarg(args.keywords, "capacity")?;
+        Ok(Self {
+            set: RefCell::new(dispatch(ruby, capacity, None)?),
+            names: RefCell::new(Names::new()),
+        })
+    }
+
+    /// Reads a blob written by [`dump`](Self::dump).
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let set = dispatch(ruby, blob_shape(ruby, &blob)?, Some(&blob))?;
+        let frame_len = set!(&set, |inner| frame_len_of(&**inner));
+        let names = names::read(ruby, &blob[frame_len..])?;
+        let elements = set!(&set, |inner| inner
+            .adds()
+            .map(|add| add.element)
+            .collect::<Vec<u64>>());
+        names::complete(ruby, &names, elements.into_iter())?;
+
+        let wrapper = Self {
+            set: RefCell::new(set),
+            names: RefCell::new(names),
+        };
+        wrapper.prune();
+        Ok(wrapper)
+    }
+
+    fn capacity(&self) -> usize {
+        set!(&*self.set.borrow(), |set| capacity_of(&**set))
+    }
+
+    /// Adds `key` under a tag of `replica:` and the next counter that replica
+    /// has not used here.
+    fn add(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(String,), (), (), (), RHash, ()>(args)?;
+        let (key,) = args.required;
+        let Whole(replica): Whole<ReplicaId> = required_kwarg(args.keywords, "replica")?;
+
+        let element = hash64(key.as_bytes());
+        let Some(counter) = rb_self.next_counter(replica) else {
+            return Err(tags_exhausted(ruby));
+        };
+        let tag = Tag::new(replica, counter);
+        capacity(
+            ruby,
+            set!(&mut *rb_self.set.borrow_mut(), |set| set.add(element, tag)),
+        )?;
+        rb_self.names.borrow_mut().insert(element, key);
+        Ok(())
+    }
+
+    /// Tombstones every tag this set has seen for `key`.
+    fn remove(ruby: &Ruby, rb_self: &Self, key: String) -> Result<(), Error> {
+        let element = hash64(key.as_bytes());
+        capacity(
+            ruby,
+            set!(&mut *rb_self.set.borrow_mut(), |set| set.remove(&element)),
+        )
+    }
+
+    fn includes(&self, key: String) -> bool {
+        let element = hash64(key.as_bytes());
+        set!(&*self.set.borrow(), |set| set.contains(&element))
+    }
+
+    /// The keys still in the set, each once, in no particular order.
+    fn members(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let elements = set!(&*rb_self.set.borrow(), |set| set
+            .iter()
+            .collect::<Vec<u64>>());
+        names::members(ruby, &rb_self.names.borrow(), &elements)
+    }
+
+    fn size(&self) -> usize {
+        set!(&*self.set.borrow(), |set| set.len())
+    }
+
+    fn is_empty(&self) -> bool {
+        set!(&*self.set.borrow(), |set| set.is_empty())
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.set.borrow().clone();
+        let names = other.names.borrow().clone();
+        let Some(folded) = rb_self.set.borrow_mut().absorb(&source) else {
+            return Err(mismatch(ruby, "set"));
+        };
+        rb_self.names.borrow_mut().extend(names);
+        rb_self.prune();
+        capacity(ruby, folded)?;
+        Ok(rb_self)
+    }
+
+    /// The core frame followed by the names of every key it has seen added.
+    ///
+    /// ```text
+    /// core frame   OrSet::<u64, capacity>::ENCODED_LEN bytes, tag 0x82
+    /// name record  u64 little-endian byte length, then that many UTF-8 bytes
+    /// ```
+    ///
+    /// One record per add, tombstoned or not, in the core frame's order,
+    /// filling the rest of the blob. The frame holds 64-bit hashes, so
+    /// [`load`](Self::load) rehashes each name to rebuild what
+    /// [`members`](Self::members) reads.
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let (frame, elements) = set!(&*rb_self.set.borrow(), |set| (
+            set.encoded(),
+            set.adds().map(|add| add.element).collect::<Vec<u64>>()
+        ));
+        let mut blob = Vec::from(frame);
+        names::write(&mut blob, &rb_self.names.borrow(), elements.into_iter());
+        ruby.str_from_slice(&blob)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<MergeMachines::OrSet capacity={} size={}>",
+            self.capacity(),
+            self.size()
+        )
+    }
+
+    /// Leaves a name for every add the core holds, tombstoned or not, and for
+    /// nothing else.
+    ///
+    /// A merge extends the table before the core reports whether everything
+    /// fit, because a merge that overran capacity still took whatever it had
+    /// room for and those keys need their names. Reconciling afterwards keeps
+    /// the names of the adds that landed and drops the ones that did not.
+    fn prune(&self) {
+        let set = self.set.borrow();
+        self.names.borrow_mut().retain(|element, _| {
+            set!(&*set, |held| held.adds().any(|add| add.element == *element))
+        });
+    }
+
+    /// A counter no tag in this process has used, and above anything this
+    /// replica already used in this set.
+    ///
+    /// `None` once either counter has nothing left to count: reusing a tag
+    /// would make the core take the add for one it already holds and drop the
+    /// key without a word.
+    fn next_counter(&self, replica: ReplicaId) -> Option<u64> {
+        let used = |tag: Tag| (tag.replica == replica).then_some(tag.counter);
+        let highest = set!(&*self.set.borrow(), |set| set
+            .adds()
+            .map(|add| add.tag)
+            .chain(set.removes())
+            .filter_map(used)
+            .max())
+        .unwrap_or(0);
+
+        let minted = MINTED
+            .try_update(Ordering::Relaxed, Ordering::Relaxed, |minted| {
+                minted.checked_add(1)
+            })
+            .ok()?;
+        highest.max(minted).checked_add(1)
+    }
+}
+
+/// The variant for `capacity`, read from `blob` when there is one.
+fn dispatch(ruby: &Ruby, capacity: usize, blob: Option<&[u8]>) -> Result<Set, Error> {
+    let Some(frame) = blob else {
+        return Set::blank(capacity)
+            .ok_or_else(|| unsupported(ruby, "capacity", capacity, &CAPACITIES));
+    };
+    Set::decoded(ruby, capacity, frame)
+        .unwrap_or_else(|| Err(unsupported_blob(ruby, "capacity", &CAPACITIES)))
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("OrSet", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("capacity", method!(Wrapper::capacity, 0))?;
+    class.define_method("add", method!(Wrapper::add, -1))?;
+    class.define_method("remove", method!(Wrapper::remove, 1))?;
+    class.define_method("include?", method!(Wrapper::includes, 1))?;
+    class.define_method("members", method!(Wrapper::members, 0))?;
+    class.define_method("size", method!(Wrapper::size, 0))?;
+    class.define_method("empty?", method!(Wrapper::is_empty, 0))?;
+    class.define_method("merge", method!(Wrapper::merge, 1))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/merge_machines_native/ffi/src/pncounter.rs

@@ -0,0 +1,143 @@
+//! `MergeMachines::PNCounter`: a counter replicas can lower as well as raise.
+
+use std::cell::RefCell;
+
+use bytes::Bytes;
+use magnus::scan_args::scan_args;
+use magnus::typed_data::Obj;
+use magnus::{Error, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use merge_machines::PNCounter;
+
+use crate::gcounter::increment_args;
+use crate::shape::shaped;
+use crate::{
+    REPLICAS, Whole, blob_shape, capacity, mismatch, required_kwarg, unsupported, unsupported_blob,
+};
+
+/// The counter at a single replica count.
+type Held<const R: usize> = PNCounter<R>;
+
+shaped!(Counter over Held { R4 = 4, R8 = 8, R16 = 16, R32 = 32 });
+
+/// Runs `body` against whichever variant is held.
+macro_rules! counter {
+    ($counter:expr, |$inner:ident| $body:expr) => {
+        match $counter {
+            Counter::R4($inner) => $body,
+            Counter::R8($inner) => $body,
+            Counter::R16($inner) => $body,
+            Counter::R32($inner) => $body,
+        }
+    };
+}
+
+#[magnus::wrap(class = "MergeMachines::PNCounter", free_immediately, size)]
+struct Wrapper(RefCell<Counter>);
+
+const fn replicas_of<const R: usize>(_: &Held<R>) -> usize {
+    R
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(replicas): Whole<usize> = required_kwarg(args.keywords, "replicas")?;
+        Ok(Self(RefCell::new(dispatch(ruby, replicas, None)?)))
+    }
+
+    /// Reads a blob written by [`dump`](Self::dump).
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let replicas = blob_shape(ruby, &blob)?;
+        Ok(Self(RefCell::new(dispatch(ruby, replicas, Some(&blob))?)))
+    }
+
+    fn replicas(&self) -> usize {
+        counter!(&*self.0.borrow(), |counter| replicas_of(&**counter))
+    }
+
+    /// Adds `by:` to `replica:`'s own count.
+    fn increment(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (replica, by) = increment_args(args.keywords)?;
+        capacity(
+            ruby,
+            counter!(&mut *rb_self.0.borrow_mut(), |counter| counter
+                .increment(replica, by)),
+        )
+    }
+
+    /// Takes `by:` away on `replica:`'s own account.
+    fn decrement(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (replica, by) = increment_args(args.keywords)?;
+        capacity(
+            ruby,
+            counter!(&mut *rb_self.0.borrow_mut(), |counter| counter
+                .decrement(replica, by)),
+        )
+    }
+
+    /// Everything added, minus everything taken away.
+    fn value(&self) -> i128 {
+        counter!(&*self.0.borrow(), |counter| counter.value())
+    }
+
+    /// Everything added, by every replica.
+    fn added(&self) -> u128 {
+        counter!(&*self.0.borrow(), |counter| counter.added())
+    }
+
+    /// Everything taken away, by every replica.
+    fn removed(&self) -> u128 {
+        counter!(&*self.0.borrow(), |counter| counter.removed())
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.0.borrow().clone();
+        let Some(folded) = rb_self.0.borrow_mut().absorb(&source) else {
+            return Err(mismatch(ruby, "counter"));
+        };
+        capacity(ruby, folded)?;
+        Ok(rb_self)
+    }
+
+    /// The core frame, tag 0x62.
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let frame = counter!(&*rb_self.0.borrow(), |counter| counter.encoded());
+        ruby.str_from_slice(&frame)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<MergeMachines::PNCounter replicas={} value={}>",
+            self.replicas(),
+            self.value()
+        )
+    }
+}
+
+/// The variant for `replicas`, read from `blob` when there is one.
+fn dispatch(ruby: &Ruby, replicas: usize, blob: Option<&[u8]>) -> Result<Counter, Error> {
+    let Some(frame) = blob else {
+        return Counter::blank(replicas)
+            .ok_or_else(|| unsupported(ruby, "replicas", replicas, &REPLICAS));
+    };
+    Counter::decoded(ruby, replicas, frame)
+        .unwrap_or_else(|| Err(unsupported_blob(ruby, "replica count", &REPLICAS)))
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("PNCounter", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("replicas", method!(Wrapper::replicas, 0))?;
+    class.define_method("increment", method!(Wrapper::increment, -1))?;
+    class.define_method("decrement", method!(Wrapper::decrement, -1))?;
+    class.define_method("value", method!(Wrapper::value, 0))?;
+    class.define_method("added", method!(Wrapper::added, 0))?;
+    class.define_method("removed", method!(Wrapper::removed, 0))?;
+    class.define_method("merge", method!(Wrapper::merge, 1))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/merge_machines_native/ffi/src/shape.rs

@@ -0,0 +1,116 @@
+//! The shape a class is given, resolved to a monomorphised state.
+
+use magnus::{Error, Ruby};
+use merge_machines::CodecError;
+
+use crate::codec_error;
+
+/// A state at one const generic, and the core frame it encodes to.
+pub trait Framed: Sized {
+    /// Length of the core frame this state encodes to.
+    const FRAME_LEN: usize;
+
+    /// The state a class starts out holding.
+    fn blank() -> Self;
+
+    /// Reads a core frame over a state the caller already holds.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `frame` is too short,
+    /// [`CodecError::Tag`] when it holds another structure,
+    /// [`CodecError::Parameters`] when it was written at another shape.
+    fn read_frame(&mut self, frame: &[u8]) -> Result<(), CodecError>;
+}
+
+/// Length of the core frame `state` encodes to.
+pub const fn frame_len_of<T: Framed>(_state: &T) -> usize {
+    T::FRAME_LEN
+}
+
+/// Each shape is constructed behind its own call frame.
+#[inline(never)]
+pub fn boxed_new<T: Framed>() -> Box<T> {
+    Box::new(T::blank())
+}
+
+/// Each shape is read behind its own call frame.
+#[inline(never)]
+pub fn boxed_decode<T: Framed>(ruby: &Ruby, frame: &[u8]) -> Result<Box<T>, Error> {
+    let mut state = boxed_new::<T>();
+    state
+        .read_frame(frame)
+        .map_err(|error| codec_error(ruby, error))?;
+    Ok(state)
+}
+
+/// Defines the enum a class holds: one boxed variant per shape `held` is
+/// monomorphised at, where `held` is that state at a single shape, built by
+/// `held::new` and read by `held::decode_into`.
+///
+/// A class is a pointer wide whatever shape it was given, and every variant is
+/// built and read through [`boxed_new`] and [`boxed_decode`]. A shape no
+/// variant was monomorphised at, and a pairing of two different shapes, come
+/// back as `None` for the class to turn into the error its own callers expect.
+macro_rules! shaped {
+    ($name:ident over $held:ident { $($variant:ident = $shape:literal),+ $(,)? }) => {
+        impl<const SHAPE: usize> $crate::shape::Framed for $held<SHAPE> {
+            const FRAME_LEN: usize = Self::ENCODED_LEN;
+
+            fn blank() -> Self {
+                Self::new()
+            }
+
+            fn read_frame(&mut self, frame: &[u8]) -> Result<(), ::merge_machines::CodecError> {
+                self.decode_into(frame)
+            }
+        }
+
+        /// A state at one of the monomorphised shapes.
+        #[derive(Clone)]
+        enum $name {
+            $($variant(Box<$held<$shape>>),)+
+        }
+
+        impl $name {
+            /// The variant for `shape`, holding nothing, or `None` when no
+            /// variant was monomorphised at `shape`.
+            fn blank(shape: usize) -> Option<Self> {
+                match shape {
+                    $($shape => Some(Self::$variant($crate::shape::boxed_new())),)+
+                    _ => None,
+                }
+            }
+
+            /// The variant for `shape`, read from `frame`, or `None` when no
+            /// variant was monomorphised at `shape`.
+            fn decoded(
+                ruby: &::magnus::Ruby,
+                shape: usize,
+                frame: &[u8],
+            ) -> Option<Result<Self, ::magnus::Error>> {
+                match shape {
+                    $($shape => Some(
+                        $crate::shape::boxed_decode(ruby, frame).map(Self::$variant),
+                    ),)+
+                    _ => None,
+                }
+            }
+
+            /// Folds `other` in, or `None` when it holds another shape.
+            fn absorb(
+                &mut self,
+                other: &Self,
+            ) -> Option<Result<(), ::merge_machines::CapacityError>> {
+                match (self, other) {
+                    $((Self::$variant(target), Self::$variant(source)) => Some(
+                        <$held<$shape> as ::merge_machines::Merge>::merge(target, source),
+                    ),)+
+                    _ => None,
+                }
+            }
+        }
+    };
+}
+
+pub(crate) use shaped;

data/ext/merge_machines_native/ffi/src/wall.rs

@@ -0,0 +1,37 @@
+//! The wall-clock reading a hybrid timestamp is stamped at.
+//!
+//! `Process::CLOCK_REALTIME` is physical time two machines can compare. It
+//! steps backwards when the host's clock is corrected, and no deadline may be
+//! derived from it.
+
+use std::sync::OnceLock;
+
+use magnus::value::Opaque;
+use magnus::{Error, RModule, Ruby, Value, prelude::*};
+
+use crate::{defined_twice, uninitialised};
+
+static PROCESS: OnceLock<Opaque<RModule>> = OnceLock::new();
+static REALTIME: OnceLock<Opaque<Value>> = OnceLock::new();
+
+pub fn define(ruby: &Ruby) -> Result<(), Error> {
+    let process: RModule = ruby.class_object().const_get("Process")?;
+    let realtime: Value = process.const_get("CLOCK_REALTIME")?;
+    PROCESS
+        .set(process.into())
+        .map_err(|_| defined_twice(ruby, "Process"))?;
+    REALTIME
+        .set(realtime.into())
+        .map_err(|_| defined_twice(ruby, "Process::CLOCK_REALTIME"))
+}
+
+/// `Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)`.
+pub fn now_ns(ruby: &Ruby) -> Result<u64, Error> {
+    let (Some(process), Some(realtime)) = (PROCESS.get(), REALTIME.get()) else {
+        return Err(uninitialised(ruby));
+    };
+    ruby.get_inner(*process).funcall(
+        "clock_gettime",
+        (ruby.get_inner(*realtime), ruby.to_symbol("nanosecond")),
+    )
+}

data/lib/merge_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MergeMachines
+  VERSION = '0.2.0'
+end

data/lib/merge_machines.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'merge_machines/version'
+
+# GCounter, PNCounter, LwwRegister, GSet, OrSet, LogicalClock and HybridClock
+# are defined by the native extension; there is no pure-Ruby implementation to
+# fall back to.
+require 'merge_machines_native/merge_machines_native'