probabilistic_machines 0.1.1

data/ext/probabilistic_machines_native/ffi/src/cuckoo.rs

@@ -0,0 +1,149 @@
+//! `ProbabilisticMachines::CuckooFilter`: membership that can forget.
+
+use std::cell::RefCell;
+
+use bytes::Bytes;
+use magnus::scan_args::scan_args;
+use magnus::{Error, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use probabilistic_machines::{CodecError, CuckooFilter};
+
+use crate::{Whole, codec_error, full, required_kwarg, unsupported, unsupported_blob};
+
+/// Bucket counts [`Filter`] is monomorphised for.
+const BUCKETS: [usize; 4] = [1024, 4096, 16384, 65536];
+
+enum Filter {
+    B1024(Box<CuckooFilter<1024>>),
+    B4096(Box<CuckooFilter<4096>>),
+    B16384(Box<CuckooFilter<16384>>),
+    B65536(Box<CuckooFilter<65536>>),
+}
+
+/// Runs `body` against whichever variant is held.
+macro_rules! filter {
+    ($filter:expr, |$inner:ident| $body:expr) => {
+        match $filter {
+            Filter::B1024($inner) => $body,
+            Filter::B4096($inner) => $body,
+            Filter::B16384($inner) => $body,
+            Filter::B65536($inner) => $body,
+        }
+    };
+}
+
+#[magnus::wrap(class = "ProbabilisticMachines::CuckooFilter", free_immediately, size)]
+struct Wrapper(RefCell<Filter>);
+
+const fn buckets_of<const B: usize>(_: &CuckooFilter<B>) -> usize {
+    B
+}
+
+const fn capacity_of<const B: usize>(_: &CuckooFilter<B>) -> usize {
+    CuckooFilter::<B>::CAPACITY
+}
+
+/// Each shape is constructed behind its own call frame. Inlined, a debug build
+/// sizes one frame for every arm of the match below at once.
+#[inline(never)]
+fn boxed_new<const N: usize>() -> Box<CuckooFilter<N>> {
+    Box::new(CuckooFilter::new())
+}
+
+#[inline(never)]
+fn boxed_decode<const N: usize>(ruby: &Ruby, frame: &[u8]) -> Result<Box<CuckooFilter<N>>, Error> {
+    let mut filter = boxed_new::<N>();
+    filter
+        .decode_into(frame)
+        .map_err(|error| codec_error(ruby, error))?;
+    Ok(filter)
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(buckets): Whole<usize> = required_kwarg(args.keywords, "buckets")?;
+        let filter = match buckets {
+            1024 => Filter::B1024(boxed_new::<1024>()),
+            4096 => Filter::B4096(boxed_new::<4096>()),
+            16384 => Filter::B16384(boxed_new::<16384>()),
+            65536 => Filter::B65536(boxed_new::<65536>()),
+            _ => return Err(unsupported(ruby, "buckets", buckets, &BUCKETS)),
+        };
+        Ok(Self(RefCell::new(filter)))
+    }
+
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let Some(&exponent) = blob.get(1) else {
+            return Err(codec_error(ruby, CodecError::Truncated));
+        };
+        let filter = match exponent {
+            10 => Filter::B1024(boxed_decode::<1024>(ruby, &blob)?),
+            12 => Filter::B4096(boxed_decode::<4096>(ruby, &blob)?),
+            14 => Filter::B16384(boxed_decode::<16384>(ruby, &blob)?),
+            16 => Filter::B65536(boxed_decode::<65536>(ruby, &blob)?),
+            _ => return Err(unsupported_blob(ruby, "bucket count", &BUCKETS)),
+        };
+        Ok(Self(RefCell::new(filter)))
+    }
+
+    fn buckets(&self) -> usize {
+        filter!(&*self.0.borrow(), |filter| buckets_of(&**filter))
+    }
+
+    fn capacity(&self) -> usize {
+        filter!(&*self.0.borrow(), |filter| capacity_of(&**filter))
+    }
+
+    fn insert(ruby: &Ruby, rb_self: &Self, item: Bytes) -> Result<bool, Error> {
+        filter!(&mut *rb_self.0.borrow_mut(), |filter| filter.insert(&item))
+            .map(|()| true)
+            .map_err(|_| full(ruby))
+    }
+
+    fn contains(&self, item: Bytes) -> bool {
+        filter!(&*self.0.borrow(), |filter| filter.contains(&item))
+    }
+
+    fn remove(&self, item: Bytes) -> bool {
+        filter!(&mut *self.0.borrow_mut(), |filter| filter.remove(&item))
+    }
+
+    fn size(&self) -> usize {
+        filter!(&*self.0.borrow(), |filter| filter.len())
+    }
+
+    fn is_empty(&self) -> bool {
+        filter!(&*self.0.borrow(), |filter| filter.is_empty())
+    }
+
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let frame = filter!(&*rb_self.0.borrow(), |filter| filter.encoded());
+        ruby.str_from_slice(&frame)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<ProbabilisticMachines::CuckooFilter buckets={} size={} capacity={}>",
+            self.buckets(),
+            self.size(),
+            self.capacity()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("CuckooFilter", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("buckets", method!(Wrapper::buckets, 0))?;
+    class.define_method("capacity", method!(Wrapper::capacity, 0))?;
+    class.define_method("insert", method!(Wrapper::insert, 1))?;
+    class.define_method("include?", method!(Wrapper::contains, 1))?;
+    class.define_method("contains?", method!(Wrapper::contains, 1))?;
+    class.define_method("remove", method!(Wrapper::remove, 1))?;
+    class.define_method("size", method!(Wrapper::size, 0))?;
+    class.define_method("empty?", method!(Wrapper::is_empty, 0))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/probabilistic_machines_native/ffi/src/data.rs

@@ -0,0 +1,69 @@
+//! The frozen `Data` objects the sketches hand back.
+
+use std::sync::OnceLock;
+
+use magnus::value::Opaque;
+use magnus::{Error, RClass, RModule, RStruct, Ruby, Value, prelude::*};
+
+use crate::{defined_twice, uninitialised};
+
+static HITTER: OnceLock<Opaque<RClass>> = OnceLock::new();
+static CENTROID: OnceLock<Opaque<RClass>> = OnceLock::new();
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let hitter = ruby.define_data(None, ("key", "count", "overestimate"))?;
+    module.const_set("Hitter", hitter)?;
+    HITTER
+        .set(hitter.into())
+        .map_err(|_| defined_twice(ruby, "Hitter"))?;
+
+    let centroid = ruby.define_data(None, ("mean", "weight"))?;
+    module.const_set("Centroid", centroid)?;
+    CENTROID
+        .set(centroid.into())
+        .map_err(|_| defined_twice(ruby, "Centroid"))
+}
+
+/// A tracked key, its counter, and how much of that counter it inherited from
+/// keys evicted before it.
+pub fn hitter(ruby: &Ruby, key: Value, count: u64, overestimate: u64) -> Result<Value, Error> {
+    new_data(
+        ruby,
+        &HITTER,
+        [key, ruby.into_value(count), ruby.into_value(overestimate)],
+    )
+}
+
+/// One cluster of a digest: the mean of the values that collapsed into it.
+pub fn centroid(ruby: &Ruby, mean: f64, weight: f64) -> Result<Value, Error> {
+    new_data(
+        ruby,
+        &CENTROID,
+        [ruby.into_value(mean), ruby.into_value(weight)],
+    )
+}
+
+/// Instantiate one of our `Data` classes from its member values, in
+/// declaration order.
+///
+/// `Data#initialize` takes keywords only, so `new_instance` would need a
+/// temporary `Hash` per call plus a temporary `String` per key while magnus
+/// interns it. Allocating, filling the members by position and freezing is
+/// everything `Data#initialize` does, and both classes are defined here with
+/// no `initialize` override to skip.
+fn new_data<const N: usize>(
+    ruby: &Ruby,
+    slot: &OnceLock<Opaque<RClass>>,
+    members: [Value; N],
+) -> Result<Value, Error> {
+    let class = slot
+        .get()
+        .map(|class| ruby.get_inner(*class))
+        .ok_or_else(|| uninitialised(ruby))?;
+    let instance = RStruct::try_convert(class.obj_alloc()?)?;
+    for (index, value) in members.into_iter().enumerate() {
+        instance.aset(index, value)?;
+    }
+    instance.freeze();
+    Ok(instance.as_value())
+}

