carray 2.0.0 → 3.0.0

data/ext/ca_sweep_engine.h

@@ -0,0 +1,157 @@
+/* ---------------------------------------------------------------------------
+ *
+ *  ca_sweep_engine.h -- sweep (xfer_all) author surface engine, shared helper
+ *
+ *  Established in PROPOSAL_L0_AUTHOR_SURFACE L0.1 (2026-06-11).  Extracts
+ *  the xfer_all-aware lifecycle template previously duplicated 7-times in
+ *  ext/carray_call_cfunc.c (= one body per arity 1..7) into a single shared
+ *  helper.  Same helper will back the forthcoming CA_FOR_EACH_ELEMENT macro
+ *  family (L0.2a) and the WHOLE_BUFFER family (L0.2c).
+ *
+ *  Lifecycle template:
+ *    (1) per-operand acquire
+ *          OUTPUT (fsync=='1') -> ca_attach + use ca->ptr (sync on release)
+ *          INPUT  (fsync=='0') alias-able -> ca_attach + use ca->ptr
+ *          INPUT  (fsync=='0') non-alias  -> xmalloc + ca_xfer_all(GET)
+ *    (2) broadcast shape check (scalar collapse + n_kernel agreement)
+ *    (3) mask OR across INPUT operands -> m0 (xmalloc, NULL if none)
+ *    (4) mask propagate to OUTPUT operands (overwrite output->mask)
+ *    (5) caller runs the per-cell loop using base[] + stride[]
+ *    (6) per-operand release (reverse order):
+ *          sync OUTPUTs, detach attached or xfree owned_buf, xfree m0
+ *
+ *  Why xmalloc instead of ALLOCV_N:
+ *    ALLOCV_N uses alloca() for sizes < RUBY_ALLOCV_LIMIT (1024 B); the
+ *    allocation is bound to the calling C frame.  When the engine is
+ *    extracted to a helper function, the alloca'd region would die on
+ *    helper return.  xmalloc/xfree is frame-independent and safe to
+ *    carry across the helper boundary.  Cost: one heap call per non-alias
+ *    INPUT.  For arrays that warrant a kernel loop the cost is negligible.
+ *
+ *  --------------------------------------------------------------------------- */
+
+#ifndef CA_SWEEP_ENGINE_H
+#define CA_SWEEP_ENGINE_H
+
+#include "carray.h"
+
+/* Caller-allocated arrays of length n_ops:
+ *   - cx[]        IN:  CArray pointers (caller fills before ca_sweep_acquire)
+ *   - base[]      OUT: per-op base ptr for the per-cell loop
+ *   - stride[]    OUT: per-cell stride in bytes (0 for scalar broadcast)
+ *   - owned_buf[] OUT: xmalloc'd buffer (NULL if alias or OUTPUT path)
+ *   - attached[]  OUT: 1 if ca_attach was called (= release must ca_detach)
+ *
+ * Engine-allocated:
+ *   - m0          OUT: xmalloc'd mask byte array, NULL if no INPUT has mask
+ *   - n_kernel    OUT: broadcast element count
+ *
+ * fsync: per-op '0'/'1' string of length n_ops.  Lifetime must cover both
+ *        ca_sweep_acquire and ca_sweep_release (caller-owned, typically a string
+ *        literal or stack-stored).
+ *
+ * src_label: optional, included in [BUG] error message if fsync length
+ *            mismatches; NULL falls back to "ca_sweep_acquire".
+ */
+typedef struct ca_sweep_state {
+  int             n_ops;
+  const char     *fsync;
+  CArray        **cx;
+  char          **base;
+  ca_size_t      *stride;
+  char          **owned_buf;
+  int            *attached;
+  boolean8_t     *m0;
+  ca_size_t       n_kernel;
+  const char     *src_label;
+  /* no_mask: if non-zero, ca_sweep_acquire raises when any INPUT operand has
+   * a mask.  Used by the NO_MASK macro forms (CA_FOR_EACH_ELEMENT etc.) to
+   * implement Q3=(ii) runtime error policy.  Default 0 (= masked INPUT OK,
+   * m0 built as usual).  Caller sets before calling ca_sweep_acquire. */
+  int             no_mask;
+
+  /* === chunked path fields (L0.1 chunk, PROPOSAL_L0_AUTHOR_SURFACE) === */
+  /* Used by ca_sweep_acquire_chunked / ca_sweep_next_chunk / ca_sweep_release_chunked
+   * (= the sweep ELEMENT macro family).  Unused by the whole-materialise path
+   * (ca_sweep_acquire / ca_sweep_release) — cfunc and other whole-buffer callers
+   * leave these zero. */
+  char          **base_orig;     /* per-op original ptr (= ca->ptr for
+                                    alias/output; NULL for non-alias INPUT
+                                    that uses an arena chunk scratch).
+                                    Caller-allocated, length n_ops. */
+  ca_size_t       chunk_n;       /* current chunk element count */
+  ca_size_t       chunk_off;     /* current chunk start in flat addr */
+  ca_size_t       chunk_n_max;   /* max chunk size from ca_chunk_compute_n */
+  ca_size_t       inner;         /* product of dims except outermost (= row
+                                    size in elements for outer-axis chunking) */
+  int             chunked_state; /* 0=pre-init, 1=active, 2=done */
+} ca_sweep_state_t;
+
+/* Validate fsync length, acquire per-op buffers, compute broadcast shape +
+ * strides, build mask m0, propagate mask to OUTPUTs.  May raise (fsync
+ * length mismatch, shape mismatch). */
+void ca_sweep_acquire (ca_sweep_state_t *st);
+
+/* Reverse-order release: sync OUTPUTs, detach attached / xfree owned_buf,
+ * xfree m0.  State is single-use; do not call acquire again on the same
+ * state without re-initializing the caller-owned arrays. */
+void ca_sweep_release (ca_sweep_state_t *st);
+
+/* Strict full-shape equality check used by INOUT macros (AC5: silent-
+ * corruption seam prevention).  Raises if ndim differs or any dim[k]
+ * differs.  Returns void; raises on mismatch. */
+void ca_sweep_check_same_shape (CArray *ca_in, CArray *ca_out,
+                             const char *src_label);
+
+/* ===== Chunked path API (sweep ELEMENT macro family, L0.1 chunk) =====
+ *
+ * Unlike ca_sweep_acquire / ca_sweep_release (= whole-buffer materialise used
+ * by cfunc), the chunked path keeps INPUT memory peak bounded to chunk
+ * size (~32KB at f64 by default).  AC2 ancestor cascade prevention plus
+ * memory peak guarantee: shrinking views materialise into chunk scratch
+ * sized to inner-axis multiples, not full operand size.
+ *
+ * Usage shape (inside a macro):
+ *   ca_sweep_acquire_chunked(&st);
+ *   while (ca_sweep_next_chunk(&st)) {
+ *     for (k = 0; k < st.chunk_n; k++) {
+ *       T x = *(T*)(st.base[0] + k * st.stride[0]);
+ *       ...
+ *     }
+ *   }
+ *   ca_sweep_release_chunked(&st);
+ *
+ * OUTPUT operand semantics:
+ *   OUTPUT is ca_attach'd whole (= self IS write target, legitimate per
+ *   E.7 invariant), and base[k] is rewritten per chunk as base_orig[k] +
+ *   chunk_off * stride[k] so author writes land in the correct region.
+ *   Final ca_sync runs in release_chunked.  Output memory peak = entity
+ *   size (= unavoidable; output buffer must exist).
+ *
+ * INPUT operand semantics:
+ *   alias INPUT: base[k] = ca->ptr + chunk_off * stride[k], no gather.
+ *   non-alias INPUT: arena scratch of size chunk_n_max * bytes is held
+ *     for the entire walk; ca_chunked_gather rewrites it per chunk.
+ *
+ * Mask handling (m0):
+ *   Built once in acquire_chunked at full size (= n_kernel bytes).
+ *   Macros that want per-cell mask read at m0[chunk_off + k].
+ *   Full-size m0 mirrors the whole path; per-chunk mask gather is a
+ *   future optim.
+ */
+void ca_sweep_acquire_chunked (ca_sweep_state_t *st);
+int  ca_sweep_next_chunk      (ca_sweep_state_t *st); /* 1 = chunk ready, 0 = done */
+void ca_sweep_release_chunked (ca_sweep_state_t *st);
+
+/* ===== Chunking helpers (extern-ified from carray_operator.c) ===== */
+ca_size_t ca_chunk_inner_size (CArray *ca);
+ca_size_t ca_chunk_compute_n  (ca_size_t total, ca_size_t inner,
+                               ca_size_t bytes_per_cell);
+void      ca_chunked_gather   (CArray *ca, ca_size_t off, ca_size_t n,
+                               void *dest);
+
+/* Arena pool (extern-ified earlier by lazy substrate; reused here). */
+extern void *ca_lazy_arena_acquire (ca_size_t bytes);
+extern void  ca_lazy_arena_release (void *ptr);
+
+#endif /* CA_SWEEP_ENGINE_H */

