carray 3.0.2 → 3.0.4

data/ext/ca_compare.c

@@ -14,6 +14,7 @@
 #include "ruby.h"
 #include "carray.h"
 #include "ca_compare.h"
+#include "carray_internal.h"   /* CA_FLOAT_ORDER_CMP, ca_obj_order_cmp */
 #include <math.h>
 
 #define DEFINE_ELEM_CMP(type)                          \
@@ -27,18 +28,14 @@ elem_cmp_## type (const void *va, const void *vb)      \
   return 0;                                            \
 }
 
-/* Float order: NaN sorts last (matches the sort kernels' NaN-at-end). */
+/* Float order: NaN after every number (CA_FLOAT_ORDER_CMP). */
 #define DEFINE_ELEM_CMP_FLOAT(type)                    \
 static int                                             \
 elem_cmp_## type (const void *va, const void *vb)      \
 {                                                      \
-  const type *a = (const type *) va;                   \
-  const type *b = (const type *) vb;                   \
-  if ( isnan(*a) && ( ! isnan(*b) ) ) return  1;       \
-  if ( isnan(*b) && ( ! isnan(*a) ) ) return -1;       \
-  if ( *a > *b ) return  1;                            \
-  if ( *a < *b ) return -1;                            \
-  return 0;                                            \
+  const type a = *(const type *) va;                   \
+  const type b = *(const type *) vb;                   \
+  return CA_FLOAT_ORDER_CMP(a, b);                     \
 }
 
 DEFINE_ELEM_CMP(boolean8_t)
@@ -53,13 +50,11 @@ DEFINE_ELEM_CMP(uint64_t)
 DEFINE_ELEM_CMP_FLOAT(float32_t)
 DEFINE_ELEM_CMP_FLOAT(float64_t)
 
-/* CA_OBJECT: compare via Ruby Comparable (`<=>`). */
+/* CA_OBJECT: the object order (ca_obj_order_cmp). */
 static int
 elem_cmp_VALUE (const void *va, const void *vb)
 {
-  const VALUE *a = (const VALUE *) va;
-  const VALUE *b = (const VALUE *) vb;
-  return NUM2INT(rb_funcall(*a, rb_intern("<=>"), 1, *b));
+  return ca_obj_order_cmp(*(const VALUE *) va, *(const VALUE *) vb);
 }
 
 /* FIXLEN / retired / otherwise unorderable data_types: callers must handle

data/ext/ca_for_buffer.h

@@ -1,43 +1,33 @@
 /* ---------------------------------------------------------------------------
  *
- *  ca_for_buffer.h -- sweep WHOLE_BUFFER macro family (whole contig buffer
- *                    handed to author / third-party library)
+ *  ca_for_buffer.h -- 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, ...).
+ *  C-side counterpart of Ruby's `ca.attach! { |a| ... }` block: the
+ *  attach / sync / detach lifecycle is scoped to a body function, which
+ *  receives a contig buffer ptr and element count and may 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):
+ *  The buffer aliases ca->ptr when the array is a contig entity and is a
+ *  materialised scratch otherwise.  A writable call syncs the buffer back
+ *  to the array's storage when the body returns.
  *
- *    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.
+ *  The body may raise.  The view is closed however the body is left: a
+ *  writable view is synced first, so what the body wrote before raising
+ *  reaches the view's storage, and the view is detached even if that sync
+ *  raises.  The body's exception is the one that propagates.
  *
  *  Author pattern:
  *
- *    double *ptr;
- *    ca_size_t n;
- *    CA_WITH_BUFFER_WRITABLE(ca, double, ptr, n) {
+ *    static void
+ *    fft_body (void *user_data, void *ptr, ca_size_t n)
+ *    {
+ *      fftw_plan plan = (fftw_plan) user_data;
  *      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).
+ *    rb_ca_call_with_buffer(rca, 1, fft_body, plan);
  *
  *  --------------------------------------------------------------------------- */
 
@@ -47,46 +37,9 @@
 #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
+/*   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.
- */
+ * Returns nothing; box a result in user_data. */
 typedef void (*ca_with_buffer_body_fn) (void *user_data, void *ptr,
                                       ca_size_t n_elements);
 

data/ext/ca_group_iter.c

@@ -14,13 +14,14 @@
   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_by_axis_groups__ : here
     - reduce_plan / bundle assembly / output-axis permutation (metadata) : Ruby