data/ext/probabilistic_machines_native/ffi/src/hyperloglog.rs

@@ -0,0 +1,155 @@
+//! `ProbabilisticMachines::HyperLogLog`: how many distinct items a stream held.
+
+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 probabilistic_machines::{CodecError, HyperLogLog};
+
+use crate::{Whole, codec_error, mismatch, required_kwarg, unsupported, unsupported_blob};
+
+/// Register counts [`Sketch`] is monomorphised for.
+const REGISTERS: [usize; 4] = [1024, 4096, 16384, 65536];
+
+#[derive(Clone)]
+enum Sketch {
+    M1024(Box<HyperLogLog<1024>>),
+    M4096(Box<HyperLogLog<4096>>),
+    M16384(Box<HyperLogLog<16384>>),
+    M65536(Box<HyperLogLog<65536>>),
+}
+
+/// Runs `body` against whichever variant is held.
+macro_rules! sketch {
+    ($sketch:expr, |$inner:ident| $body:expr) => {
+        match $sketch {
+            Sketch::M1024($inner) => $body,
+            Sketch::M4096($inner) => $body,
+            Sketch::M16384($inner) => $body,
+            Sketch::M65536($inner) => $body,
+        }
+    };
+}
+
+#[magnus::wrap(class = "ProbabilisticMachines::HyperLogLog", free_immediately, size)]
+struct Wrapper(RefCell<Sketch>);
+
+const fn registers_of<const M: usize>(_: &HyperLogLog<M>) -> usize {
+    M
+}
+
+fn standard_error_of<const M: usize>(_: &HyperLogLog<M>) -> f64 {
+    HyperLogLog::<M>::standard_error()
+}
+
+/// Each shape is constructed behind its own call frame. Inlined, a debug build
+/// sizes one frame for every arm of the match below at once.
+#[inline(never)]
+fn boxed_new<const N: usize>() -> Box<HyperLogLog<N>> {
+    Box::new(HyperLogLog::new())
+}
+
+#[inline(never)]
+fn boxed_decode<const N: usize>(ruby: &Ruby, frame: &[u8]) -> Result<Box<HyperLogLog<N>>, Error> {
+    let mut sketch = boxed_new::<N>();
+    sketch
+        .decode_into(frame)
+        .map_err(|error| codec_error(ruby, error))?;
+    Ok(sketch)
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(registers): Whole<usize> = required_kwarg(args.keywords, "registers")?;
+        let sketch = match registers {
+            1024 => Sketch::M1024(boxed_new::<1024>()),
+            4096 => Sketch::M4096(boxed_new::<4096>()),
+            16384 => Sketch::M16384(boxed_new::<16384>()),
+            65536 => Sketch::M65536(boxed_new::<65536>()),
+            _ => return Err(unsupported(ruby, "registers", registers, &REGISTERS)),
+        };
+        Ok(Self(RefCell::new(sketch)))
+    }
+
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let Some(&precision) = blob.get(1) else {
+            return Err(codec_error(ruby, CodecError::Truncated));
+        };
+        let sketch = match precision {
+            10 => Sketch::M1024(boxed_decode::<1024>(ruby, &blob)?),
+            12 => Sketch::M4096(boxed_decode::<4096>(ruby, &blob)?),
+            14 => Sketch::M16384(boxed_decode::<16384>(ruby, &blob)?),
+            16 => Sketch::M65536(boxed_decode::<65536>(ruby, &blob)?),
+            _ => return Err(unsupported_blob(ruby, "register count", &REGISTERS)),
+        };
+        Ok(Self(RefCell::new(sketch)))
+    }
+
+    fn registers(&self) -> usize {
+        sketch!(&*self.0.borrow(), |sketch| registers_of(&**sketch))
+    }
+
+    fn add(&self, item: Bytes) {
+        sketch!(&mut *self.0.borrow_mut(), |sketch| sketch.add(&item));
+    }
+
+    fn add_hash(&self, Whole(hash): Whole<u64>) {
+        sketch!(&mut *self.0.borrow_mut(), |sketch| sketch.add_hash(hash));
+    }
+
+    fn estimate(&self) -> f64 {
+        sketch!(&*self.0.borrow(), |sketch| sketch.estimate())
+    }
+
+    fn standard_error(&self) -> f64 {
+        sketch!(&*self.0.borrow(), |sketch| standard_error_of(&**sketch))
+    }
+
+    fn is_empty(&self) -> bool {
+        sketch!(&*self.0.borrow(), |sketch| sketch.is_empty())
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.0.borrow().clone();
+        match (&mut *rb_self.0.borrow_mut(), &source) {
+            (Sketch::M1024(target), Sketch::M1024(source)) => target.merge(source),
+            (Sketch::M4096(target), Sketch::M4096(source)) => target.merge(source),
+            (Sketch::M16384(target), Sketch::M16384(source)) => target.merge(source),
+            (Sketch::M65536(target), Sketch::M65536(source)) => target.merge(source),
+            _ => return Err(mismatch(ruby, "sketch")),
+        }
+        Ok(rb_self)
+    }
+
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let frame = sketch!(&*rb_self.0.borrow(), |sketch| sketch.encoded());
+        ruby.str_from_slice(&frame)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<ProbabilisticMachines::HyperLogLog registers={} estimate={:.1}>",
+            self.registers(),
+            self.estimate()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("HyperLogLog", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("registers", method!(Wrapper::registers, 0))?;
+    class.define_method("add", method!(Wrapper::add, 1))?;
+    class.define_method("add_hash", method!(Wrapper::add_hash, 1))?;
+    class.define_method("estimate", method!(Wrapper::estimate, 0))?;
+    class.define_method("standard_error", method!(Wrapper::standard_error, 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/probabilistic_machines_native/ffi/src/lib.rs

@@ -0,0 +1,140 @@
+//! Ruby bindings for the `probabilistic-machines` sketches.
+//!
+//! Every sketch is sized by a const generic, so each class dispatches the size
+//! it is given to a fixed set of monomorphised variants and raises
+//! `ArgumentError` for any other size.
+
+#![allow(clippy::needless_pass_by_value)]
+
+mod countmin;
+mod cuckoo;
+mod data;
+mod hyperloglog;
+mod tdigest;
+mod topk;
+
+use std::sync::OnceLock;
+
+use magnus::scan_args::get_kwargs;
+use magnus::value::Opaque;
+use magnus::{Error, ExceptionClass, Integer, RHash, RModule, Ruby, TryConvert, Value, prelude::*};
+use probabilistic_machines::CodecError;
+
+/// `ProbabilisticMachines::Full`, defined in [`init`].
+static FULL: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+
+/// A whole number of things: a count, a width, a depth, a `k`, a hash.
+///
+/// magnus reads an integer through Ruby's `NUM2*` family, which truncates a
+/// `Float` towards zero instead of refusing it, so an argument that means an
+/// integer is read as one of these and anything but an `Integer` is turned
+/// away. An `Integer` outside the target width still comes back as the
+/// `RangeError` magnus raises for it.
+pub(crate) struct Whole<T>(pub(crate) T);
+
+impl<T: TryConvert> TryConvert for Whole<T> {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(not_whole(value));
+        }
+        T::try_convert(value).map(Self)
+    }
+}
+
+fn not_whole(value: Value) -> Error {
+    let ruby = Ruby::get_with(value);
+    Error::new(
+        ruby.exception_type_error(),
+        format!(
+            "no implicit conversion of {} into Integer: {}",
+            value.class(),
+            value.inspect()
+        ),
+    )
+}
+
+/// The one required keyword of a constructor.
+pub(crate) fn required_kwarg<T: TryConvert>(keywords: RHash, name: &str) -> Result<T, Error> {
+    Ok(get_kwargs::<_, (T,), (), ()>(keywords, &[name], &[])?
+        .required
+        .0)
+}
+
+/// A keyword with a default the caller may leave out.
+pub(crate) fn optional_kwarg<T: TryConvert>(
+    keywords: RHash,
+    name: &str,
+) -> Result<Option<T>, Error> {
+    Ok(
+        get_kwargs::<_, (), (Option<T>,), ()>(keywords, &[], &[name])?
+            .optional
+            .0,
+    )
+}
+
+pub(crate) fn unsupported(ruby: &Ruby, name: &str, given: usize, supported: &[usize]) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("{name} {given} is not supported, expected one of {supported:?}"),
+    )
+}
+
+pub(crate) fn unsupported_blob(ruby: &Ruby, name: &str, supported: &[usize]) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("blob was written with a {name} outside {supported:?}"),
+    )
+}
+
+pub(crate) fn codec_error(ruby: &Ruby, error: CodecError) -> Error {
+    Error::new(ruby.exception_arg_error(), format!("codec: {error}"))
+}
+
+pub(crate) fn mismatch(ruby: &Ruby, name: &str) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("the other {name} has a different shape"),
+    )
+}
+
+pub(crate) fn uninitialised(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "the probabilistic_machines extension is not initialised",
+    )
+}
+
+pub(crate) fn defined_twice(ruby: &Ruby, name: &str) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        format!("ProbabilisticMachines::{name} was initialised twice"),
+    )
+}
+
+/// `ProbabilisticMachines::Full`, raised when a cuckoo filter cannot place an
+/// item after relocating its neighbours.
+pub(crate) fn full(ruby: &Ruby) -> Error {
+    FULL.get().map_or_else(
+        || uninitialised(ruby),
+        |class| Error::new(ruby.get_inner(*class), "the filter is full"),
+    )
+}
+
+fn define_errors(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let base = module.define_error("Error", ruby.exception_standard_error())?;
+    let full = module.define_error("Full", base)?;
+    FULL.set(full.into())
+        .map_err(|_| defined_twice(ruby, "Full"))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("ProbabilisticMachines")?;
+    define_errors(ruby, module)?;
+    data::define(ruby, module)?;
+    hyperloglog::define(ruby, module)?;
+    countmin::define(ruby, module)?;
+    tdigest::define(ruby, module)?;
+    cuckoo::define(ruby, module)?;
+    topk::define(ruby, module)
+}

