carray 2.0.1 → 3.0.1

data/ext/ca_for_buffer.h

@@ -0,0 +1,96 @@
+/* ---------------------------------------------------------------------------
+ *
+ *  ca_for_buffer.h -- sweep WHOLE_BUFFER macro family (whole contig buffer
+ *                    handed to author / third-party library)
+ *
+ *  PROPOSAL_L0_AUTHOR_SURFACE L0.2c (2026-06-11).  C-side counterpart of
+ *  Ruby's `ca.attach! { |a| ... }` block: scope the ca_attach + ca_sync +
+ *  ca_detach lifecycle to a block, hand the author a contig buffer ptr
+ *  and element count, let the author do whatever (typically pass the
+ *  ptr to a third-party library: FFTW, akima init, fitpack surf1, ...).
+ *
+ *  Two forms (Q8 = M1 alias-when-possible; non-contig source materialises
+ *  into a transient buffer; writable form syncs back on exit):
+ *
+ *    CA_WITH_BUFFER(ca, T, ptr, n)
+ *      Read-only access.  ptr : T const * pointing at native contig
+ *      layout of `ca` (= ca->ptr alias when contig entity, scratch
+ *      otherwise).  n : ca->elements.  No write-back on exit.
+ *
+ *    CA_WITH_BUFFER_WRITABLE(ca, T, ptr, n)
+ *      Writable; same ptr/n semantics, plus ca_sync on block exit so
+ *      author writes propagate back to the view's storage.
+ *
+ *  Author pattern:
+ *
+ *    double *ptr;
+ *    ca_size_t n;
+ *    CA_WITH_BUFFER_WRITABLE(ca, double, ptr, n) {
+ *      fftw_execute_dft(plan, ptr, ptr);
+ *    }
+ *
+ *  Constraints (same as CA_FOR_EACH_FIBER family):
+ *    - `break;` from body exits cleanly (= outer for's advance clause
+ *      runs ca_sync / ca_detach).
+ *    - `return;` from body LEAKS the attach; restructure to break.
+ *    - Macros are NOT statement-equivalent (= nested for); no trailing
+ *      `else`.
+ *    - For Ruby-exception-safe lifecycle (e.g. when calling Ruby code or
+ *      anything that may raise from inside the body), use the function
+ *      form `rb_ca_call_with_buffer` instead (= rb_ensure-protected).
+ *
+ *  --------------------------------------------------------------------------- */
+
+#ifndef CA_FOR_BUFFER_H
+#define CA_FOR_BUFFER_H
+
+#include "carray.h"
+#include "ca_sweep_engine.h"
+
+/* ---------- macro forms ---------- */
+
+/* Read-only: ca_attach (alias-when-possible) + author body + ca_detach. */
+#define CA_WITH_BUFFER(_ca, T, _ptr, _n)                                  \
+  for ( CArray *__cwv_ca = (CArray *)(_ca);                             \
+        __cwv_ca;                                                       \
+        ca_detach(__cwv_ca), __cwv_ca = NULL )                          \
+    for ( int __cwv_once = (ca_attach(__cwv_ca),                        \
+                            (_ptr) = (T *)__cwv_ca->ptr,                \
+                            (_n)   = __cwv_ca->elements,                \
+                            1);                                         \
+          __cwv_once;                                                   \
+          __cwv_once = 0 )
+
+/* Writable: same as above + ca_sync on block exit. */
+#define CA_WITH_BUFFER_WRITABLE(_ca, T, _ptr, _n)                         \
+  for ( CArray *__cwvw_ca = (CArray *)(_ca);                            \
+        __cwvw_ca;                                                      \
+        ca_sync(__cwvw_ca), ca_detach(__cwvw_ca), __cwvw_ca = NULL )    \
+    for ( int __cwvw_once = (ca_attach(__cwvw_ca),                      \
+                             (_ptr) = (T *)__cwvw_ca->ptr,              \
+                             (_n)   = __cwvw_ca->elements,              \
+                             1);                                        \
+          __cwvw_once;                                                  \
+          __cwvw_once = 0 )
+
+/* ---------- function form (rb_ensure-protected, AC8) ----------
+ *
+ * Use this when the body may raise a Ruby exception (= calling rb_funcall,
+ * type-checking with rb_check_type, indirect Ruby code, etc.).  The
+ * engine ca_attach's the view, runs body via rb_ensure, then guarantees
+ * ca_sync (if writable) and ca_detach run before the exception
+ * propagates.
+ *
+ *   body_fn(user_data, ptr, n_elements) -> may raise
+ *
+ * Returns whatever body_fn returns via its own propagation (= the
+ * function itself returns Qnil since rb_ensure body must be VALUE).
+ * For richer return semantics, box your result in user_data.
+ */
+typedef void (*ca_with_buffer_body_fn) (void *user_data, void *ptr,
+                                      ca_size_t n_elements);
+
+void rb_ca_call_with_buffer (VALUE r_ca, int writable,
+                        ca_with_buffer_body_fn body, void *user_data);
+
+#endif /* CA_FOR_BUFFER_H */

