carray 3.0.1 → 3.0.3

data/README.md

@@ -4,17 +4,16 @@ Ruby/CArray is an extension library for the multi-dimensional array class. It pr
 
 ## Status
 
-3.0.x still moves: behavior can change between releases — see [CHANGELOG.md](CHANGELOG.md). 3.1 is the first release meant to be depended on. Until then, treat it as a place to try things out.
+3.0.x still moves: behavior can change between releases. 3.1 is the first release meant to be depended on. Until then, treat it as a place to try things out.
 
 ## Features
 
 * Every array carries a per-element mask for missing values, respected by reductions and statistics
 * Views compose without copying — a write through the outermost view reaches the source data
 * MemoryView protocol on both sides: share buffers with other numerical libraries without copying
-* Kernel-style iteration: run a Ruby block over each sub-array spanning the axes you choose
-* Attach domain meaning (time, angle, quantity with units…) without changing storage — a Face
 * Define your own array class in pure Ruby while keeping the full CArray interface
-* Pack multiple values into one element as a record type
+* Kernel-style iteration: run a Ruby block over each sub-array spanning the axes you choose
+* Faces: array types for time, strings and categories, with methods of their own on top of everything CArray does
 * Comes with a DataFrame (`CAFrame`) whose columns are plain CArrays, so masks and views keep working on them
 
 Each of these is shown, briefly and with a runnable example, in [A tour of the features](docs/FeatureTour.md).
@@ -129,9 +128,9 @@ Bug reports and feature requests are welcome — please open an issue.
 
 ## Credits
 
-Up to version 2.0, CArray was authored by himotoyoshi.
+CArray is created and maintained by himotoyoshi.
 
-CArray 3.0 was designed and reviewed by a human developer; the implementation was produced in collaboration with AI coding tools.
+Versions up to 2.0 were written by the author. For version 3.0, the author provided the design, and most of the implementation was rewritten with AI coding tools; it has been verified primarily through the test suite and practical use.
 
 ## License
 

data/carray.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = "carray"
-  s.version     = "3.0.1"
+  s.version     = "3.0.3"
   s.authors      = ["himotoyoshi"]
   s.email       = ["himotoyoshi@users.noreply.github.com"]
   s.summary     = "Multi-dimensional numerical array class for Ruby"

data/ext/ca_axis_dispatch.c

@@ -42,6 +42,7 @@
 #include "carray.h"
 #include "ca_iter_substrate.h"
 #include "ca_composite_dispatch.h"
+#include "carray_internal.h"   /* ca_parent_lends_no_memory */
 
 #include <string.h>
 
@@ -339,13 +340,27 @@ ca_axis_dispatch_scatter_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
 /* Callback context for fill_value (broadcast a single value).  parent is set
    when the value goes through the parent's own fill_stride instead of a
    buffer this side has attached. */
+/* Same size as the window ca_fill_stride_via_addrs collects into. */
+#define CA_AXIS_FILL_ADDR_WINDOW 1024
+
 typedef struct {
   const void *val;
   ca_size_t   bytes;
   char       *parent_ptr;
   CArray     *parent;
+  ca_size_t   window[CA_AXIS_FILL_ADDR_WINDOW];
+  ca_size_t   nw;
 } ca_axis_fill_ctx_t;
 
+static void
+ca_axis_dispatch_fill_flush (ca_axis_fill_ctx_t *c)
+{
+  if ( c->nw ) {
+    ca_fill_addrs(c->parent, c->nw, c->window, (void *) c->val);
+    c->nw = 0;
+  }
+}
+
 static void
 ca_axis_dispatch_fill_value_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
 {
@@ -354,17 +369,125 @@ ca_axis_dispatch_fill_value_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
   if ( c->parent ) {
     /* One slab is one contiguous run of parent cells, which is a region the
        parent can fill for itself -- no borrowed buffer, so nothing outside
-       the run is read or written. */
+       the run is read or written.  A run of one cell is not worth a call of
+       its own, though: when the innermost selected axis picks individual
+       indices every run is one cell, and the same cell count that costs the
+       parent eight calls on an outer axis cost it one per cell here.  Collect
+       those and hand them over as a list.  The value is the same for every
+       cell and the walk visits each cell once, so batching cannot change
+       which cells are written. */
     ca_size_t count = n / c->bytes;
-    ca_size_t step  = 1;
-    ca_fill_stride(c->parent, off / c->bytes, 1, &count, &step,
-                   (void *) c->val);
+    if ( count == 1 ) {
+      c->window[c->nw++] = off / c->bytes;
+      if ( c->nw == CA_AXIS_FILL_ADDR_WINDOW ) {
+        ca_axis_dispatch_fill_flush(c);
+      }
+    }
+    else {
+      ca_size_t step = 1;
+      ca_fill_stride(c->parent, off / c->bytes, 1, &count, &step,
+                     (void *) c->val);
+    }
   }
   else {
     ca_axis_dispatch_fill_slab(c->parent_ptr + off, c->val, c->bytes, n);
   }
 }
 