data/ext/ca_transform_common.c

@@ -0,0 +1,228 @@
+/* ---------------------------------------------------------------------------
+
+  Shared substrate for byte-level 1:1 value-transform views (CAFake /
+  CAByteSwap).  Implements the "compose to root + walk + transform in
+  flight" fast path used by xfer_stride (and indirectly by xfer_all via
+  thin-wrapper delegation).
+
+  Design and rationale: devel/PROPOSAL_TRANSFORM_FUSED_XFER.md.
+
+---------------------------------------------------------------------------- */
+
+#include "carray.h"
+#include "ca_iter_substrate.h"
+#include <string.h>
+
+/* CAStride compose helper (ca_obj_stride.c). */
+extern void ca_stride_compose_to_root (CAStride *leaf, CArray **out_root,
+                                        ca_size_t *out_strides,
+                                        ca_size_t *out_base);
+extern ca_operation_function_t ca_stride_func;
+
+/* ---------------------------------------------------------------------------
+   ca_xfer_stride_transform_fused
+
+   Walk parent's CAStride chain to its root (an entity with live ptr), then
+   for each inner row gather one strided run from root.ptr into a row scratch
+   in parent data_type and apply the per-view transform callback to write that
+   row to dst in view data_type.  No whole-view scratch, no ca_attach -- a true
+   1-pass fused walk for both GET and PUT.
+
+   PUT is symmetric to GET: cast dst (view data_type) into row scratch (parent
+   data_type) via xform_put, then scatter row scratch into root.ptr strided.
+
+   Eligibility (returns 0 = fail, caller falls back to its existing path):
+     - parent is in the CAStride family (= ca_func[].attach matches)
+     - ndim >= 1
+     - compose_to_root yields a root with live ptr (= entity / attached)
+
+   Mask: not consulted.  Post-xfer-reform data paths are mask-blind by
+   design; mask is propagated on a separate channel.  See
+   PROPOSAL_TRANSFORM_FUSED_XFER.md for the audit.
+
+   row scratch sizing: stack 16 KB first, ALLOCV (alloca-like) for larger.
+
+   Callers (= the two transform views that wire xform_get/_put):
+     - ext/ca_obj_fake.c       (CAFake; xform = type cast)
+     - ext/ca_obj_byte_swap.c  (CAByteSwap; xform = endian swap)
+   The ca_transform_row_fn callback contract is declared in
+   ext/ca_iter_substrate.h.
+--------------------------------------------------------------------------- */
+
+#define CA_TRANSFORM_ROW_STACK_BYTES 16384
+
+int
+ca_xfer_stride_transform_fused (CArray   *view,
+                                CArray   *parent,
+                                ca_size_t *starts,
+                                ca_size_t *counts,
+                                ca_size_t *strides,
+                                char     *data,
+                                int       dir,
+                                ca_transform_row_fn xform_get,
+                                ca_transform_row_fn xform_put)
+{
+  CArray   *root;
+  ca_size_t composed_strides[CA_RANK_MAX];
+  ca_size_t composed_base;
+  ca_size_t parent_bytes, view_bytes;
+  int8_t    ndim, k;
+  ca_size_t inner_count, inner_stride;
+  ca_size_t row_bytes;
+  char     *row_buf;
+  char      row_stack[CA_TRANSFORM_ROW_STACK_BYTES];
+  volatile VALUE holder = Qnil;
+  ca_size_t idx[CA_RANK_MAX];
+  ca_size_t outer_total, n, doff;
+
+  /* ---- Eligibility ---- */
+  if ( view->ndim < 1 ) return 0;
+  if ( dir != CA_XFER_GET && dir != CA_XFER_PUT ) return 0;
+
+  parent_bytes = parent->bytes;
+  view_bytes   = view->bytes;
+  ndim         = view->ndim;
+  /* CAREFUL: must use counts[ndim-1] (the sub-region width), not
+     view->dim[ndim-1] (the full view width).  Caller's data buffer is
+     sized for counts[], so a sub-region PUT through a CATranspose-of-
+     CAFake chain overflows the buffer if the full view dim is used. */
+  inner_count  = counts[ndim - 1];
+  if ( inner_count == 0 ) return 1;   /* trivially complete */
+
+  /* Compute view's natural row-major byte strides in view byte space. */
+  ca_size_t view_native[CA_RANK_MAX];
+  {
+    ca_size_t s = view_bytes;
+    for ( k = ndim - 1; k >= 0; k-- ) {
+      view_native[k] = s;
+      s *= view->dim[k];
+    }
+  }
+
+  ca_size_t eff_root_step[CA_RANK_MAX];
+
+  /* ---- Resolve parent's data source: two cases ---- */
+  if ( ca_func[parent->obj_type].attach == ca_stride_func.attach ) {
+    /* (A) CAStride family parent: compose stride chain down to root.
+       composed_strides[k] = root bytes per ONE view cell on axis k
+       (already accounts for parent's possibly-permuted layout).
+       Requires caller's strides to be natural multiples of view_native[]
+       so req_step is integer; otherwise fallback. */
+    ca_stride_compose_to_root((CAStride *)parent, &root,
+                              composed_strides, &composed_base);
+    if ( !root->ptr ) return 0;
+    if ( parent->bytes != root->bytes ) return 0;
+
+    for ( k = 0; k < ndim; k++ ) {
+      if ( view_native[k] == 0 ) return 0;
+      if ( strides[k] % view_native[k] != 0 ) return 0;  /* non-natural */
+      ca_size_t req_step = strides[k] / view_native[k];
+      composed_base    += starts[k] * composed_strides[k];
+      eff_root_step[k]  = req_step * composed_strides[k];
+    }
+  } else if ( parent->ptr ) {
+    /* (B) Non-CAStride parent with live ptr (= entity / attached view).
+       Parent has linear row-major byte layout: bytes scale uniformly with
+       cells via parent_bytes/view_bytes ratio (CAFake is 1:1 shape
+       preserving).  Use the universal "OLD CAFake" formula:
+         root byte step per axis-k iter = strides[k] * parent_bytes / view_bytes
+         root base contribution = starts[k] * parent_native[k]
+       This naturally handles transposed/sub-sampled caller strides. */
+    root = parent;
+    composed_base = 0;
+    if ( view_bytes == 0 ) return 0;
+    if ( parent_bytes % view_bytes != 0 && view_bytes % parent_bytes != 0 ) return 0;
+
+    ca_size_t parent_native[CA_RANK_MAX];
+    {
+      ca_size_t s = parent_bytes;
+      for ( k = parent->ndim - 1; k >= 0; k-- ) {
+        parent_native[k] = s;
+        s *= parent->dim[k];
+      }
+    }
+    for ( k = 0; k < ndim; k++ ) {
+      composed_base    += starts[k] * parent_native[k];
+      eff_root_step[k]  = strides[k] * parent_bytes / view_bytes;
+    }
+  } else {
+    /* Cold non-CAStride boundary (= CASelect etc. without ptr) -- fallback. */
+    return 0;
+  }
+
+  inner_stride = eff_root_step[ndim - 1];
+
+  /* When the inner row is contig in root (= inner_stride == parent_bytes),
+     the scratch gather/scatter is redundant -- xform_get/_put can read or
+     write root->ptr+soff directly, saving the row_buf allocation and one
+     of the two memory passes per outer row.  Transposed access through
+     CATranspose-of-CAFake has inner_stride != parent_bytes and falls
+     through to the scratch+gather path.  See
+     PROPOSAL_XFER_STRIDE_PER_REGION_GAPS.md. */
+  int inner_contig = (inner_stride == parent_bytes);
+
+  /* A 2D tile-cache + bulk-cast variant of this loop was explored and
+     reverted: the existing per-row walker already streams source through
+     L2/L3, and the tile path loses to per-call cast dispatch overhead
+     and an extra untranspose pass.  See
+     PROPOSAL_TRANSFORM_FUSED_XFER.md for the rejected-direction record.
+     A typed (src,dst)-specialised inner loop is the next candidate. */
+
+  /* ---- Row scratch (parent data_type, inner_count cells) ----
+     Skipped when inner_contig is true (= every outer iter uses the
+     direct fast path below). */
+  row_bytes = inner_count * parent_bytes;
+  row_buf   = NULL;
+  if ( !inner_contig ) {
+    if ( row_bytes <= (ca_size_t)CA_TRANSFORM_ROW_STACK_BYTES ) {
+      row_buf = row_stack;
+    } else {
+      row_buf = ALLOCV_N(char, holder, row_bytes);
+    }
+  }
+
+  /* ---- Walk outer (ndim-1) axes on odometer ---- */
+  outer_total = 1;
+  for ( k = 0; k < ndim - 1; k++ ) outer_total *= counts[k];
+  for ( k = 0; k < ndim - 1; k++ ) idx[k] = 0;
+  doff = 0;
+
+  for ( n = 0; n < outer_total; n++ ) {
+    /* Outer offset into root for this inner row. */
+    ca_size_t soff = composed_base;
+    for ( k = 0; k < ndim - 1; k++ ) soff += idx[k] * eff_root_step[k];
+
+    if ( inner_contig ) {
+      /* Inner-row contig in root; no scratch needed. */
+      if ( dir == CA_XFER_GET ) {
+        xform_get(inner_count, parent, root->ptr + soff,
+                  view, data + doff);
+      } else {
+        xform_put(inner_count, view, data + doff,
+                  parent, root->ptr + soff);
+      }
+    } else if ( dir == CA_XFER_GET ) {
+      /* root.ptr+soff strided -> row_buf contig (parent data_type). */
+      ca_stride_gather_run(row_buf, root->ptr + soff,
+                           parent_bytes, inner_count, inner_stride);
+      /* row_buf (parent data_type) -> data+doff (view data_type). */
+      xform_get(inner_count, parent, row_buf, view, data + doff);
+    } else {
+      /* data+doff (view data_type) -> row_buf contig (parent data_type). */
+      xform_put(inner_count, view, data + doff, parent, row_buf);
+      /* row_buf contig -> root.ptr+soff strided (parent data_type). */
+      ca_stride_scatter_run(root->ptr + soff, row_buf,
+                            parent_bytes, inner_count, inner_stride);
+    }
+    doff += inner_count * view_bytes;
+
+    /* Odometer advance over the outer (ndim-1) axes. */
+    if ( ndim < 2 ) break;
+    k = ndim - 2;
+    while ( k >= 0 ) { if ( ++idx[k] < counts[k] ) break; idx[k] = 0; k--; }
+    if ( k < 0 ) break;
+  }
+
+  if ( holder != Qnil ) ALLOCV_END(holder);
+  return 1;
+}