data/ext/probabilistic_machines_native/ffi/src/tdigest.rs

@@ -0,0 +1,166 @@
+//! `ProbabilisticMachines::TDigest`: quantiles of a stream, in clusters.
+
+use std::cell::RefCell;
+
+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 probabilistic_machines::TDigest;
+
+use crate::data::centroid;
+use crate::{Whole, codec_error, optional_kwarg, required_kwarg};
+
+/// Below this the cluster budget is zero, so every point merges into one
+/// centroid and a quantile is meaningless.
+const MIN_COMPRESSION: u16 = 10;
+
+/// The compressions this binding answers for, whether the digest is being built
+/// or read back.
+fn honoured(ruby: &Ruby, compression: u16) -> Result<u16, Error> {
+    if compression < MIN_COMPRESSION {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!("compression must be at least {MIN_COMPRESSION}, got {compression}"),
+        ));
+    }
+    Ok(compression)
+}
+
+#[magnus::wrap(class = "ProbabilisticMachines::TDigest", free_immediately, size)]
+struct Wrapper(RefCell<TDigest>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(compression) = required_kwarg::<Whole<u16>>(args.keywords, "compression")?;
+        Ok(Self(RefCell::new(TDigest::new(honoured(
+            ruby,
+            compression,
+        )?))))
+    }
+
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let digest = TDigest::decode(&blob).map_err(|error| codec_error(ruby, error))?;
+        honoured(ruby, digest.compression())?;
+        Ok(Self(RefCell::new(digest)))
+    }
+
+    fn compression(&self) -> u16 {
+        self.0.borrow().compression()
+    }
+
+    fn add(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(f64,), (), (), (), RHash, ()>(args)?;
+        let (value,) = args.required;
+        let weight: f64 = optional_kwarg(args.keywords, "weight")?.unwrap_or(1.0);
+        if !value.is_finite() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("value must be finite, got {value}"),
+            ));
+        }
+        if !weight.is_finite() || weight <= 0.0 {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("weight must be finite and positive, got {weight}"),
+            ));
+        }
+        let count = rb_self.0.borrow().count();
+        if !(count + weight).is_finite() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("weight {weight} overflows the total weight {count}"),
+            ));
+        }
+        rb_self.0.borrow_mut().add_weighted(value, weight);
+        Ok(())
+    }
+
+    fn quantile(&self, q: f64) -> f64 {
+        self.0.borrow().quantile(q)
+    }
+
+    fn cdf(&self, value: f64) -> f64 {
+        self.0.borrow().cdf(value)
+    }
+
+    fn count(&self) -> f64 {
+        self.0.borrow().count()
+    }
+
+    fn minimum(&self) -> f64 {
+        self.0.borrow().minimum()
+    }
+
+    fn maximum(&self) -> f64 {
+        self.0.borrow().maximum()
+    }
+
+    fn size(&self) -> usize {
+        self.0.borrow().len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.0.borrow().is_empty()
+    }
+
+    fn centroids(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let digest = rb_self.0.borrow();
+        let clusters = ruby.ary_new_capa(digest.len());
+        for cluster in digest.centroids() {
+            clusters.push(centroid(ruby, cluster.mean, cluster.weight)?)?;
+        }
+        Ok(clusters)
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.0.borrow().clone();
+        let count = rb_self.0.borrow().count();
+        if !(count + source.count()).is_finite() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!(
+                    "total weight {} overflows the total weight {count}",
+                    source.count()
+                ),
+            ));
+        }
+        rb_self.0.borrow_mut().merge(&source);
+        Ok(rb_self)
+    }
+
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        ruby.str_from_slice(&rb_self.0.borrow().encoded())
+    }
+
+    fn inspect(&self) -> String {
+        let digest = self.0.borrow();
+        format!(
+            "#<ProbabilisticMachines::TDigest compression={} count={} centroids={}>",
+            digest.compression(),
+            digest.count(),
+            digest.len()
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("TDigest", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("compression", method!(Wrapper::compression, 0))?;
+    class.define_method("add", method!(Wrapper::add, -1))?;
+    class.define_method("quantile", method!(Wrapper::quantile, 1))?;
+    class.define_method("cdf", method!(Wrapper::cdf, 1))?;
+    class.define_method("count", method!(Wrapper::count, 0))?;
+    class.define_method("minimum", method!(Wrapper::minimum, 0))?;
+    class.define_method("maximum", method!(Wrapper::maximum, 0))?;
+    class.define_method("size", method!(Wrapper::size, 0))?;
+    class.define_method("empty?", method!(Wrapper::is_empty, 0))?;
+    class.define_method("centroids", method!(Wrapper::centroids, 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(())
+}