+/* Rows whose innermost axis is a step-1 SHIFT axis.  View cell i of the row
+   reads parent cell start + i, so the cells with 0 <= start + i < size0 form
+   one run and go to cb together.  The cells before and after it are out of
+   range: under FILL / MASK every one of them is (cb gets each side as one
+   oob slab), under the other policies each maps to a cell of its own. */
+static void
+ca_axis_dispatch_shift_cell (const ca_axis_desc_t *ax, ca_size_t pstride,
+                             ca_size_t row_off, ca_size_t i, ca_size_t bytes,
+                             ca_slab_cb_t cb, void *ctx)
+{
+  ca_size_t pi = ca_bounds_normalize_index(ax->policy, ax->size0,
+                                           ax->start + i);
+  if ( pi < 0 || pi >= ax->size0 ) {
+    cb(row_off, 1, bytes, ctx);
+  }
+  else {
+    cb(row_off + pi * pstride, 0, bytes, ctx);
+  }
+}
+
+static void
+ca_axis_dispatch_for_each_shift_row (ca_axis_desc_t  *laxes,
+                                     const ca_size_t *pstrides,
+                                     int8_t           lndim,
+                                     ca_size_t        bytes,
+                                     ca_size_t        total_elements,
+                                     ca_slab_cb_t     cb,
+                                     void            *ctx)
+{
+  int8_t               inner   = lndim - 1;
+  const ca_axis_desc_t *ax     = &laxes[inner];
+  ca_size_t            pstride = pstrides[inner];
+  ca_size_t            count   = ax->count;
+  int                  coalesce = ( ax->policy == CA_BOUNDS_FILL
+                                    || ax->policy == CA_BOUNDS_MASK );
+  ca_op_prefix_axis_t  prefix[CA_RANK_MAX];
+  ca_size_t            idx[CA_RANK_MAX];
+  ca_size_t            lo, hi, n_rows, r, i;
+  int8_t               k;
+
+  /* In-range view cells: lo <= i < hi. */
+  lo = -ax->start;
+  if ( lo < 0 )     lo = 0;
+  if ( lo > count ) lo = count;
+  hi = ax->size0 - ax->start;
+  if ( hi > count ) hi = count;
+  if ( hi < lo )    hi = lo;
+
+  ca_axis_dispatch_classify_prefix(laxes, pstrides, inner, prefix);
+  for ( k = 0; k < inner; k++ ) idx[k] = 0;
+
+  n_rows = total_elements / count;
+  for ( r = 0; r < n_rows; r++ ) {
+    int oob;
+    ca_size_t row_off = ca_axis_dispatch_prefix_offset(prefix, idx, inner,
+                                                       &oob);
+    if ( oob ) {
+      cb(row_off, 1, count * bytes, ctx);
+    }
+    else {
+      if ( lo > 0 ) {
+        if ( coalesce ) {
+          cb(row_off, 1, lo * bytes, ctx);
+        }
+        else {
+          for ( i = 0; i < lo; i++ ) {
+            ca_axis_dispatch_shift_cell(ax, pstride, row_off, i, bytes,
+                                        cb, ctx);
+          }
+        }
+      }
+      if ( hi > lo ) {
+        cb(row_off + (ax->start + lo) * pstride, 0, (hi - lo) * bytes, ctx);
+      }
+      if ( hi < count ) {
+        if ( coalesce ) {
+          cb(row_off, 1, (count - hi) * bytes, ctx);
+        }
+        else {
+          for ( i = hi; i < count; i++ ) {
+            ca_axis_dispatch_shift_cell(ax, pstride, row_off, i, bytes,
+                                        cb, ctx);
+          }
+        }
+      }
+    }
+
+    for ( k = inner - 1; k >= 0; k-- ) {
+      if ( ++idx[k] < prefix[k].count ) break;
+      idx[k] = 0;
+    }
+  }
+}
+
 /* Generic per-slab driver.  Walks the (post-merge / post-layout)
    prefix axes row-major and invokes `cb` once per slab iteration.
    The all-slab case degenerates to a single `cb` invocation with
@@ -409,6 +532,17 @@ ca_axis_dispatch_for_each_slab (CArray          *parent,
     return;
   }
 
+  /* Innermost SHIFT axis with step 1: the in-range part of each row is one
+     contiguous run of parent cells, so it goes to cb as one slab instead of
+     one cell at a time. */
+  if ( slab_start == lndim
+       && laxes[lndim - 1].kind == CA_AXIS_KIND_SHIFT
+       && laxes[lndim - 1].step == 1 ) {
+    ca_axis_dispatch_for_each_shift_row(laxes, pstrides, lndim, bytes,
+                                        total_elements, cb, ctx);
+    return;
+  }
+
   /* Pre-classify prefix axes once.  Inner loop becomes branchless
      modulo a per-axis kind tag whose value is constant across
      iters. */