data/ext/ca_for_each_element.h

@@ -0,0 +1,239 @@
+/* ---------------------------------------------------------------------------
+ *
+ *  ca_for_each_element.h -- sweep ELEMENT macro family (single-array, lexical
+ *                            scope body) for ext authors.
+ *
+ *  PROPOSAL_L0_AUTHOR_SURFACE L0.2a (2026-06-11).  Builds on the sweep engine
+ *  helper (ca_sweep_engine.{c,h}, L0.1) for the xfer_all-aware acquire/release
+ *  lifecycle.  Provides 5 macro forms for single-array element-wise loops
+ *  with author-inline body and lexical-scope state capture.
+ *
+ *  Forms (Q2 = gamma: READ by-value, INOUT / OUT by-lvalue):
+ *
+ *    CA_FOR_EACH_ELEMENT(st1, ca, T, x)
+ *      Read-only loop; per-iter x = cell value (T rvalue convention but
+ *      declared lvalue for assignment).  Mask policy: NO_MASK (raises if
+ *      INPUT has mask; use _MASKED form to handle).
+ *
+ *    CA_FOR_EACH_ELEMENT_MASKED(st1, ca, T, x, m)
+ *      Read-only with mask byte m (1 = masked).  Author inspects m and
+ *      decides; m == 0 if source has no mask.
+ *
+ *    CA_FOR_EACH_ELEMENT_INOUT(st2, ca_in, ca_out, T_IN, T_OUT, in, out)
+ *      Map kernel; per-iter in = read input, body assigns to out (lvalue),
+ *      out is written back to ca_out.  Strict same-shape check on init
+ *      (raises on mismatch).  NO_MASK on input.
+ *
+ *    CA_FOR_EACH_ELEMENT_INOUT_MASKED(st2, ca_in, ca_out, T_IN, T_OUT,
+ *                                      in, out, m_in, m_out)
+ *      Map kernel with mask; per-iter m_in = input mask byte (or 0 if no
+ *      input mask), author writes m_out (1 = mark output cell masked) and
+ *      out.  m_out written back to ca_out's mask.
+ *
+ *    CA_FOR_EACH_ELEMENT_OUT(st1, ca_out, T, out)
+ *      Write-only; body assigns to out (lvalue).  Use for init / iota /
+ *      fill patterns.  NO_MASK (output mask cleared).
+ *
+ *  Usage pattern:
+ *
+ *      ca_each_state_t st;
+ *      double x;
+ *      CA_FOR_EACH_ELEMENT(st, ca, double, x) {
+ *        accumulator += x;
+ *      }
+ *
+ *  Constraints (same as CA_FOR_EACH_FIBER family):
+ *    - State (st1 / st2) is author-declared on the stack.
+ *    - `break;` from body exits cleanly (release runs in outer for's
+ *      teardown clause).
+ *    - `return;` from body LEAKS scratch buffers / attached views — do
+ *      not return early from the macro body; restructure to break.
+ *    - Macros are NOT statement-equivalent (expand to nested for); no
+ *      trailing `else`.
+ *    - `T` must be the data_type of `ca` (matched via ca->data_type and
+ *      ca->bytes — engine does not auto-cast; use rb_ca_wrap_readonly /
+ *      rb_ca_template_with_type at the call site if cast needed).
+ *
+ *  --------------------------------------------------------------------------- */
+
+#ifndef CA_FOR_EACH_ELEMENT_H
+#define CA_FOR_EACH_ELEMENT_H
+
+#include "carray.h"
+#include "ca_sweep_engine.h"
+
+/* Stack-allocated state holders for 1- and 2-operand sweep ELEMENT macros.
+ * Embeds the per-op bookkeeping arrays + the core ca_sweep_state_t in one
+ * struct so authors declare just one variable. */
+
+typedef struct {
+  CArray       *cx[1];
+  char         *base[1];
+  ca_size_t     stride[1];
+  char         *owned_buf[1];
+  int           attached[1];
+  char         *base_orig[1];
+  ca_sweep_state_t core;
+} ca_each_state_t;
+
+typedef struct {
+  CArray       *cx[2];
+  char         *base[2];
+  ca_size_t     stride[2];
+  char         *owned_buf[2];
+  int           attached[2];
+  char         *base_orig[2];
+  ca_sweep_state_t core;
+} ca_each_map_state_t;
+
+/* Internal init helpers: wire the embedded arrays into core, set fsync /
+ * no_mask / src_label.  Called via comma-expression inside the macro
+ * for-loop init clause. */
+
+#define CA_SWEEP_WIRE_1_(_st1, _ca0, _fsync, _no_mask, _label) (   \
+    (_st1).cx[0]           = (CArray *)(_ca0),                  \
+    (_st1).core.n_ops      = 1,                                 \
+    (_st1).core.fsync      = (_fsync),                          \
+    (_st1).core.cx         = (_st1).cx,                         \
+    (_st1).core.base       = (_st1).base,                       \
+    (_st1).core.stride     = (_st1).stride,                     \
+    (_st1).core.owned_buf  = (_st1).owned_buf,                  \
+    (_st1).core.attached   = (_st1).attached,                   \
+    (_st1).core.base_orig  = (_st1).base_orig,                  \
+    (_st1).core.no_mask    = (_no_mask),                        \
+    (_st1).core.src_label  = (_label))
+
+#define CA_SWEEP_WIRE_2_(_st2, _ca0, _ca1, _fsync, _no_mask, _label) ( \
+    (_st2).cx[0]           = (CArray *)(_ca0),                  \
+    (_st2).cx[1]           = (CArray *)(_ca1),                  \
+    (_st2).core.n_ops      = 2,                                 \
+    (_st2).core.fsync      = (_fsync),                          \
+    (_st2).core.cx         = (_st2).cx,                         \
+    (_st2).core.base       = (_st2).base,                       \
+    (_st2).core.stride     = (_st2).stride,                     \
+    (_st2).core.owned_buf  = (_st2).owned_buf,                  \
+    (_st2).core.attached   = (_st2).attached,                   \
+    (_st2).core.base_orig  = (_st2).base_orig,                  \
+    (_st2).core.no_mask    = (_no_mask),                        \
+    (_st2).core.src_label  = (_label))
+
+/* ---------- 5 author-facing macro forms ----------
+ *
+ * All 5 forms expand to a 3-level nested for:
+ *   outer  : acquire_chunked / release_chunked (= lifecycle scope)
+ *   middle : ca_sweep_next_chunk loop (= chunk iteration)
+ *   inner  : per-cell loop within chunk_n
+ *
+ * Memory peak per AC2: INPUT non-alias views materialise into a single
+ * chunk scratch (~32KB at f64).  m0 (= masked form) is chunk-sized too and
+ * re-gathered per chunk, so the macro reads at m0[k] -- indexed within the
+ * chunk, not by the flat cell index.
+ *
+ * For MASKED forms (m / m_in / m_out): when source has no mask, m0 is
+ * NULL and m / m_in == 0 always.  m_out writes during INOUT_MASKED are
+ * silently dropped if no INPUT mask exists (= AC4 mask-creation on
+ * INOUT MASKED with no source mask is a future enhancement; current
+ * convention follows the FIBER family's MASKED form).
+ */
+
+/* (1) READ-only, NO_MASK */
+#define CA_FOR_EACH_ELEMENT(_st1, _ca, T, x)                            \
+  for ( int __cfe_init = (CA_SWEEP_WIRE_1_((_st1), (_ca), "0", 1,          \
+                                        "CA_FOR_EACH_ELEMENT"),         \
+                          ca_sweep_acquire_chunked(&(_st1).core), 1);      \
+        __cfe_init;                                                     \
+        __cfe_init = 0, ca_sweep_release_chunked(&(_st1).core) )           \
+    for ( ; ca_sweep_next_chunk(&(_st1).core); )                           \
+      for ( ca_size_t __cfe_k = 0;                                      \
+            __cfe_k < (_st1).core.chunk_n                               \
+              && (((x) = *(T *)((_st1).core.base[0]                     \
+                                + __cfe_k * (_st1).core.stride[0])), 1); \
+            __cfe_k++ )
+
+/* (2) READ-only, MASKED (m is 1 if masked, 0 otherwise; 0 if no source mask) */
+#define CA_FOR_EACH_ELEMENT_MASKED(_st1, _ca, T, x, m)                  \
+  for ( int __cfem_init = (CA_SWEEP_WIRE_1_((_st1), (_ca), "0", 0,         \
+                                         "CA_FOR_EACH_ELEMENT_MASKED"), \
+                           ca_sweep_acquire_chunked(&(_st1).core), 1);     \
+        __cfem_init;                                                    \
+        __cfem_init = 0, ca_sweep_release_chunked(&(_st1).core) )          \
+    for ( ; ca_sweep_next_chunk(&(_st1).core); )                           \
+      for ( ca_size_t __cfem_k = 0;                                     \
+            __cfem_k < (_st1).core.chunk_n                              \
+              && (((x) = *(T *)((_st1).core.base[0]                     \
+                                + __cfem_k * (_st1).core.stride[0])),   \
+                  ((m) = (_st1).core.m0                                 \
+                            ? (_st1).core.m0[__cfem_k]                  \
+                            : (boolean8_t)0),                           \
+                  1);                                                   \
+            __cfem_k++ )
+
+/* (3) INOUT map (NO_MASK).  Strict same-shape check pre-acquire.        */
+#define CA_FOR_EACH_ELEMENT_INOUT(_st2, _ca_in, _ca_out,                \
+                                  T_IN, T_OUT, in, out)                 \
+  for ( int __cfei_init = (                                             \
+            ca_sweep_check_same_shape((CArray *)(_ca_in),                  \
+                                   (CArray *)(_ca_out),                 \
+                                   "CA_FOR_EACH_ELEMENT_INOUT"),        \
+            CA_SWEEP_WIRE_2_((_st2), (_ca_in), (_ca_out), "01", 1,         \
+                          "CA_FOR_EACH_ELEMENT_INOUT"),                 \
+            ca_sweep_acquire_chunked(&(_st2).core),                        \
+            1);                                                         \
+        __cfei_init;                                                    \
+        __cfei_init = 0, ca_sweep_release_chunked(&(_st2).core) )          \
+    for ( ; ca_sweep_next_chunk(&(_st2).core); )                           \
+      for ( ca_size_t __cfei_k = 0;                                     \
+            __cfei_k < (_st2).core.chunk_n                              \
+              && (((in) = *(T_IN *)((_st2).core.base[0]                 \
+                                    + __cfei_k * (_st2).core.stride[0])), \
+                  1);                                                   \
+            (*(T_OUT *)((_st2).core.base[1]                             \
+                        + __cfei_k * (_st2).core.stride[1]) = (out)),   \
+            __cfei_k++ )
+
+/* (4) INOUT map (MASKED).  Author writes m_out per cell. */
+#define CA_FOR_EACH_ELEMENT_INOUT_MASKED(_st2, _ca_in, _ca_out,         \
+                                         T_IN, T_OUT,                   \
+                                         in, out, m_in, m_out)          \
+  for ( int __cfeim_init = (                                            \
+            ca_sweep_check_same_shape((CArray *)(_ca_in),                  \
+                                   (CArray *)(_ca_out),                 \
+                                   "CA_FOR_EACH_ELEMENT_INOUT_MASKED"), \
+            CA_SWEEP_WIRE_2_((_st2), (_ca_in), (_ca_out), "01", 0,         \
+                          "CA_FOR_EACH_ELEMENT_INOUT_MASKED"),          \
+            ca_sweep_acquire_chunked(&(_st2).core),                        \
+            1);                                                         \
+        __cfeim_init;                                                   \
+        __cfeim_init = 0, ca_sweep_release_chunked(&(_st2).core) )         \
+    for ( ; ca_sweep_next_chunk(&(_st2).core); )                           \
+      for ( ca_size_t __cfeim_k = 0;                                    \
+            __cfeim_k < (_st2).core.chunk_n                             \
+              && (((in) = *(T_IN *)((_st2).core.base[0]                 \
+                                    + __cfeim_k * (_st2).core.stride[0])), \
+                  ((m_in) = (_st2).core.m0                              \
+                              ? (_st2).core.m0[__cfeim_k]               \
+                              : (boolean8_t)0),                         \
+                  ((m_out) = (m_in)),                                   \
+                  1);                                                   \
+            (*(T_OUT *)((_st2).core.base[1]                             \
+                        + __cfeim_k * (_st2).core.stride[1]) = (out)),  \
+            (((_st2).core.m0)                                           \
+                ? ((_st2).core.m0[__cfeim_k] = (m_out))                 \
+                : (boolean8_t)0),                                       \
+            __cfeim_k++ )
+
+/* (5) WRITE-only (init / iota / fill). */
+#define CA_FOR_EACH_ELEMENT_OUT(_st1, _ca_out, T, out)                  \
+  for ( int __cfeo_init = (CA_SWEEP_WIRE_1_((_st1), (_ca_out), "1", 0,     \
+                                         "CA_FOR_EACH_ELEMENT_OUT"),    \
+                           ca_sweep_acquire_chunked(&(_st1).core), 1);     \
+        __cfeo_init;                                                    \
+        __cfeo_init = 0, ca_sweep_release_chunked(&(_st1).core) )          \
+    for ( ; ca_sweep_next_chunk(&(_st1).core); )                           \
+      for ( ca_size_t __cfeo_k = 0;                                     \
+            __cfeo_k < (_st1).core.chunk_n;                             \
+            (*(T *)((_st1).core.base[0]                                 \
+                    + __cfeo_k * (_st1).core.stride[0]) = (out)),       \
+            __cfeo_k++ )
+
+#endif /* CA_FOR_EACH_ELEMENT_H */

