carray 3.0.2 → 3.0.4

data/ext/carray_random.c

@@ -18,6 +18,7 @@
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "carray_internal.h"   /* ca_attach_window */
 #include <math.h>
 #include <string.h>
 #include <stdint.h>
@@ -47,12 +48,12 @@ enum {
 typedef struct {
   int kind;
   VALUE rng;
-  CArray *state;       /* attached for CA_RNG_OWN, else NULL */
-  int64_t *cells;
+  CArray *state;       /* the CArray::Rng state for CA_RNG_OWN, else NULL */
+  int64_t *cells;      /* state->ptr, once the window has attached it */
 } ca_rng_t;
 
 static void
-ca_rng_open (VALUE rng, ca_rng_t *source)
+ca_rng_resolve (VALUE rng, ca_rng_t *source)
 {
   source->rng = rng;
   source->state = NULL;
@@ -64,27 +65,48 @@ ca_rng_open (VALUE rng, ca_rng_t *source)
     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. */
+/* The fills below draw inside a window over the array and, for a
+   CArray::Rng, the generator's state.  A Ruby generator (rng: a
+   ::Random or anything with #rand) is called per draw and can raise part
+   way; the window then pushes back the cells drawn so far, and the state
+   they advanced, as it does when the fill completes. */
+
+typedef struct {
+  CArray        *ca;
+  ca_rng_t       source;
+  ca_size_t      n;
+  int            is_default;
+  double         low_dbl, high_dbl;
+  long           low_long;
+  unsigned long  limit;
+  int            axis;           /* shuffle!: -1 = all cells */
+  CArray        *mask;           /* shuffle!: self's mask, moved with the values */
+} ca_random_ctx_t;
+
 static void
-ca_rng_close (ca_rng_t *source)
+ca_random_run (ca_random_ctx_t *c, VALUE rng, VALUE (*fill)(VALUE))
 {
-  if (source->state) {
-    ca_sync(source->state);
-    ca_detach(source->state);
-    source->state = NULL;
-    source->cells = NULL;
-  }
+  CArray *list[3];
+  ca_rng_resolve(rng, &c->source);
+  list[0] = c->ca;
+  list[1] = c->source.state;
+  list[2] = c->mask;
+  ca_attach_window(c->mask ? 3 : 2, list, "www", fill, (VALUE) c);
+}
+
+/* The state is attached once the window is open. */
+static void
+ca_rng_bind (ca_rng_t *source)
+{
+  source->cells = source->state ? (int64_t *) source->state->ptr : NULL;
 }
 
 static inline double
@@ -129,117 +151,28 @@ ca_random_ulong_limited (ca_rng_t *source, unsigned long limit)
 
 /* ---- random! ----------------------------------------------------------- */
 
-/* CArray#random!([low,] [high], rng:) — fill self with uniform random
- * numbers in-place, returning self.  Range surface mirrors Numo/NumPy
- * (half-open [low, high) as the default) plus Ruby idiom (`..` closed,
- * `...` half-open):
- *
- *   random!                    float [0.0, 1.0); integer -> ArgumentError
- *   random!(high)              [0, high)                (Ruby rand shorthand)
- *   random!(low, high)         [low, high)              (Numo positional)
- *   random!(a..b)              [a, b]  closed           (integer: b included)
- *   random!(a...b)             [a, b)  half-open
- *   random!(..., rng: r)       any of the above with a custom Random source
- *
- * For float, `..` and `...` return the same distribution (endpoint
- * probability ~2^-53); the closed form is honored syntactically but not
- * enforced at the mantissa level, matching NumPy/SciPy convention.
- * Boolean fills 0/1 with 50% probability each and ignores the range
- * argument.  Rejects CA_OBJECT / CA_FIXLEN. */
 static VALUE
-rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
+ca_random_bang_fill (VALUE arg)
 {
-  CArray *ca;
-  VALUE arg1 = Qnil, arg2 = Qnil, opts = Qnil;
-  VALUE low_val = Qnil, high_val = Qnil;
-  int is_default = 1;
-  int high_is_closed = 0;
-  double low_dbl = 0.0, high_dbl = 0.0;
-  long low_long = 0, high_long = 0;
-  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);
-
-  /* Parse positional args into (low_val, high_val) + high_is_closed. */
-  if (rb_obj_is_kind_of(arg1, rb_cRange)) {
-    if (!NIL_P(arg2)) {
-      rb_raise(rb_eArgError,
-               "random: cannot combine a Range with a second positional arg");
-    }
-    low_val  = rb_funcall(arg1, rb_intern("begin"), 0);
-    high_val = rb_funcall(arg1, rb_intern("end"), 0);
-    if (NIL_P(low_val) || NIL_P(high_val)) {
-      rb_raise(rb_eArgError,
-               "random: Range must have finite begin and end");
-    }
-    high_is_closed = ! RTEST(rb_funcall(arg1, rb_intern("exclude_end?"), 0));
-    is_default = 0;
-  } else if (!NIL_P(arg1) && !NIL_P(arg2)) {
-    low_val  = arg1;
-    high_val = arg2;
-    is_default = 0;
-  } else if (!NIL_P(arg1)) {
-    low_val  = INT2FIX(0);
-    high_val = arg1;
-    is_default = 0;
-  }
-
-  rb_ca_modify(self);
-  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
-
-  if (ca->data_type == CA_OBJECT || ca->data_type == CA_FIXLEN) {
-    rb_raise(rb_eCADataTypeError,
-             "random! is not supported for object/fixlen arrays");
-  }
-
-  /* Materialize (low, high) as the correct scalar type and validate.
-   * 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_type = (ca->data_type >= CA_INT8
-                            && ca->data_type <= CA_UINT64);
-    if (is_integer_type) {
-      low_long  = NUM2LONG(low_val);
-      high_long = NUM2LONG(high_val);
-      if (high_is_closed) high_long += 1;
-      if (low_long >= high_long) {
-        rb_raise(rb_eArgError,
-                 "random: low must be less than high "
-                 "(got low=%ld, high=%ld)",
-                 low_long, high_long);
-      }
-      limit = (unsigned long)(high_long - low_long) - 1;
-    } else {
-      low_dbl  = NUM2DBL(low_val);
-      high_dbl = NUM2DBL(high_val);
-      if (low_dbl >= high_dbl) {
-        rb_raise(rb_eArgError,
-                 "random: low must be less than high "
-                 "(got low=%g, high=%g)",
-                 low_dbl, high_dbl);
-      }
-    }
-  }
-
-  n = ca->elements;
-  ca_attach(ca);
-  ca_rng_open(rng, &source);
-
+  ca_random_ctx_t *c = (ca_random_ctx_t *) arg;
+  CArray *ca = c->ca;
+  ca_size_t i, n = c->n;
+  int is_default = c->is_default;
+  double low_dbl = c->low_dbl, high_dbl = c->high_dbl;
+  long low_long = c->low_long;
+  unsigned long limit = c->limit;
+
+  ca_rng_bind(&c->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(&source);
+        p[i] = ca_random_real(&c->source);
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = low_dbl + ca_random_real(&source) * range;
+        p[i] = low_dbl + ca_random_real(&c->source) * range;
     }
     break;
   }
@@ -247,11 +180,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(&source);
+        p[i] = (float)ca_random_real(&c->source);
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (float)(low_dbl + ca_random_real(&source) * range);
+        p[i] = (float)(low_dbl + ca_random_real(&c->source) * range);
     }
     break;
   }
@@ -259,12 +192,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(&source) + ca_random_real(&source) * I;
+        p[i] = ca_random_real(&c->source) + ca_random_real(&c->source) * I;
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (low_dbl + ca_random_real(&source) * range)
-             + (low_dbl + ca_random_real(&source) * range) * I;
+        p[i] = (low_dbl + ca_random_real(&c->source) * range)
+             + (low_dbl + ca_random_real(&c->source) * range) * I;
     }
     break;
   }
@@ -272,27 +205,24 @@ 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(&source) + (float)ca_random_real(&source) * I;
+        p[i] = (float)ca_random_real(&c->source) + (float)ca_random_real(&c->source) * I;
     } else {
       double range = high_dbl - low_dbl;
       for (i = 0; i < n; i++)
-        p[i] = (float)(low_dbl + ca_random_real(&source) * range)
-             + (float)(low_dbl + ca_random_real(&source) * range) * I;
+        p[i] = (float)(low_dbl + ca_random_real(&c->source) * range)
+             + (float)(low_dbl + ca_random_real(&c->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(&source) < 0.5) ? 1 : 0;
+      p[i] = (ca_random_real(&c->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,
                "random! on an integer array requires a range: "
                "a.random!(high), a.random!(low, high), or "
@@ -302,55 +232,52 @@ 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(&source, limit));
+        p[i] = (int8_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (uint8_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (int16_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (uint16_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (int32_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (uint32_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (int64_t)(low_long + ca_random_ulong_limited(&c->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(&source, limit));
+        p[i] = (uint64_t)(low_long + ca_random_ulong_limited(&c->source, limit));
       break;
     }
     default:
-      ca_rng_close(&source);
-      ca_sync(ca);
-      ca_detach(ca);
       rb_raise(rb_eCADataTypeError,
                "random! is not supported for this data type");
     }
@@ -358,9 +285,153 @@ rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
   }
   }
 
-  ca_rng_close(&source);
-  ca_sync(ca);
-  ca_detach(ca);
+  return Qnil;
+}
+
+/* CArray#random!([low,] [high], rng:) — fill self with uniform random
+ * numbers in-place, returning self.  Range surface mirrors Numo/NumPy
+ * (half-open [low, high) as the default) plus Ruby idiom (`..` closed,
+ * `...` half-open):
+ *
+ *   random!                    float [0.0, 1.0); integer -> ArgumentError
+ *   random!(high)              [0, high)                (Ruby rand shorthand)
+ *   random!(low, high)         [low, high)              (Numo positional)
+ *   random!(a..b)              [a, b]  closed           (integer: b included)
+ *   random!(a...b)             [a, b)  half-open
+ *   random!(..., rng: r)       any of the above with a custom Random source
+ *
+ * For float, `..` and `...` return the same distribution (endpoint
+ * probability ~2^-53); the closed form is honored syntactically but not
+ * enforced at the mantissa level, matching NumPy/SciPy convention.
+ * Boolean fills 0/1 with 50% probability each and ignores the range
+ * argument.  Rejects CA_OBJECT / CA_FIXLEN. */
+static VALUE
+rb_ca_random_bang(int argc, VALUE *argv, VALUE self)
+{
+  CArray *ca;
+  VALUE arg1 = Qnil, arg2 = Qnil, opts = Qnil;
+  VALUE low_val = Qnil, high_val = Qnil;
+  int is_default = 1;
+  int high_is_closed = 0;
+  double low_dbl = 0.0, high_dbl = 0.0;
+  long low_long = 0, high_long = 0;
+  unsigned long limit = 0;
+  VALUE rng = Qnil;
+
+  rb_scan_args(argc, argv, "02:", &arg1, &arg2, &opts);
+  rb_scan_options(opts, "rng", &rng);
+
+  /* Parse positional args into (low_val, high_val) + high_is_closed. */
+  if (rb_obj_is_kind_of(arg1, rb_cRange)) {
+    if (!NIL_P(arg2)) {
+      rb_raise(rb_eArgError,
+               "random: cannot combine a Range with a second positional arg");
+    }
+    low_val  = rb_funcall(arg1, rb_intern("begin"), 0);
+    high_val = rb_funcall(arg1, rb_intern("end"), 0);
+    if (NIL_P(low_val) || NIL_P(high_val)) {
+      rb_raise(rb_eArgError,
+               "random: Range must have finite begin and end");
+    }
+    high_is_closed = ! RTEST(rb_funcall(arg1, rb_intern("exclude_end?"), 0));
+    is_default = 0;
+  } else if (!NIL_P(arg1) && !NIL_P(arg2)) {
+    low_val  = arg1;
+    high_val = arg2;
+    is_default = 0;
+  } else if (!NIL_P(arg1)) {
+    low_val  = INT2FIX(0);
+    high_val = arg1;
+    is_default = 0;
+  }
+
+  rb_ca_modify(self);
+  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
+
+  if (ca->data_type == CA_OBJECT || ca->data_type == CA_FIXLEN) {
+    rb_raise(rb_eCADataTypeError,
+             "random! is not supported for object/fixlen arrays");
+  }
+
+  /* Materialize (low, high) as the correct scalar type and validate.
+   * 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_type = (ca->data_type >= CA_INT8
+                            && ca->data_type <= CA_UINT64);
+    if (is_integer_type) {
+      /* The bounds stay Ruby Integers until they are known to fit: the
+         last value drawn is high (closed) or high - 1, and every value
+         from low to it must be one of the type's.  The draw is low plus
+         an offset up to last - low, which holds even the whole int64 or
+         uint64 range. */
+      VALUE last, type_min, type_max;
+      if (!RB_INTEGER_TYPE_P(low_val) || !RB_INTEGER_TYPE_P(high_val)) {
+        rb_raise(rb_eTypeError,
+                 "random: an integer array takes Integer bounds "
+                 "(got %"PRIsVALUE", %"PRIsVALUE")",
+                 rb_inspect(low_val), rb_inspect(high_val));
+      }
+      last = high_is_closed ? high_val
+                            : rb_funcall(high_val, '-', 1, INT2FIX(1));
+      if (RTEST(rb_funcall(low_val, '>', 1, last))) {
+        rb_raise(rb_eArgError,
+                 "random: low must be less than high "
+                 "(got low=%"PRIsVALUE", high=%"PRIsVALUE")",
+                 low_val, high_val);
+      }
+      switch (ca->data_type) {
+      case CA_INT8:   type_min = INT2FIX(INT8_MIN);   type_max = INT2FIX(INT8_MAX);   break;
+      case CA_UINT8:  type_min = INT2FIX(0);          type_max = INT2FIX(UINT8_MAX);  break;
+      case CA_INT16:  type_min = INT2FIX(INT16_MIN);  type_max = INT2FIX(INT16_MAX);  break;
+      case CA_UINT16: type_min = INT2FIX(0);          type_max = INT2FIX(UINT16_MAX); break;
+      case CA_INT32:  type_min = LL2NUM(INT32_MIN);   type_max = LL2NUM(INT32_MAX);   break;
+      case CA_UINT32: type_min = INT2FIX(0);          type_max = ULL2NUM(UINT32_MAX); break;
+      case CA_INT64:  type_min = LL2NUM(INT64_MIN);   type_max = LL2NUM(INT64_MAX);   break;
+      default:        type_min = INT2FIX(0);          type_max = ULL2NUM(UINT64_MAX); break;
+      }
+      if (RTEST(rb_funcall(low_val, '<', 1, type_min)) ||
+          RTEST(rb_funcall(last, '>', 1, type_max))) {
+        rb_raise(rb_eRangeError,
+                 "random: the values %"PRIsVALUE"..%"PRIsVALUE" are not all %s "
+                 "(%"PRIsVALUE"..%"PRIsVALUE")",
+                 low_val, last, ca_type_name[ca->data_type], type_min, type_max);
+      }
+      low_long = RTEST(rb_funcall(low_val, '<', 1, INT2FIX(0)))
+               ? (long) NUM2LL(low_val) : (long) NUM2ULL(low_val);
+      limit = (unsigned long) NUM2ULL(rb_funcall(last, '-', 1, low_val));
+      (void) high_long;
+    } else {
+      low_dbl  = NUM2DBL(low_val);
+      high_dbl = NUM2DBL(high_val);
+      if (!isfinite(low_dbl) || !isfinite(high_dbl)) {
+        rb_raise(rb_eArgError,
+                 "random: the bounds are finite numbers "
+                 "(got low=%g, high=%g)", low_dbl, high_dbl);
+      }
+      if (low_dbl >= high_dbl) {
+        rb_raise(rb_eArgError,
+                 "random: low must be less than high "
+                 "(got low=%g, high=%g)",
+                 low_dbl, high_dbl);
+      }
+    }
+  }
+
+  {
+    ca_random_ctx_t c = { 0 };
+    c.ca         = ca;
+    c.n          = ca->elements;
+    c.is_default = is_default;
+    c.low_dbl    = low_dbl;
+    c.high_dbl   = high_dbl;
+    c.low_long   = low_long;
+    c.limit      = limit;
+    ca_random_run(&c, rng, ca_random_bang_fill);
+  }
+  /* Every cell now holds a value, as after seq! or fill. */
+  ca_clear_mask(ca);
   return self;
 }
 