@@ -895,6 +1029,7 @@ ca_axis_dispatch_fill_value_via_parent (CArray          *parent,
   ca_axis_dispatch_for_each_slab(parent, parent_axis_dims, axes, ndim,
                                  bytes, total_elements,
                                  ca_axis_dispatch_fill_value_cb, &ctx);
+  ca_axis_dispatch_fill_flush(&ctx);
 }
 
 /* ==========================================================================
@@ -922,3 +1057,122 @@ ca_axis_dispatch_outer_has_shift (const ca_axis_desc_t *descs,
   }
   return 0;
 }
+
+/* ==========================================================================
+   Transfers of a descriptor view (CAGrid, CASelect, CASelectAxis, CAWindow)
+   whose parent holds no ptr.
+
+   The engine above walks parent->ptr.  A cold parent is handled by what it
+   is:
+
+     - one ca_attach_is_alias accepts already has the memory: borrow it;
+     - one with no memory to lend (ca_parent_lends_no_memory) is asked for
+       the selected cells only, through the view's own xfer_stride over the
+       whole view -- producing every cell of the parent to serve a selection
+       would make the cost follow the parent's size;
+     - anything else is gathered into a parent-shaped scratch that stands in
+       for parent->ptr, and pushed back for PUT.
+   ========================================================================== */
+
+/* The whole view as one region request to its own xfer_stride slot. */
+static void
+ca_axis_view_xfer_region (CArray *ca, void *data, int dir)
+{
+  ca_size_t starts[CA_RANK_MAX], strides[CA_RANK_MAX], s;
+  int8_t    k;
+
+  /* The slot is called directly, past ca_xfer_stride's empty-region check. */
+  if ( ca->elements == 0 ) return;
+
+  s = ca->bytes;
+  for ( k = ca->ndim - 1; k >= 0; k-- ) {
+    starts[k]  = 0;
+    strides[k] = s;
+    s *= ca->dim[k];
+  }
+  ca_func[ca->obj_type].xfer_stride(ca, starts, ca->dim, strides, data, dir);
+}
+
+void
+ca_axis_view_xfer_all (void *ap, ca_axis_view_fast_t fast, int region_ok,
+                       void *data, int dir)
+{
+  CArray *ca     = (CArray *) ap;
+  CArray *parent = ((CAView *) ca)->parent;
+
+  if ( parent->ptr ) {
+    fast(ca, (char *) data, dir);
+    return;
+  }
+
+  if ( ca_attach_is_alias(parent) ) {
+    ca_attach(parent);   /* window: an alias attach, cannot raise */
+    fast(ca, (char *) data, dir);
+    ca_detach(parent);
+    return;
+  }
+
+  if ( region_ok && ca_parent_lends_no_memory(parent) ) {
+    ca_axis_view_xfer_region(ca, data, dir);
+    return;
+  }
+
+  {
+    volatile VALUE holder;
+    ca_size_t plen   = parent->elements * parent->bytes;
+    char     *parent_scratch = ALLOCV_N(char, holder, plen);
+    ca_xfer_all(parent, parent_scratch, CA_XFER_GET);
+    parent->ptr = parent_scratch;
+    fast(ca, (char *) data, dir);
+    /* Put parent->ptr back before the PUT: the PUT can raise (a lazy
+       backing's sync failing), and the scratch is gone once this frame
+       is. */
+    parent->ptr = NULL;
+    if ( dir == CA_XFER_PUT ) {
+      ca_xfer_all(parent, parent_scratch, CA_XFER_PUT);
+    }
+    ALLOCV_END(holder);
+  }
+}
+
+/* The attach of a view that owns its buffer and fills it through its own
+   transfers (a descriptor view whose parent has no memory to lend, CARemap,
+   CAStack, CAMeld).  The buffer is published only once filled -- a view
+   with a live ptr makes the per-cell dispatchers bypass the transfer slots,
+   and for CA_OBJECT the garbage cells of an unfilled buffer would be marked
+   -- and a raise while filling frees it.  The fill goes through ca_xfer_all,
+   which holds the object cells against a collection while the transfers
+   call Ruby. */
+
+static VALUE
+ca_axis_view_fill_owned (VALUE arg)
+{
+  void **args = (void **) arg;
+  ca_xfer_all((CArray *) args[0], args[1], CA_XFER_GET);
+  return Qnil;
+}
+
+void
+ca_axis_view_attach_owned (void *ap)
+{
+  CArray *ca  = (CArray *) ap;
+  char   *buf = xmalloc(ca_length(ca) > 0 ? ca_length(ca) : 1);
+  void   *args[2];
+  int     tag = 0;
+
+  args[0] = ca;
+  args[1] = buf;
+  rb_protect(ca_axis_view_fill_owned, (VALUE) args, &tag);
+  if ( tag ) {
+    xfree(buf);
+    rb_jump_tag(tag);
+  }
+  ca->ptr = buf;
+}
+
+void
+ca_axis_view_sync_owned (void *ap)
+{
+  CArray *ca = (CArray *) ap;
+  ca_func[ca->obj_type].xfer_all(ca, ca->ptr, CA_XFER_PUT);
+}