data/ext/ca_triop_dispatch.c

@@ -0,0 +1,55 @@
+/* ---------------------------------------------------------------------------
+
+  CATriOp dispatch: routes a triop op id (`CA_TRIOP_*`) to the per-
+  data_type kernel and computes the 3-way promotion.
+
+  Sibling of ca_binop_dispatch.c (binary counterpart) and
+  ca_obj_triop.c (the CATriOp view).  Per-data_type kernel tables
+  are declared in ca_triop_dispatch.h.
+
+  All 3 operands are cast to the common promoted data_type before the
+  kernel runs (cast-before invariant, same as CABinOp).  Output data_type
+  is the common promoted data_type.
+
+---------------------------------------------------------------------------- */
+
+#include "carray.h"
+#include "ca_triop_dispatch.h"
+
+/* ------------------------------------------------------------------- */
+/* vvv kernel lookup                                                    */
+/* ------------------------------------------------------------------- */
+
+ca_triop_func_t
+ca_triop_kernel_lookup_vvv (uint16_t op_id, int8_t common_dt)
+{
+  switch (op_id) {
+    case CA_TRIOP_FMA:  return ca_triop_fma  [common_dt];
+    case CA_TRIOP_FMS:  return ca_triop_fms  [common_dt];
+    case CA_TRIOP_CLIP: return ca_triop_clip [common_dt];
+    default:            return NULL;
+  }
+}
+
+/* ------------------------------------------------------------------- */
+/* 3-way promotion                                                      */
+/* ------------------------------------------------------------------- */
+
+int8_t
+ca_lazy_promote_triop (uint16_t op_id, int8_t dt1, int8_t dt2, int8_t dt3)
+{
+  (void) op_id;   /* uniform 3-way promote across all currently-defined triops */
+  return (int8_t) ca_promote_type(ca_promote_type(dt1, dt2), dt3);
+}
+
+void
+ca_triop_kernel_input_data_types (uint16_t op_id,
+                                  int8_t dt1, int8_t dt2, int8_t dt3,
+                                  int8_t *out_dt1, int8_t *out_dt2,
+                                  int8_t *out_dt3)
+{
+  int8_t common = ca_lazy_promote_triop(op_id, dt1, dt2, dt3);
+  if ( out_dt1 ) *out_dt1 = common;
+  if ( out_dt2 ) *out_dt2 = common;
+  if ( out_dt3 ) *out_dt3 = common;
+}