data/ext/ca_group_iter.c

@@ -0,0 +1,304 @@
+/* ---------------------------------------------------------------------------
+
+  Axis-group reduction surface: the `[]` type gate and CAGroupIterator.
+
+  The apply path is C-level: the `[]` type gate that routes a CACategorical /
+  AxisGroup index to the group path (vs ordinary selection), the
+  CAGroupIterator construction and the :group reduce dispatch all live here.
+  The classifier is CACategorical (`categorical` (lib/carray/categorical.rb)):
+  a READONLY Face over narrow-uint codes; this surface consumes its codes / k
+  / labels.  The value-independent metadata (AxisGroup spec derivation,
+  GroupLabels) is Ruby (`axis_group` (lib/carray/axis_group.rb)) — it is not on
+  the `[]` hot path and is plain O(ndim) metadata.
+
+  Split summary:
+    - ca_argv_has_group / rb_ca_fetch_group  : here (called by carray_access.c)
+    - CAGroupIterator + the tier-1 reduction methods driving
+      __axis_group_reduce__ : here
+    - reduce_plan / bundle assembly / output-axis permutation (metadata) : Ruby
+    - the O(N) compute kernel __axis_group_reduce__ : ca_axis_group.c
+
+--------------------------------------------------------------------------- */
+
+#include "carray.h"
+
+/* lib/carray/axis_group.rb registers these classes here on first load (and
+   loading is wired so that load happens as soon as any categorical exists —
+   see autoload_base.rb).  Until then they stay Qnil and the [] type-gate scan
+   short-circuits, so a normal index pays nothing (no kind_of on the hot
+   path). */
+static VALUE rb_cCategorical     = Qnil;
+static VALUE rb_cAxisGroup       = Qnil;
+static VALUE rb_cCAGroupIterator = Qnil;
+
+static ID id_value, id_spec, id_axis_group, id_reduce_plan, id_parse_axis;
+static ID id_axis_group_reduce, id_reshape, id_transpose, id_labels;
+
+/* CArray.__register_axis_group_classes__(CACategorical, AxisGroup) — called
+   from the top of lib/carray/axis_group.rb so the C type gate can recognise
+   the classifier/spec types without triggering autoload on every [] call. */
+static VALUE
+rb_ca_register_axis_group_classes (VALUE klass, VALUE cat, VALUE ag)
+{
+  rb_cCategorical = cat;
+  rb_cAxisGroup   = ag;
+  rb_gc_register_address(&rb_cCategorical);
+  rb_gc_register_address(&rb_cAxisGroup);
+  return Qnil;
+}
+
+/* Cheap per-arg pre-filter + kind_of check.  Returns 1 if any arg is a
+   CACategorical (one-shot slot) or an AxisGroup (pre-built spec) — the group
+   apply path — and 0 otherwise.
+
+   The two group-arg forms have different Ruby representations, so each gets a
+   pre-filter that keeps ordinary indexing off the kind_of walk:
+
+     - AxisGroup is a plain Ruby object (T_OBJECT).  The scalar index kinds
+       (Integer / nil / Symbol / Range) are not T_OBJECT, so they cost only the
+       RB_TYPE_P bit test.
+
+     - CACategorical is a CArray (T_DATA) whose SURFACE data_type is CA_FIXLEN
+       (its narrow-uint codes are the storage parent).  A plain fancy-index is a
+       numeric CArray, so the cheap data_type read lets ordinary selection args
+       skip the kind_of — only a fixlen CArray index pays it.
+
+   Arming: the classes are registered by lib/carray/axis_group.rb.  We cannot
+   pre-arm on categorical construction (CACategorical is a CArray, so routing
+   its autoload through the axis-group file recurses when categorical.rb reopens
+   the class), so the gate arms itself lazily the first time it sees a fixlen
+   CArray index — the only thing a categorical can be, and never a real plain
+   index.  That covers a categorical built via CACategorical.from_codes that
+   never touched the axis-group file.  Scalar / range / integer indices never
+   reach this branch, so they never trigger the require. */
+int
+ca_argv_has_group (int argc, VALUE *argv)
+{
+  int i;
+  for ( i = 0; i < argc; i++ ) {
+    VALUE a = argv[i];
+    if ( RB_TYPE_P(a, T_OBJECT) ) {
+      if ( ! NIL_P(rb_cAxisGroup) && rb_obj_is_kind_of(a, rb_cAxisGroup) ) {
+        return 1;
+      }
+    }
+    else if ( RB_TYPE_P(a, T_DATA)
+              && rb_typeddata_is_kind_of(a, &carray_data_type) ) {
+      CArray *ca = (CArray *) DATA_PTR(a);
+      if ( ca->data_type == CA_FIXLEN ) {
+        if ( NIL_P(rb_cCategorical) ) {
+          rb_require("carray/axis_group");   /* lazily arm (registers) */
+        }
+        if ( ! NIL_P(rb_cCategorical) && rb_obj_is_kind_of(a, rb_cCategorical) ) {
+          return 1;
+        }
+      }
+    }
+  }
+  return 0;
+}
+
+/* Build a CAGroupIterator for `self[*argv]`.  Two entry forms:
+     (A) one-shot   self[idx, nil, ...]  -> build the spec via axis_group(*argv)
+     (B) pre-built  self[g]              -> g is already an AxisGroup spec
+   Pre-condition: ca_argv_has_group(argc, argv) is true. */
+VALUE
+rb_ca_fetch_group (int argc, VALUE *argv, VALUE self)
+{
+  volatile VALUE spec;
+
+  if ( argc == 1 && ! NIL_P(rb_cAxisGroup)
+       && rb_obj_is_kind_of(argv[0], rb_cAxisGroup) ) {
+    spec = argv[0];
+  }
+  else {
+    /* one-shot: raw CACategorical / nil slots -> build the spec (axis_group
+       validates the slot layout = one slot per source axis). */
+    spec = rb_funcallv(self, id_axis_group, argc, argv);
+  }
+  return rb_funcall(rb_cCAGroupIterator, rb_intern("__build__"), 2, self, spec);
+}
+
+/* --- CAGroupIterator -------------------------------------------------------
+
+   A reduction dispatcher, not an array: it holds the source value + the
+   AxisGroup spec and exposes the tier-1 reductions.  There is no to_ca / copy
+   / materialise path — the grouping only exists as the reduction's argument. */
+
+static VALUE
+rb_ca_group_iter_build (VALUE klass, VALUE value, VALUE spec)
+{
+  VALUE obj = rb_obj_alloc(klass);
+  rb_ivar_set(obj, id_value, value);
+  rb_ivar_set(obj, id_spec,  spec);
+  return obj;
+}
+
+static VALUE
+rb_ca_group_iter_value (VALUE self)
+{
+  return rb_ivar_get(self, id_value);
+}
+
+static VALUE
+rb_ca_group_iter_spec (VALUE self)
+{
+  return rb_ivar_get(self, id_spec);
+}
+
+static VALUE
+rb_ca_group_iter_labels (int argc, VALUE *argv, VALUE self)
+{
+  VALUE spec = rb_ivar_get(self, id_spec);
+  return rb_funcallv_kw(spec, id_labels, argc, argv, RB_PASS_CALLED_KEYWORDS);
+}
+
+/* Reduce the grouped result by `perm`/`squeeze` from the plan:
+     result (= [K_total, *band]) -> reshape [*group_dims, *band]
+                                  -> transpose to slot order (perm)
+                                  -> squeeze the length-1 fused-band axes. */
+static VALUE
+group_iter_shape_output (VALUE result, VALUE group_dims, VALUE perm, VALUE squeeze)
+{
+  CArray *cr;
+  VALUE   dims[CA_RANK_MAX];
+  VALUE   pargv[CA_RANK_MAX];
+  long    ng, nband, nd, i;
+
+  GetCArray(result, cr);
+
+  /* reshape target = group_dims ++ result.shape[1..] (drop leading K_total) */
+  ng    = RARRAY_LEN(group_dims);
+  nband = cr->ndim - 1;
+  nd    = ng + nband;
+  if ( nd > CA_RANK_MAX ) {
+    rb_raise(rb_eRuntimeError, "axis_group: output ndim %ld too large", nd);
+  }
+  for ( i = 0; i < ng; i++ ) {
+    dims[i] = RARRAY_AREF(group_dims, i);
+  }
+  for ( i = 0; i < nband; i++ ) {
+    dims[ng + i] = SIZE2NUM(cr->dim[i + 1]);
+  }
+  result = rb_funcall2(result, id_reshape, (int) nd, dims);
+
+  /* transpose to slot order */
+  for ( i = 0; i < nd; i++ ) {
+    pargv[i] = RARRAY_AREF(perm, i);
+  }
+  result = rb_funcall2(result, id_transpose, (int) nd, pargv);
+
+  /* squeeze the fused (length-1) band slots */
+  if ( RARRAY_LEN(squeeze) > 0 ) {
+    char drop[CA_RANK_MAX];
+    VALUE keep[CA_RANK_MAX];
+    long  nkeep = 0, j;
+    GetCArray(result, cr);
+    for ( i = 0; i < cr->ndim; i++ ) drop[i] = 0;
+    for ( j = 0; j < RARRAY_LEN(squeeze); j++ ) {
+      long s = NUM2LONG(RARRAY_AREF(squeeze, j));
+      if ( s >= 0 && s < cr->ndim ) drop[s] = 1;
+    }
+    for ( i = 0; i < cr->ndim; i++ ) {
+      if ( ! drop[i] ) keep[nkeep++] = SIZE2NUM(cr->dim[i]);
+    }
+    result = rb_funcall2(result, id_reshape, (int) nkeep, keep);
+  }
+  return result;
+}
+
+/* Shared driver for every tier-1 reduction.  The op is read from the called
+   method name (rb_frame_this_func), so the 10 white-list names all bind here.
+   axis: absent / no :group  -> delegate to the value's plain same-named
+   reduction (grouping NOT engaged).  axis: contains :group -> group reduction
+   (+ any integer band axes folded into the statistic). */
+static VALUE
+group_iter_reduce (int argc, VALUE *argv, VALUE self)
+{
+  ID    op_id  = rb_frame_this_func();
+  VALUE op_sym = ID2SYM(op_id);
+  VALUE value  = rb_ivar_get(self, id_value);
+  VALUE spec   = rb_ivar_get(self, id_spec);
+  VALUE kw = Qnil, vaxis;
+  VALUE parsed, plan;
+  VALUE group_axes, bundles, group_dims, perm, squeeze, fused;
+  VALUE result;
+
+  rb_scan_args(argc, argv, "0:", &kw);
+  vaxis = NIL_P(kw)
+          ? Qundef
+          : rb_hash_lookup2(kw, ID2SYM(rb_intern("axis")), Qundef);
+
+  /* (has_group, fused_band_slots) */
+  parsed = rb_funcall(rb_cAxisGroup, id_parse_axis,
+                      1, (vaxis == Qundef) ? Qnil : vaxis);
+  if ( RTEST(RARRAY_AREF(parsed, 0)) == 0 ) {
+    /* no :group -> plain reduction on the value (grouping not engaged) */
+    if ( vaxis == Qundef ) {
+      return rb_funcall(value, op_id, 0);
+    }
+    else {
+      VALUE h = rb_hash_new();
+      rb_hash_aset(h, ID2SYM(rb_intern("axis")), vaxis);
+      return rb_funcallv_kw(value, op_id, 1, &h, RB_PASS_KEYWORDS);
+    }
+  }
+
+  /* group reduction */
+  fused = RARRAY_AREF(parsed, 1);
+  plan  = rb_funcall(spec, id_reduce_plan, 1, fused);
+  group_axes = RARRAY_AREF(plan, 0);
+  bundles    = RARRAY_AREF(plan, 1);
+  group_dims = RARRAY_AREF(plan, 2);
+  perm       = RARRAY_AREF(plan, 3);
+  squeeze    = RARRAY_AREF(plan, 4);
+
+  result = rb_funcall(value, id_axis_group_reduce, 3,
+                      group_axes, bundles, op_sym);
+  return group_iter_shape_output(result, group_dims, perm, squeeze);
+}
+
+void
+Init_ca_group_iter (void)
+{
+  id_value             = rb_intern("@value");
+  id_spec              = rb_intern("@spec");
+  id_axis_group        = rb_intern("axis_group");
+  id_reduce_plan       = rb_intern("reduce_plan");
+  id_parse_axis        = rb_intern("parse_axis");
+  id_axis_group_reduce = rb_intern("__axis_group_reduce__");
+  id_reshape           = rb_intern("reshape");
+  id_transpose         = rb_intern("transpose");
+  id_labels            = rb_intern("labels");
+
+  rb_define_singleton_method(rb_cCArray, "__register_axis_group_classes__",
+                             rb_ca_register_axis_group_classes, 2);
+
+  rb_cCAGroupIterator =
+    rb_define_class("CAGroupIterator",
+                    rb_const_get(rb_cObject, rb_intern("CAIterator")));
+  rb_gc_register_address(&rb_cCAGroupIterator);
+
+  rb_define_singleton_method(rb_cCAGroupIterator, "__build__",
+                             rb_ca_group_iter_build, 2);
+  rb_define_method(rb_cCAGroupIterator, "value",  rb_ca_group_iter_value,  0);
+  rb_define_method(rb_cCAGroupIterator, "spec",   rb_ca_group_iter_spec,   0);
+  rb_define_method(rb_cCAGroupIterator, "labels", rb_ca_group_iter_labels, -1);
+
+  /* reduction white-list.  All bind to one driver; the op is recovered from
+     the called method name.  count_not_masked is a synonym of count (present
+     count); elements / count_masked / minmax / wsum / wmean are composed in
+     Ruby (lib/carray/axis_group.rb).  min_addr / max_addr give the flat source
+     address of the extremum (there is no group-local min_index for the group
+     iterator -- the order-preserving flat address is the meaningful position). */
+  {
+    const char *ops[] = { "sum", "accumulate", "prod", "mean", "min", "max",
+                          "variance", "stddev", "variancep", "stddevp",
+                          "count", "count_not_masked", "min_addr", "max_addr",
+                          "all", "any", NULL };
+    int i;
+    for ( i = 0; ops[i]; i++ ) {
+      rb_define_method(rb_cCAGroupIterator, ops[i], group_iter_reduce, -1);
+    }
+  }
+}