carray 3.0.0 → 3.0.2

data/ext/carray_random.c

@@ -9,7 +9,7 @@
   (rb_random_*).
 
   Dispatch:
-    random!       -> uniform fill (per-dtype branch below)
+    random!       -> uniform fill (per-type branch below)
     randomn!      -> standard normal via Box-Muller (float / complex only)
     shuffle!      -> Fisher-Yates over the flat buffer, or per-slice
                      when axis: is given (byte-chunk swap)
@@ -20,24 +20,111 @@
 #include "carray.h"
 #include <math.h>
 #include <string.h>
+#include <stdint.h>
+
+/* The generator itself, shared verbatim with carray-jit.  See the file's
+   own comment for why it carries no include guard. */
+#include "ca_rng_normal.h"
+#include "ca_rng_xoshiro256pp.h"
+
+VALUE rb_cCARng;
+
+/* Where a fill's numbers come from.  Resolved once per call rather than
+   per cell: the `rng:` argument is one object for the whole array, and
+   asking what it is inside the loop would put a Ruby type test between
+   every pair of draws.
+
+   CA_RNG_OWN holds the state's cells directly.  That array belongs to
+   the CArray::Rng the caller passed, so the draws advance it and the
+   next call -- here or in a kernel -- carries on from where this one
+   stopped. */
+enum {
+  CA_RNG_DEFAULT = 0,  /* no rng: given -- the per-ractor MT */
+  CA_RNG_RUBY    = 1,  /* a ::Random instance -- also MT */
+  CA_RNG_OWN     = 2   /* a CArray::Rng -- the generator above */
+};
+
+typedef struct {
+  int kind;
+  VALUE rng;
+  CArray *state;       /* attached for CA_RNG_OWN, else NULL */
+  int64_t *cells;
+} ca_rng_t;
 
+static void
+ca_rng_open (VALUE rng, ca_rng_t *source)
+{
+  source->rng = rng;
+  source->state = NULL;
+  source->cells = NULL;
+  if (NIL_P(rng)) {
+    source->kind = CA_RNG_DEFAULT;
+  }
+  else if (rb_obj_is_kind_of(rng, rb_cCARng)) {
+    VALUE state = rb_ivar_get(rng, rb_intern("@state"));
+    CArray *ca;
+    TypedData_Get_Struct(state, CArray, &carray_data_type, ca);
+    ca_attach(ca);
+    source->kind = CA_RNG_OWN;
+    source->state = ca;
+    source->cells = (int64_t *) ca->ptr;
+  }
+  else {
+    source->kind = CA_RNG_RUBY;
+  }
+}
+
+/* Writes the advanced state back where it came from.  Safe to call twice,
+   which is what lets an error path close before it raises. */
+static void
+ca_rng_close (ca_rng_t *source)
+{
+  if (source->state) {
+    ca_sync(source->state);
+    ca_detach(source->state);
+    source->state = NULL;
+    source->cells = NULL;
+  }
+}
 
 static inline double
-ca_random_real(VALUE rng)
+ca_random_real (ca_rng_t *source)
 {
-  if (NIL_P(rng))
-    return rb_genrand_real();
-  else
-    return rb_random_real(rng);
+  switch (source->kind) {
+  case CA_RNG_OWN:    return ca_xoshiro256pp_next_real(source->cells);
+  case CA_RNG_RUBY:   return rb_random_real(source->rng);
+  default:            return rb_genrand_real();
+  }
+}
+
+/* A draw in [0, limit], inclusive, matching what Ruby's own bounded draw
+   promises.  For the generator above that is rejection sampling: taking
+   the remainder alone would favour the low end of the range whenever the
+   range does not divide 2**64. */
+static inline uint64_t
+ca_xoshiro256pp_below (int64_t *state, uint64_t range)
+{
+  uint64_t threshold, draw;
+  if (range == 0) return ca_xoshiro256pp_next(state);   /* the whole word */
+  threshold = (0 - range) % range;                      /* 2**64 mod range */
+  do {
+    draw = ca_xoshiro256pp_next(state);
+  } while (draw < threshold);
+  return draw % range;
 }
 
 static inline unsigned long
-ca_random_ulong_limited(VALUE rng, unsigned long limit)
+ca_random_ulong_limited (ca_rng_t *source, unsigned long limit)
 {
-  if (NIL_P(rng))
+  switch (source->kind) {
+  case CA_RNG_OWN:
+    return (unsigned long)
+             ca_xoshiro256pp_below(source->cells, (uint64_t) limit + 1);
+  case CA_RNG_RUBY:
+    return rb_random_ulong_limited(source->rng, limit);
+  default:
     return rb_genrand_ulong_limited(limit);
-  else
-    return rb_random_ulong_limited(rng, limit);
+  }
 }
 
 /* ---- random! ----------------------------------------------------------- */
