carray 3.0.2 → 3.0.4

data/ext/ca_axis_descriptor.h

@@ -2,13 +2,10 @@
 
   ca_axis_descriptor.h
 
-  Per-axis descriptor framework (D1 + D2 + D3) — shared C-level vocabulary
-  that lets CSA, CAGrid, CASelectAxis, CAWindow, CAShift, and future
+  Per-axis descriptor framework — shared C-level vocabulary that lets
+  CASelectAxis, CAGrid, CASelect, CAWindow, CAShift, and future
   per-axis-mixed views describe each axis the same way so a common
-  attach dispatch engine (D3, ca_axis_dispatch.c) can drive them
-  uniformly.
-
-  See devel/PROPOSAL_AXIS_DESCRIPTOR_FRAMEWORK.md for the design.
+  attach dispatch engine (ca_axis_dispatch.c) can drive them uniformly.
 
   Status: TWO-TIER FREEZE CONTRACT (3.0 onward), the same split
   ca_kernel_iterator.h declares, for the same reason: this header is
@@ -50,14 +47,14 @@
    When this header is included from carray.h mid-file, those typedefs
    are already in scope by the time we reach the include site. */
 
-/* ---- D1: per-axis descriptor types ----------------------------------------
+/* ---- per-axis descriptor types --------------------------------------------
 
    STRIDE = linear stride axis: parent index = start + i*step,
             i in [0, count).  Subsumes nil / Integer / Range index args.
    INDEX  = integer index axis:  parent index = indices[i],
             i in [0, count).  Subsumes integer-array (CAGrid)
             and boolean-mask-after-snapshot (CASelectAxis) axes.
-   SHIFT  = bound-aware stride axis (CAWindow/CAShift, Tier 2.B):
+   SHIFT  = bound-aware stride axis (CAWindow/CAShift):
             parent index = start + i*step normalised by `policy`
             (CA_BOUNDS_FILL / PERIODIC / REFLECT / NEAREST / ...)
             against `size0` (= parent dim along this axis).  When
@@ -86,16 +83,17 @@ typedef struct {
   uint8_t         policy;    /* CA_BOUNDS_FILL / PERIODIC / REFLECT / ... */
 } ca_axis_desc_t;
 
-/* ---- D2: producer interface ----------------------------------------------
+/* ---- producer interface --------------------------------------------------
 
-   Both implementations write ndim entries into `out` (caller-allocated)
-   and `out_parent_dims` (caller-allocated, sized CA_RANK_MAX).  See
-   devel/PROPOSAL_AXIS_DESCRIPTOR_FRAMEWORK.md §5 Framework Phase 1 and
-   devel/PROPOSAL_FLAT_INDEX_VIEWS.md §2.3 for rationale.
+   A producer writes one entry per descriptor axis into `out`
+   (caller-allocated) and `out_parent_dims` (caller-allocated, sized
+   CA_RANK_MAX).  The producers declared here are CASelectAxis and CAGrid;
+   CASelect and CAWindow have their own (ca_select_describe_axes /
+   ca_window_describe_axes).
 
    `out_parent_dims[k]` is the **effective** parent dim along descriptor
-   axis k — for CSA / CAGrid this is just `parent->dim[k]`, but for
-   flat-index views (CASelect / CAMapping, Tier 2.A.3+) it is
+   axis k — for CASelectAxis / CAGrid this is just `parent->dim[k]`, but
+   for a flat-index view (CASelect) it is
    `{parent->elements}` (a single-axis flat view of parent).  This
    decouples descriptor.ndim from parent.ndim so the engine can drive
    views whose iteration axes don't match the parent's physical shape.
@@ -103,13 +101,17 @@ typedef struct {
    Pointer arguments are typed `void *` here to avoid pulling the
    private CASelectAxis / CAGrid struct definitions (which live in
    their respective .c files) into this header.  Each implementation
-   casts to its concrete type inside the .c file. */
+   casts to its concrete type inside the .c file.
+
+   An INDEX axis has no way to say "no cell": a CAGrid index that is
+   masked (a hole) is written as index 0, so a caller driving a holed grid
+   through the engine reads and writes parent cell 0 there. */
 void ca_select_axis_describe_axes (void *ca, ca_axis_desc_t *out,
                                    ca_size_t *out_parent_dims);
 void ca_grid_describe_axes        (void *ca, ca_axis_desc_t *out,
                                    ca_size_t *out_parent_dims);
 
-/* ---- D3: common attach engine --------------------------------------------
+/* ---- common attach engine -------------------------------------------------
 
    Drives gather from `parent` into an output buffer driven by the
    per-axis descriptor array.  Caller must have parent attached before
@@ -119,14 +121,15 @@ void ca_grid_describe_axes        (void *ca, ca_axis_desc_t *out,
    descriptor axis (see producer interface above).  The engine never
    reads `parent->dim` directly — it only reads `parent->ptr` for
    data access — which is what allows flat-index views to lie about
-   parent's apparent shape (Tier 2.A, PROPOSAL_FLAT_INDEX_VIEWS.md).
+   parent's apparent shape.
 
    `bound_fill` is the bytes-wide value written into gather output
-   cells whose SHIFT axes resolve to an out-of-bounds parent index
-   (Tier 2.B, PROPOSAL_BOUND_AWARE_VIEWS.md).  Pass NULL when no
-   SHIFT axis is present (CSA / CAGrid / CASelect / CAMapping); the
-   engine ignores it.  On scatter, the engine simply skips parent
-   writes for OOB cells regardless of bound_fill.
+   cells whose SHIFT axes resolve to an out-of-bounds parent index.
+   Pass NULL when no SHIFT axis is present (CASelectAxis / CAGrid /
+   CASelect); the engine ignores it.  On scatter, the engine simply skips
+   parent writes for OOB cells regardless of bound_fill.  A SHIFT axis
+   under the RUBY or STRICT policy raises IndexError part way through the
+   walk for an index outside the parent.
 
    _gather — caller provides out_buf (must be sized total_elements*bytes)
    _attach — wrapper that mallocs the buffer; caller xfrees
@@ -160,7 +163,7 @@ void  ca_axis_dispatch_scatter (struct _CArray  *parent,
                                 ca_size_t        total_elements,
                                 const char      *in_buf);
 /* Broadcast scatter: write the single value `val` (bytes wide) into
-   every selected parent cell.  See D6 of the framework piece.
+   every selected parent cell.
    (SHIFT axis OOB cells are skipped — fill semantics aren't
    meaningful for broadcast-write since the destination value already
    IS the broadcast value.) */

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>
 
@@ -393,6 +394,100 @@ ca_axis_dispatch_fill_value_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
   }
 }
 
+/* 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
@@ -437,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. */
@@ -951,3 +1057,117 @@ 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];
+
+  args[0] = ca;
+  args[1] = buf;
+  ca_fill_or_xfree(buf, ca_axis_view_fill_owned, (VALUE) args);
+  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);
+}