-    - the O(N) compute kernel __axis_group_reduce__ : ca_axis_group.c
+    - the O(N) compute kernel __reduce_by_axis_groups__ : ca_axis_group.c
 
 --------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "carray_internal.h"   /* ca_check_rank_fits */
 
 /* 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 —
@@ -34,16 +35,20 @@ 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
+/* 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)
 {
+  static int registered = 0;
   rb_cCategorical = cat;
   rb_cAxisGroup   = ag;
-  rb_gc_register_address(&rb_cCategorical);
-  rb_gc_register_address(&rb_cAxisGroup);
+  if ( ! registered ) {               /* one GC root per address, not per call */
+    rb_gc_register_address(&rb_cCategorical);
+    rb_gc_register_address(&rb_cAxisGroup);
+    registered = 1;
+  }
   return Qnil;
 }
 
@@ -116,7 +121,7 @@ rb_ca_fetch_group (int argc, VALUE *argv, VALUE self)
        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);
+  return rb_funcall(rb_cCAGroupIterator, rb_intern("build_for"), 2, self, spec);
 }
 
 /* --- CAGroupIterator -------------------------------------------------------
@@ -171,9 +176,7 @@ group_iter_shape_output (VALUE result, VALUE group_dims, VALUE perm, VALUE squee
   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);
-  }
+  ca_check_rank_fits(nd, "axis_group");
   for ( i = 0; i < ng; i++ ) {
     dims[i] = RARRAY_AREF(group_dims, i);
   }
@@ -215,7 +218,7 @@ group_iter_shape_output (VALUE result, VALUE group_dims, VALUE perm, VALUE squee
 static VALUE
 group_iter_reduce (int argc, VALUE *argv, VALUE self)
 {
-  ID    op_id  = rb_frame_this_func();
+  ID    op_id  = rb_frame_this_func();   /* frame-name: picks the op, names no error */
   VALUE op_sym = ID2SYM(op_id);
   VALUE value  = rb_ivar_get(self, id_value);
   VALUE spec   = rb_ivar_get(self, id_spec);
@@ -233,17 +236,19 @@ group_iter_reduce (int argc, VALUE *argv, VALUE self)
   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 ) {
+    /* no :group -> plain reduction on the value (grouping not engaged),
+       with every keyword the caller gave */
+    if ( NIL_P(kw) ) {
       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);
-    }
+    return rb_funcallv_kw(value, op_id, 1, &kw, RB_PASS_KEYWORDS);
   }
 
+  /* min_count: / fill_value: are applied to the grouped result; any other
+     keyword is refused before the work is done. */
+  rb_funcall(self, rb_intern("check_reduce_keywords"), 2,
+             op_sym, NIL_P(kw) ? rb_hash_new() : kw);
+
   /* group reduction */
   fused = RARRAY_AREF(parsed, 1);
   plan  = rb_funcall(spec, id_reduce_plan, 1, fused);
@@ -253,9 +258,19 @@ group_iter_reduce (int argc, VALUE *argv, VALUE self)
   perm       = RARRAY_AREF(plan, 3);
   squeeze    = RARRAY_AREF(plan, 4);
 
+  /* a count reads only the mask, so a payload the kernel cannot read
+     (object, fixlen, ...) is counted through a boolean stand-in */
+  if ( op_id == rb_intern("count") || op_id == rb_intern("count_not_masked") ) {
+    value = rb_funcall(rb_cAxisGroup, rb_intern("count_stand_in"), 1, value);
+  }
   result = rb_funcall(value, id_axis_group_reduce, 3,
                       group_axes, bundles, op_sym);
-  return group_iter_shape_output(result, group_dims, perm, squeeze);
+  result = group_iter_shape_output(result, group_dims, perm, squeeze);
+  if ( ! NIL_P(kw) ) {
+    result = rb_funcall(self, rb_intern("finish_reduction"), 3,
+                        op_sym, kw, result);
+  }
+  return result;
 }
 
 void
@@ -266,21 +281,21 @@ Init_ca_group_iter (void)
   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_axis_group_reduce = rb_intern("__reduce_by_axis_groups__");
   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_define_private_method(rb_singleton_class(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_private_method(rb_singleton_class(rb_cCAGroupIterator), "build_for",
+                           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);