@@ -396,53 +467,31 @@ box_muller_pair(ca_rng_t *source, double *r1, double *r2)
   *r2 = r * sin(theta);
 }
 
-/* CArray#randomn!(rng:) — fill self with standard normal N(0, 1)
- * samples in-place via Box-Muller, returning self.
- *
- * 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)
+ca_randomn_bang_fill (VALUE arg)
 {
-  CArray *ca;
-  VALUE opts = Qnil;
-  ca_size_t i, n;
-
-  rb_scan_args(argc, argv, "0:", &opts);
-  VALUE rng = Qnil;
-  ca_rng_t source;
-  rb_scan_options(opts, "rng", &rng);
-
-  rb_ca_modify(self);
-  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
-
-  if (ca->data_type != CA_FLOAT64 && ca->data_type != CA_FLOAT32 &&
-      ca->data_type != CA_CMPLX128 && ca->data_type != CA_CMPLX64) {
-    rb_raise(rb_eCADataTypeError,
-             "randomn! requires float or complex array");
-  }
-
-  n = ca->elements;
-  ca_attach(ca);
-  ca_rng_open(rng, &source);
+  ca_random_ctx_t *c = (ca_random_ctx_t *) arg;
+  CArray *ca = c->ca;
+  ca_size_t i, n = c->n;
 
+  ca_rng_bind(&c->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) {
+  if (c->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);
+        p[i] = ca_random_normal(&c->source);
       break;
     }
     case CA_FLOAT32: {
       float *p = (float *)ca->ptr;
       for (i = 0; i < n; i++)
-        p[i] = (float) ca_random_normal(&source);
+        p[i] = (float) ca_random_normal(&c->source);
       break;
     }
     case CA_CMPLX128: {
@@ -450,8 +499,8 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
       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);
+        double re = ca_random_normal(&c->source);
+        double im = ca_random_normal(&c->source);
         p[i] = re + im * I;
       }
       break;
@@ -459,8 +508,8 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     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);
+        double re = ca_random_normal(&c->source);
+        double im = ca_random_normal(&c->source);
         p[i] = (float) re + (float) im * I;
       }
       break;
@@ -468,10 +517,7 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     default:
       break;
     }
-    ca_rng_close(&source);
-    ca_sync(ca);
-    ca_detach(ca);
-    return self;
+    return Qnil;
   }
 
   switch (ca->data_type) {
@@ -479,11 +525,11 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     double *p = (double *)ca->ptr;
     ca_size_t pairs = n / 2;
     for (i = 0; i < pairs; i++) {
-      box_muller_pair(&source, &p[2*i], &p[2*i+1]);
+      box_muller_pair(&c->source, &p[2*i], &p[2*i+1]);
     }
     if (n % 2 == 1) {
       double r1, r2;
-      box_muller_pair(&source, &r1, &r2);
+      box_muller_pair(&c->source, &r1, &r2);
       p[n-1] = r1;
     }
     break;
@@ -493,13 +539,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(&source, &r1, &r2);
+      box_muller_pair(&c->source, &r1, &r2);
       p[2*i]   = (float)r1;
       p[2*i+1] = (float)r2;
     }
     if (n % 2 == 1) {
       double r1, r2;
-      box_muller_pair(&source, &r1, &r2);
+      box_muller_pair(&c->source, &r1, &r2);
       p[n-1] = (float)r1;
     }
     break;
@@ -508,7 +554,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(&source, &r1, &r2);
+      box_muller_pair(&c->source, &r1, &r2);
       p[i] = r1 + r2 * I;
     }
     break;
@@ -517,7 +563,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(&source, &r1, &r2);
+      box_muller_pair(&c->source, &r1, &r2);
       p[i] = (float)r1 + (float)r2 * I;
     }
     break;
@@ -526,9 +572,41 @@ rb_ca_randomn_bang(int argc, VALUE *argv, VALUE self)
     break;
   }
 
-  ca_rng_close(&source);
-  ca_sync(ca);
-  ca_detach(ca);
+  return Qnil;
+}
+
+/* CArray#randomn!(rng:) — fill self with standard normal N(0, 1)
+ * samples in-place via Box-Muller, returning self.
+ *
+ * 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)
+{
+  CArray *ca;
+  VALUE opts = Qnil;
+
+  rb_scan_args(argc, argv, "0:", &opts);
+  VALUE rng = Qnil;
+  rb_scan_options(opts, "rng", &rng);
+
+  rb_ca_modify(self);
+  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
+
+  if (ca->data_type != CA_FLOAT64 && ca->data_type != CA_FLOAT32 &&
+      ca->data_type != CA_CMPLX128 && ca->data_type != CA_CMPLX64) {
+    rb_raise(rb_eCADataTypeError,
+             "randomn! requires float or complex array");
+  }
+
+  {
+    ca_random_ctx_t c = { 0 };
+    c.ca = ca;
+    c.n  = ca->elements;
+    ca_random_run(&c, rng, ca_randomn_bang_fill);
+  }
+  /* Every cell now holds a value, as after seq! or fill. */
+  ca_clear_mask(ca);
   return self;
 }
 