data/ext/ca_triop_dispatch.h

@@ -0,0 +1,62 @@
+/* ---------------------------------------------------------------------------
+
+  ca_triop_dispatch.h
+
+  CATriOp dispatch API — sibling of ca_binop_dispatch.h.  Routes a
+  triop op id (`CA_TRIOP_*`) to the per-data_type kernel and computes
+  the 3-way input promotion.
+
+  Kernel signature: fn(n, mask, src1, i1, src2, i2, src3, i3, dst, i4)
+  All 3 operands are cast to the common data_type before the kernel
+  runs (cast-before invariant, mirrors CABinOp).  Output data_type is
+  always the common data_type (preserve).
+
+  Scope: fma / fms / clip (see ext/mkkernel.rb :fma / :fms / :clip).
+  None of the currently-defined triops trap on integer zero divisor.
+
+---------------------------------------------------------------------------- */
+
+#ifndef CA_TRIOP_DISPATCH_H
+#define CA_TRIOP_DISPATCH_H
+
+#include "carray.h"
+
+/* ------------------------------------------------------------------- */
+/* op_id enum                                                           */
+/* ------------------------------------------------------------------- */
+
+enum {
+  CA_TRIOP_FMA  = 0,   /* a * b + c  (single-rounding on float)     */
+  CA_TRIOP_FMS  = 1,   /* a * b - c  (single-rounding on float)     */
+  CA_TRIOP_CLIP = 2,   /* min(max(a, lo), hi), NaN-preserving        */
+
+  CA_TRIOP_COUNT
+};
+
+/* ------------------------------------------------------------------- */
+/* Kernel dispatch tables (per-data_type)                               */
+/* ------------------------------------------------------------------- */
+
+extern ca_triop_func_t ca_triop_fma        [CA_NTYPE];
+extern ca_triop_func_t ca_triop_fms        [CA_NTYPE];
+extern ca_triop_func_t ca_triop_clip       [CA_NTYPE];
+
+/* ------------------------------------------------------------------- */
+/* Dispatch API                                                         */
+/* ------------------------------------------------------------------- */
+
+/* Look up the triop kernel for (op_id, common_dt).  Returns NULL if
+   not implemented at the requested data_type. */
+ca_triop_func_t ca_triop_kernel_lookup_vvv (uint16_t op_id, int8_t common_dt);
+
+/* 3-way promotion: common data_type of (dt1, dt2, dt3).                 */
+int8_t ca_lazy_promote_triop (uint16_t op_id, int8_t dt1, int8_t dt2, int8_t dt3);
+
+/* Each operand's cast-target data_type (= common data_type for all three,
+   the cast-before invariant).                                           */
+void ca_triop_kernel_input_data_types (uint16_t op_id,
+                                       int8_t dt1, int8_t dt2, int8_t dt3,
+                                       int8_t *out_dt1, int8_t *out_dt2,
+                                       int8_t *out_dt3);
+
+#endif /* CA_TRIOP_DISPATCH_H */