@@ -72,6 +159,7 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
   unsigned long limit = 0;
   ca_size_t i, n;
   VALUE rng = Qnil;
+  ca_rng_t source;
 
   rb_scan_args(argc, argv, "02:", &arg1, &arg2, &opts);
   rb_scan_options(opts, "rng", &rng);
@@ -109,13 +197,13 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
   }
 
   /* Materialize (low, high) as the correct scalar type and validate.
-   * For integer dtypes, `..` closed adds 1 to high (turns into half-open
-   * for the sampler); for float dtypes, closed and half-open are
+   * For integer data types, `..` closed adds 1 to high (turns into half-open
+   * for the sampler); for float data types, closed and half-open are
    * equivalent so no adjustment. */
   if (!is_default) {
-    int is_integer_dtype = (ca->data_type >= CA_INT8
+    int is_integer_type = (ca->data_type >= CA_INT8
                             && ca->data_type <= CA_UINT64);
-    if (is_integer_dtype) {
+    if (is_integer_type) {
       low_long  = NUM2LONG(low_val);
       high_long = NUM2LONG(high_val);
       if (high_is_closed) high_long += 1;
@@ -140,17 +228,18 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
 
   n = ca->elements;
   ca_attach(ca);
+  ca_rng_open(rng, &source);
 
   switch (ca->data_type) {
   case CA_FLOAT64: {
     double *p = (double *)ca->ptr;
     if (is_default) {
       for (i = 0; i < n; i++)
-        p[i] = ca_random_real(rng);
+        p[i] = ca_random_real(&source);
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = low_dbl + ca_random_real(rng) * range;
+        p[i] = low_dbl + ca_random_real(&source) * range;
     }
     break;
   }
@@ -158,11 +247,11 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
     float *p = (float *)ca->ptr;
     if (is_default) {
       for (i = 0; i < n; i++)
-        p[i] = (float)ca_random_real(rng);
+        p[i] = (float)ca_random_real(&source);
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (float)(low_dbl + ca_random_real(rng) * range);
+        p[i] = (float)(low_dbl + ca_random_real(&source) * range);
     }
     break;
   }
@@ -170,12 +259,12 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
     double complex *p = (double complex *)ca->ptr;
     if (is_default) {
       for (i = 0; i < n; i++)
-        p[i] = ca_random_real(rng) + ca_random_real(rng) * I;
+        p[i] = ca_random_real(&source) + ca_random_real(&source) * I;
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (low_dbl + ca_random_real(rng) * range)
-             + (low_dbl + ca_random_real(rng) * range) * I;
+        p[i] = (low_dbl + ca_random_real(&source) * range)
+             + (low_dbl + ca_random_real(&source) * range) * I;
     }
     break;
   }
@@ -183,24 +272,25 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
     float complex *p = (float complex *)ca->ptr;
     if (is_default) {
       for (i = 0; i < n; i++)
-        p[i] = (float)ca_random_real(rng) + (float)ca_random_real(rng) * I;
+        p[i] = (float)ca_random_real(&source) + (float)ca_random_real(&source) * I;
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (float)(low_dbl + ca_random_real(rng) * range)
-             + (float)(low_dbl + ca_random_real(rng) * range) * I;
+        p[i] = (float)(low_dbl + ca_random_real(&source) * range)
+             + (float)(low_dbl + ca_random_real(&source) * range) * I;
     }
     break;
   }
   case CA_BOOLEAN: {
     boolean8_t *p = (boolean8_t *)ca->ptr;
     for (i = 0; i < n; i++)
-      p[i] = (ca_random_real(rng) < 0.5) ? 1 : 0;
+      p[i] = (ca_random_real(&source) < 0.5) ? 1 : 0;
     break;
   }
   default: {
     /* integer types: CA_INT8..CA_UINT64 */
     if (is_default) {
+      ca_rng_close(&source);
       ca_sync(ca);
       ca_detach(ca);
       rb_raise(rb_eArgError,
@@ -212,52 +302,53 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
     case CA_INT8: {
       int8_t *p = (int8_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (int8_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (int8_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_UINT8: {
       uint8_t *p = (uint8_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (uint8_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (uint8_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_INT16: {
       int16_t *p = (int16_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (int16_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (int16_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_UINT16: {
       uint16_t *p = (uint16_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (uint16_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (uint16_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_INT32: {
       int32_t *p = (int32_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (int32_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (int32_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_UINT32: {
       uint32_t *p = (uint32_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (uint32_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (uint32_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_INT64: {
       int64_t *p = (int64_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (int64_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (int64_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     case CA_UINT64: {
       uint64_t *p = (uint64_t *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (uint64_t)(low_long + ca_random_ulong_limited(rng, limit));
+        p[i] = (uint64_t)(low_long + ca_random_ulong_limited(&source, limit));
       break;
     }
     default:
+      ca_rng_close(&source);
       ca_sync(ca);
       ca_detach(ca);
       rb_raise(rb_eCADataTypeError,
@@ -267,6 +358,7 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
   }
   }
 
+  ca_rng_close(&source);
   ca_sync(ca);
   ca_detach(ca);
   return self;
@@ -274,13 +366,30 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
 
 /* ---- randomn! ---------------------------------------------------------- */
 
+/* One standard normal from the resolved source.
+ *
+ * For CArray::Rng this is two draws and no spare, which is what
+ * ca_rng_normal is and what lets a kernel's `randomn` continue a
+ * `randomn!` -- both are this function, called once per cell.
+ *
+ * For Ruby's MT the paired form below is kept: nothing there draws one
+ * at a time, so there is no second caller to agree with, and changing it
+ * would change the numbers an existing call gets. */
+static inline double
+ca_random_normal (ca_rng_t *source)
+{
+  double u1 = ca_random_real(source);
+  double u2 = ca_random_real(source);
+  return ca_rng_normal(u1, u2);
+}
+
 static inline void
-box_muller_pair(VALUE rng, double *r1, double *r2)
+box_muller_pair(ca_rng_t *source, double *r1, double *r2)
 {
-  double u1 = ca_random_real(rng);
-  double u2 = ca_random_real(rng);
+  double u1 = ca_random_real(source);
+  double u2 = ca_random_real(source);
   while (u1 == 0.0)
-    u1 = ca_random_real(rng);
+    u1 = ca_random_real(source);
   double r = sqrt(-2.0 * log(u1));
   double theta = 2.0 * M_PI * u2;
   *r1 = r * cos(theta);
@@ -290,7 +399,7 @@ box_muller_pair(VALUE rng, double *r1, double *r2)
 /* CArray#randomn!(rng:) — fill self with standard normal N(0, 1)
  * samples in-place via Box-Muller, returning self.
  *
- * Restricted to float / complex dtypes.  Complex fills real + imag as
+ * Restricted to float / complex data types.  Complex fills real + imag as
  * two independent normals per cell. */
 static VALUE
 rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
@@ -301,6 +410,7 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
 
   rb_scan_args(argc, argv, "0:", &opts);
   VALUE rng = Qnil;
+  ca_rng_t source;
   rb_scan_options(opts, "rng", &rng);
 
   rb_ca_modify(self);
@@ -314,17 +424,66 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
 
   n = ca->elements;
   ca_attach(ca);
+  ca_rng_open(rng, &source);
+
+  /* A CArray::Rng fills one cell per call rather than two, so that this
+     and a kernel drawing afterwards are the one sequence: both are
+     `ca_random_normal` run once per cell.  It costs a draw a cell over
+     the paired form, and what it buys is that where the generator
+     stands can be worked out rather than run. */
+  if (source.kind == CA_RNG_OWN) {
+    switch (ca->data_type) {
+    case CA_FLOAT64: {
+      double *p = (double *)ca->ptr;
+      for (i = 0; i < n; i++)
+        p[i] = ca_random_normal(&source);
+      break;
+    }
+    case CA_FLOAT32: {
+      float *p = (float *)ca->ptr;
+      for (i = 0; i < n; i++)
+        p[i] = (float) ca_random_normal(&source);
+      break;
+    }
+    case CA_CMPLX128: {
+      double complex *p = (double complex *)ca->ptr;
+      for (i = 0; i < n; i++) {
+        /* Into locals first: C does not say which order a call's
+           arguments are evaluated in, and these two advance a state. */
+        double re = ca_random_normal(&source);
+        double im = ca_random_normal(&source);
+        p[i] = re + im * I;
+      }
+      break;
+    }
+    case CA_CMPLX64: {
+      float complex *p = (float complex *)ca->ptr;
+      for (i = 0; i < n; i++) {
+        double re = ca_random_normal(&source);
+        double im = ca_random_normal(&source);
+        p[i] = (float) re + (float) im * I;
+      }
+      break;
+    }
+    default:
+      break;
+    }
+    ca_rng_close(&source);
+    ca_sync(ca);
+    ca_detach(ca);
+    return self;
+  }
 
   switch (ca->data_type) {
   case CA_FLOAT64: {
     double *p = (double *)ca->ptr;
     ca_size_t pairs = n / 2;
     for (i = 0; i < pairs; i++) {
-      box_muller_pair(rng, &p[2*i], &p[2*i+1]);
+      box_muller_pair(&source, &p[2*i], &p[2*i+1]);
     }
     if (n % 2 == 1) {
       double r1, r2;
-      box_muller_pair(rng, &r1, &r2);
+      box_muller_pair(&source, &r1, &r2);
       p[n-1] = r1;
     }
     break;
@@ -334,13 +493,13 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     ca_size_t pairs = n / 2;
     for (i = 0; i < pairs; i++) {
       double r1, r2;
-      box_muller_pair(rng, &r1, &r2);
+      box_muller_pair(&source, &r1, &r2);
       p[2*i]   = (float)r1;
       p[2*i+1] = (float)r2;
     }
     if (n % 2 == 1) {
       double r1, r2;
-      box_muller_pair(rng, &r1, &r2);
+      box_muller_pair(&source, &r1, &r2);
       p[n-1] = (float)r1;
     }
     break;
@@ -349,7 +508,7 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     double complex *p = (double complex *)ca->ptr;
     for (i = 0; i < n; i++) {
       double r1, r2;
-      box_muller_pair(rng, &r1, &r2);
+      box_muller_pair(&source, &r1, &r2);
       p[i] = r1 + r2 * I;
     }
     break;
@@ -358,7 +517,7 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     float complex *p = (float complex *)ca->ptr;
     for (i = 0; i < n; i++) {
       double r1, r2;
-      box_muller_pair(rng, &r1, &r2);
+      box_muller_pair(&source, &r1, &r2);
       p[i] = (float)r1 + (float)r2 * I;
     }
     break;
@@ -367,6 +526,7 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     break;
   }
 
+  ca_rng_close(&source);
   ca_sync(ca);
   ca_detach(ca);
   return self;
@@ -399,6 +559,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
 
   rb_scan_args(argc, argv, "0:", &opts);
   VALUE rng = Qnil;
+  ca_rng_t source;
   rb_scan_options(opts, "rng,axis", &rng, &v_axis);
 
   rb_ca_modify(self);
@@ -407,6 +568,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
   if (ca->elements <= 1) return self;
 
   ca_attach(ca);
+  ca_rng_open(rng, &source);
 
   if (NIL_P(v_axis)) {
     /* shuffle all elements */
@@ -416,7 +578,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
     char *p = ca->ptr;
 
     for (ca_size_t i = n - 1; i > 0; i--) {
-      unsigned long j = ca_random_ulong_limited(rng, (unsigned long)i);
+      unsigned long j = ca_random_ulong_limited(&source, (unsigned long)i);
       if ((ca_size_t)j != i) {
         swap_chunks(p + i * elem_bytes, p + j * elem_bytes, elem_bytes, tmp);
       }
@@ -427,6 +589,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
     axis = NUM2INT(v_axis);
     if (axis < 0) axis += ca->ndim;
     if (axis < 0 || axis >= ca->ndim) {
+      ca_rng_close(&source);
       ca_sync(ca);
       ca_detach(ca);
       rb_raise(rb_eArgError,
@@ -435,6 +598,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
 
     n = ca->dim[axis];
     if (n <= 1) {
+      ca_rng_close(&source);
       ca_sync(ca);
       ca_detach(ca);
       return self;
@@ -455,7 +619,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
     for (ca_size_t o = 0; o < outer; o++) {
       char *base = ca->ptr + o * stride;
       for (ca_size_t i = n - 1; i > 0; i--) {
-        unsigned long j = ca_random_ulong_limited(rng, (unsigned long)i);
+        unsigned long j = ca_random_ulong_limited(&source, (unsigned long)i);
         if ((ca_size_t)j != i) {
           swap_chunks(base + i * chunk_bytes,
                       base + j * chunk_bytes,
@@ -466,6 +630,7 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
     xfree(tmp);
   }
 
+  ca_rng_close(&source);
   ca_sync(ca);
   ca_detach(ca);
   return self;
@@ -484,7 +649,7 @@ rb_ca_shuffle(int argc, VALUE *argv, VALUE self)
 /* ---- random (copy) ----------------------------------------------------- */
 
 /* CArray#random([low,] [high], rng:) — non-bang variant: return a
- * newly templated array filled uniformly.  Shape and dtype come from
+ * newly templated array filled uniformly.  Shape and data type come from
  * CArray#template, so the receiver is only consulted for those.
  * Accepts the same argument forms as {rb_ca_random_bang}. */
 static VALUE
@@ -503,11 +668,190 @@ rb_ca_randomn(int argc, VALUE *argv, VALUE self)
   return rb_ca_randomn_bang(argc, argv, copy);
 }
 
+/* ---- CArray::Rng ---------------------------------------------------- */
+
+/* A generator with its own state, so that a sequence belongs to an object
+ * rather than to the process:
+ *
+ *   r = CArray::Rng.new(seed: 4)
+ *   a.random!(rng: r)                        # fills, advancing r
+ *   CArray.jit_for(n) { |i| b[i] = r.call }  # carries on from there
+ *
+ * The state is an ordinary CA_INT64 array of four cells, which is what
+ * lets the second line work: carray-jit hands that array's address to a
+ * kernel that pasted the same generator, and the kernel advances the
+ * same cells this file does.  Nothing about the generator is hidden
+ * behind a struct only this extension can read.
+ *
+ * The seed is not part of the state.  It is remembered so that #reset
+ * with no argument can repeat a run, and so `inspect` can say what a
+ * generator was started from. */
+
+static VALUE rb_ca_rng_reset (int argc, VALUE *argv, VALUE self);
+
+/* The state's cells, attached.  Every entry point here goes through this
+ * rather than reaching into the ivar, so that "what is the state" has one
+ * answer even after another generator is added. */
+static CArray *
+ca_rng_cells (VALUE self, int64_t **cells)
+{
+  CArray *ca;
+  VALUE state = rb_ivar_get(self, rb_intern("@state"));
+  TypedData_Get_Struct(state, CArray, &carray_data_type, ca);
+  ca_attach(ca);
+  *cells = (int64_t *) ca->ptr;
+  return ca;
+}
+
+/* CArray::Rng.new(generator = :xoshiro256pp, seed: nil) */
+static VALUE
+rb_ca_rng_initialize (int argc, VALUE *argv, VALUE self)
+{
+  VALUE gen = Qnil, opts = Qnil, seed = Qnil, state;
+
+  rb_scan_args(argc, argv, "01:", &gen, &opts);
+  rb_scan_options(opts, "seed", &seed);
+
+  if (NIL_P(gen)) gen = ID2SYM(rb_intern("xoshiro256pp"));
+  if (!SYMBOL_P(gen) || SYM2ID(gen) != rb_intern("xoshiro256pp")) {
+    rb_raise(rb_eArgError,
+             "unknown generator %"PRIsVALUE"; carray has :xoshiro256pp",
+             rb_inspect(gen));
+  }
+
+  state = rb_funcall(rb_cCArray, rb_intern("int64"), 1, INT2FIX(4));
+  rb_ivar_set(self, rb_intern("@generator"), gen);
+  rb_ivar_set(self, rb_intern("@state"), state);
+
+  return rb_ca_rng_reset(NIL_P(seed) ? 0 : 1, &seed, self);
+}
+
+/* CArray::Rng#reset(seed = nil) — start the sequence over.
+ *
+ * With no argument, from the seed this generator already carries, which
+ * repeats the run exactly.  A generator made without a seed is given one
+ * from Random.new_seed, so two of them differ; that drawn seed is kept,
+ * so even an unseeded run can be repeated once it has begun. */
+static VALUE
+rb_ca_rng_reset (int argc, VALUE *argv, VALUE self)
+{
+  VALUE seed = Qnil, masked;
+  CArray *ca;
+  int64_t *cells;
+
+  rb_scan_args(argc, argv, "01", &seed);
+  if (NIL_P(seed)) seed = rb_ivar_get(self, rb_intern("@seed"));
+  if (NIL_P(seed)) {
+    seed = rb_funcall(rb_path2class("Random"), rb_intern("new_seed"), 0);
+  }
+
+  /* Any Integer is a seed: a negative one and one wider than a word are
+     folded into 64 bits rather than refused, which is what `&` does. */
+  masked = rb_funcall(rb_to_int(seed), rb_intern("&"),
+                      1, ULL2NUM(0xFFFFFFFFFFFFFFFFULL));
+
+  ca = ca_rng_cells(self, &cells);
+  ca_xoshiro256pp_seed(cells, (uint64_t) NUM2ULL(masked));
+  ca_sync(ca);
+  ca_detach(ca);
+
+  rb_ivar_set(self, rb_intern("@seed"), seed);
+  return self;
+}
+
+/* CArray::Rng#random — one draw in [0.0, 1.0), the state advanced.
+ *
+ * Named for `CArray#random!`, which it is the one-cell form of, and to
+ * pair with `#randomn` the way those two pair.  Not `#rand`: Ruby's
+ * `random:` keyword calls `rand(n)` on what it is given, and a `#rand`
+ * here that takes no argument would make this look usable there and
+ * then fail with an arity error rather than say what it is.
+ *
+ * It is the same draw `random!` takes for one cell, and the same one a
+ * kernel's `random(rng:)` takes, because all three run the code in
+ * ca_rng_xoshiro256pp.h. */
+static VALUE
+rb_ca_rng_random (VALUE self)
+{
+  CArray *ca;
+  int64_t *cells;
+  double value;
+
+  ca = ca_rng_cells(self, &cells);
+  value = ca_xoshiro256pp_next_real(cells);
+  ca_sync(ca);
+  ca_detach(ca);
+  return rb_float_new(value);
+}
+
+/* CArray::Rng#bits — the same draw as the generator's raw 64 bits.
+ *
+ * Not a bounded draw and not Ruby's `rand(n)`: it is the word the
+ * generator produced, before it was turned into a double.  What that is
+ * for is checking this generator against the sequence its authors
+ * published, which is the one question `#rand` cannot answer. */
+static VALUE
+rb_ca_rng_bits (VALUE self)
+{
+  CArray *ca;
+  int64_t *cells;
+  uint64_t value;
+
+  ca = ca_rng_cells(self, &cells);
+  value = ca_xoshiro256pp_next(cells);
+  ca_sync(ca);
+  ca_detach(ca);
+  return ULL2NUM(value);
+}
+
+/* CArray::Rng#randomn — one standard normal, which is two draws.
+ *
+ * The same one `randomn!(rng: self)` writes into a cell and the same
+ * one a kernel's `randomn(rng: self)` takes, because all three are
+ * ca_random_normal. */
+static VALUE
+rb_ca_rng_randomn (VALUE self)
+{
+  CArray *ca;
+  int64_t *cells;
+  ca_rng_t source;
+  double value;
+
+  ca = ca_rng_cells(self, &cells);
+  source.kind = CA_RNG_OWN;
+  source.rng = self;
+  source.state = NULL;
+  source.cells = cells;
+  value = ca_random_normal(&source);
+  ca_sync(ca);
+  ca_detach(ca);
+  return rb_float_new(value);
+}
+
+static VALUE
+rb_ca_rng_inspect (VALUE self)
+{
+  return rb_sprintf("#<CArray::Rng %"PRIsVALUE" seed=%"PRIsVALUE">",
+                    rb_ivar_get(self, rb_intern("@generator")),
+                    rb_ivar_get(self, rb_intern("@seed")));
+}
+
 /* ---- Init -------------------------------------------------------------- */
 
 void
 Init_carray_random (void)
 {
+  rb_cCARng = rb_define_class_under(rb_cCArray, "Rng", rb_cObject);
+  rb_define_method(rb_cCARng, "initialize", rb_ca_rng_initialize, -1);
+  rb_define_method(rb_cCARng, "reset",      rb_ca_rng_reset,      -1);
+  rb_define_method(rb_cCARng, "random",     rb_ca_rng_random,      0);
+  rb_define_method(rb_cCARng, "randomn",    rb_ca_rng_randomn,     0);
+  rb_define_method(rb_cCARng, "bits",       rb_ca_rng_bits,        0);
+  rb_define_method(rb_cCARng, "inspect",    rb_ca_rng_inspect,     0);
+  rb_define_attr(rb_cCARng, "generator", 1, 0);
+  rb_define_attr(rb_cCARng, "state",     1, 0);
+  rb_define_attr(rb_cCARng, "seed",      1, 0);
+
   rb_define_method(rb_cCArray, "random!",  rb_ca_random_bang,  -1);
   rb_define_method(rb_cCArray, "randomn!", rb_ca_randomn_bang, -1);
   rb_define_method(rb_cCArray, "shuffle!", rb_ca_shuffle_bang, -1);