@@ -550,59 +628,39 @@ swap_chunks(char *a, char *b, ca_size_t chunk_bytes, char *tmp)
  * as a byte chunk and swapped whole, so multi-dim slices move
  * together). */
 static VALUE
-rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
+ca_shuffle_bang_fill (VALUE arg)
 {
-  CArray *ca;
-  VALUE opts = Qnil, v_axis = Qnil;
+  ca_random_ctx_t *c = (ca_random_ctx_t *) arg;
+  CArray *ca = c->ca;
   ca_size_t n;
-  int axis = -1;
 
-  rb_scan_args(argc, argv, "0:", &opts);
-  VALUE rng = Qnil;
-  ca_rng_t source;
-  rb_scan_options(opts, "rng,axis", &rng, &v_axis);
+  ca_rng_bind(&c->source);
 
-  rb_ca_modify(self);
-  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
-
-  if (ca->elements <= 1) return self;
-
-  ca_attach(ca);
-  ca_rng_open(rng, &source);
-
-  if (NIL_P(v_axis)) {
+  if (c->axis < 0) {
     /* shuffle all elements */
-    n = ca->elements;
+    volatile VALUE tmp_holder;
     ca_size_t elem_bytes = ca->bytes;
-    char *tmp = (char *)xmalloc(elem_bytes);
+    char *tmp = ALLOCV_N(char, tmp_holder, elem_bytes);
     char *p = ca->ptr;
+    char *m = c->mask ? c->mask->ptr : NULL;
 
+    n = ca->elements;
     for (ca_size_t i = n - 1; i > 0; i--) {
-      unsigned long j = ca_random_ulong_limited(&source, (unsigned long)i);
+      unsigned long j = ca_random_ulong_limited(&c->source, (unsigned long)i);
       if ((ca_size_t)j != i) {
         swap_chunks(p + i * elem_bytes, p + j * elem_bytes, elem_bytes, tmp);
+        if ( m ) {
+          char b = m[i]; m[i] = m[j]; m[j] = b;
+        }
       }
     }
-    xfree(tmp);
+    ALLOCV_END(tmp_holder);
   }
   else {
-    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,
-               "axis %d is out of range for ndim %d", axis, ca->ndim);
-    }
+    int axis = c->axis;
+    volatile VALUE tmp_holder;
 
     n = ca->dim[axis];
-    if (n <= 1) {
-      ca_rng_close(&source);
-      ca_sync(ca);
-      ca_detach(ca);
-      return self;
-    }
 
     ca_size_t outer = 1;
     for (int d = 0; d < axis; d++)
@@ -614,25 +672,59 @@ rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
 
     ca_size_t chunk_bytes = inner * ca->bytes;
     ca_size_t stride = n * chunk_bytes;
-    char *tmp = (char *)xmalloc(chunk_bytes);
+    char *tmp = ALLOCV_N(char, tmp_holder, chunk_bytes);
 
     for (ca_size_t o = 0; o < outer; o++) {
       char *base = ca->ptr + o * stride;
+      char *mbase = c->mask ? c->mask->ptr + o * n * inner : NULL;
       for (ca_size_t i = n - 1; i > 0; i--) {
-        unsigned long j = ca_random_ulong_limited(&source, (unsigned long)i);
+        unsigned long j = ca_random_ulong_limited(&c->source, (unsigned long)i);
         if ((ca_size_t)j != i) {
           swap_chunks(base + i * chunk_bytes,
                       base + j * chunk_bytes,
                       chunk_bytes, tmp);
+          if ( mbase ) {
+            swap_chunks(mbase + i * inner, mbase + j * inner, inner, tmp);
+          }
         }
       }
     }
-    xfree(tmp);
+    ALLOCV_END(tmp_holder);
+  }
+  return Qnil;
+}
+
+static VALUE
+rb_ca_shuffle_bang(int argc, VALUE *argv, VALUE self)
+{
+  CArray *ca;
+  VALUE opts = Qnil, v_axis = Qnil;
+  int axis = -1;
+  ca_random_ctx_t c = { 0 };
+
+  rb_scan_args(argc, argv, "0:", &opts);
+  VALUE rng = Qnil;
+  rb_scan_options(opts, "rng,axis", &rng, &v_axis);
+
+  rb_ca_modify(self);
+  TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
+
+  if (ca->elements <= 1) return self;
+
+  if (!NIL_P(v_axis)) {
+    axis = ca_normalize_axis_arg(v_axis, ca->ndim, NULL);
+    if (ca->dim[axis] <= 1) {
+      return self;
+    }
   }
 
-  ca_rng_close(&source);
-  ca_sync(ca);
-  ca_detach(ca);
+  c.ca   = ca;
+  c.axis = axis;
+  /* The mask moves with the values: a masked cell stays masked wherever
+     it lands. */
+  ca_update_mask(ca);
+  c.mask = ca->mask;
+  ca_random_run(&c, rng, ca_shuffle_bang_fill);
   return self;
 }
 
@@ -698,7 +790,7 @@ 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);
+  ca_attach(ca);   /* window: the state is an entity, whose attach holds nothing */
   *cells = (int64_t *) ca->ptr;
   return ca;
 }
@@ -752,8 +844,7 @@ rb_ca_rng_reset (int argc, VALUE *argv, VALUE self)
 
   ca = ca_rng_cells(self, &cells);
   ca_xoshiro256pp_seed(cells, (uint64_t) NUM2ULL(masked));
-  ca_sync(ca);
-  ca_detach(ca);
+  ca_sync_detach(ca);
 
   rb_ivar_set(self, rb_intern("@seed"), seed);
   return self;
@@ -779,8 +870,7 @@ rb_ca_rng_random (VALUE self)
 
   ca = ca_rng_cells(self, &cells);
   value = ca_xoshiro256pp_next_real(cells);
-  ca_sync(ca);
-  ca_detach(ca);
+  ca_sync_detach(ca);
   return rb_float_new(value);
 }
 
@@ -799,8 +889,7 @@ rb_ca_rng_bits (VALUE self)
 
   ca = ca_rng_cells(self, &cells);
   value = ca_xoshiro256pp_next(cells);
-  ca_sync(ca);
-  ca_detach(ca);
+  ca_sync_detach(ca);
   return ULL2NUM(value);
 }
 
@@ -823,8 +912,7 @@ rb_ca_rng_randomn (VALUE self)
   source.state = NULL;
   source.cells = cells;
   value = ca_random_normal(&source);
-  ca_sync(ca);
-  ca_detach(ca);
+  ca_sync_detach(ca);
   return rb_float_new(value);
 }