carray 3.0.2 → 3.0.4

data/ext/carray.h

@@ -347,14 +347,12 @@ typedef struct {
   void   (*detach)       (void *ap);
   void   (*fill_data)    (void *ap, void *data);
   void   (*create_mask)  (void *ap);
-  /* xfer protocol.  Added at struct end so existing
-     positional initializers leave it NULL automatically.  dir = CA_XFER_GET /
-     CA_XFER_PUT. */
+  /* xfer protocol.  dir = CA_XFER_GET / CA_XFER_PUT. */
   void   (*xfer_index)   (void *ap, ca_size_t *idx, void *data, int dir);
   void   (*xfer_addrs)   (void *ap, ca_size_t n, ca_size_t *addrs,
                           void *data, int dir);
-  /* fold_stride: one compose-fold hop
-     for sometimes-fold participants (CAWindow now; CAGrid/CSA/CATile later).
+  /* fold_stride: one compose-fold hop for the views that fold only
+     sometimes (CAWindow, CAGrid, CASelectAxis, CAStack, CAMeld).
      Compose *f into next_parent's byte space and return 1, or decline
      (leave *f / *next_parent untouched) and return 0 -> this view is the
      fold boundary.  CAStride family leaves this NULL (handled open-inline
@@ -637,6 +635,13 @@ typedef struct {
                                        (count[k] == parent->dim[k] && start[k]
                                        == 0 for k >= 1).  Embedded region
                                        must be contig in parent storage. */
+  /* A window over a parent that has no mask: the all-false mask its own
+     mask reads instead, so that masking the out-of-bounds cells gives the
+     parent no mask.  Owned by this window; NULL otherwise. */
+  CArray     *mask_standin;
+  /* On the mask of a window: the window whose mask it is, which holds the
+     stand-in and the parent whose mask replaces it.  NULL otherwise. */
+  CArray     *mask_owner;
 } CAWindow;                /* 56 + 16*(ndim) + 1*(bytes) + 1*ndim + 24*ndim (bytes) */
 
 /* CAShift is a pure typedef of CAWindow.  CAShift construction maps (shift[], roll[], fill,
@@ -681,17 +686,17 @@ typedef struct {
                               dim[k] = parent->dim[k] * reps[k]. */
 } CATile;                /* 56 + 8*(ndim) (bytes) */
 
-typedef CATile CARoll;   /* T.4 will land CARoll-specific constructor +
-                            obj_type CA_OBJ_ROLL.  Until then CARoll path
-                            is just CATile (= typedef body identical). */
+typedef CATile CARoll;   /* same layout as CATile, its own obj_type
+                            CA_OBJ_ROLL (ext/ca_obj_roll.c) */
 
-/* CAStack: outer-axis-only stack view of K uniform-shape parents.  shape = (K, *parent_shape),
-   axis 0 maps to parent index, axes 1..ndim-1 are per-parent contig.
+/* CAStack: stack view of K uniform-shape parents.  The K axis sits at
+   k_axis in the view's shape (0 by default: shape = (K, *parent_shape));
+   the other axes are the parents' own.
    - parents stored as Ruby Array @parents on the wrapper object (= GC
      anchor); C-side tail `parents[]` is alias pointer array.
    - CAView.parent points to parents[0] (= legacy compat for paths that
      deref ca->parent without CAStack awareness).
-   - dim[0] = n_parents; dim[1..ndim-1] = parents[0]->dim[0..ndim-2]. */
+   - dim[k_axis] = n_parents; the other dims are parents[0]->dim in order. */
 typedef struct {
   int16_t   obj_type;
   int8_t    data_type;
@@ -699,7 +704,7 @@ typedef struct {
   int32_t   flags;
   ca_size_t bytes;
   ca_size_t elements;      /* = n_parents * parents[0]->elements */
-  ca_size_t *dim;          /* ALLOC_N(ndim) = [n_parents, *parent->dim] */
+  ca_size_t *dim;          /* ALLOC_N(ndim): parent->dim with n_parents at k_axis */
   char     *ptr;
   CArray   *mask;
   char     *_pool;         /* framework-managed pool buffer (NULL = legacy ALLOC_N path).
@@ -716,6 +721,12 @@ typedef struct {
                               0 = outer-axis stack (legacy default).
                               parent_ndim = K innermost (= old merge at=-1).
                               Set by ca_stack_setup_with_axis / preserved on clone. */
+  CArray  **mask_standins; /* NULL, or ALLOC_N(CArray*, n_parents) once the mask is
+                              built: the all-false masks standing in for parents that
+                              have none (owned, freed with the view) */
+  CArray   *mask_owner;    /* on the mask of a CAStack: that CAStack, whose stand-ins
+                              this mask reads until they give way to the parents'
+                              own masks (ca_multi_parent_mask_refresh); else NULL */
 } CAStack;
 
 /* CAMeld (ragged concatenate view along an existing axis).  Unlike CAStack
@@ -725,8 +736,7 @@ typedef struct {
      shape[meld_axis] = sum_k parents[k]->dim[meld_axis]
    All other axes must match across parents (uniform check at constructor).
 
-   v0.1 stub: external-axis (meld_axis == 0) structural xfer_stride path only.
-   Other paths raise NotImplementedError. */
+   meld_axis may be any axis. */
 typedef struct {
   int16_t   obj_type;
   int8_t    data_type;
@@ -749,6 +759,8 @@ typedef struct {
   ca_size_t *seg_offset;   /* ALLOC_N(ca_size_t, K+1); prefix sum along meld_axis.
                               seg_offset[0]=0, seg_offset[k+1]=seg_offset[k]+parents[k]->dim[meld_axis],
                               seg_offset[K]=dim[meld_axis]. */
+  CArray  **mask_standins; /* as CAStack's: stand-in masks this view owns, or NULL */
+  CArray   *mask_owner;    /* as CAStack's */
 } CAMeld;
 
 /* Multi-parent view layout convention (CA_FLAG_MULTI_PARENTS).  A view that
@@ -786,9 +798,14 @@ typedef struct {
   VALUE     self;
 } CAObject;                /* 48 + 4*(ndim) (bytes) */
 
-/* 
-  CAObjectMask is an internal class 
-  used only as mask array of CAObject.
+/*
+  CAObjectMask is an internal class used only as the mask array of a
+  CAObject.  Its bits live in the CAObject's mask hooks (mask_copy_data,
+  mask_fetch_addr, ...) when it has them, and in `cache` -- the mask
+  buffer of the CAObject's internal data array -- always.  Like the mask
+  of any view it is cold at rest: ptr is NULL, and every read and write
+  goes through its slots to the hooks.  An attach publishes the cache in
+  ptr, and `holds` counts the attaches not yet detached.
 */
 
 typedef struct {
@@ -807,6 +824,8 @@ typedef struct {
                               ext/ca_array_pool.c. */
   /* -------------*/
   VALUE     array;
+  char     *cache;
+  long      holds;
 } CAObjectMask;
 
 /* CARepeat (Phase R migration): structurally identical to CAStride.
@@ -854,16 +873,19 @@ extern const char *  ca_type_name[CA_NTYPE];
 extern const int ca_cast_table[CA_NTYPE][CA_NTYPE];
 extern const int ca_cast_table2[CA_NTYPE][CA_NTYPE];
 
-/* data_type promotion reducer — pure function over ca_cast_table.  Used by
-   CArray.result_type and by the lazy view layer.  See ext/carray_cast.c
+/* data_type promotion reducer over ca_cast_table.  Used by
+   CArray.result_type and by the lazy view layer.  Raises ArgumentError for
+   a code outside the data types, and CArray::DataTypeError for a pair with
+   no common type.  See ext/carray_cast.c
    for the definition; this is the single source of the promotion rule. */
 int8_t ca_promote_type (int8_t a, int8_t b);
 
 /* Infer a data_type code from a Ruby *value* (literal Numeric, true/false,
    Complex, etc.) — distinct from rb_ca_guess_type which interprets the
    object as a data_type *representation* (e.g. T_FIXNUM as a data_type code).
-   Used by then_else and by ca_lazy_wrap_scalar's bool-self corner case.
-   CArray is not accepted (callers should use ca->data_type directly). */
+   Used by rb_ca_cast_self_or_other.
+   A CArray, like any object it does not recognise, answers CA_OBJECT;
+   callers holding a CArray use ca->data_type. */
 int8_t ca_value_to_data_type (VALUE obj);
 
 /* Infer a data_type code from a MemoryView producer by parsing its format,
@@ -915,8 +937,6 @@ extern const rb_data_type_t cabyteswap_data_type;
 /* cafield_data_type was retired in 3.0 (Phase F: CAField is now a
    CAStride subclass; use castride_data_type). */
 extern const rb_data_type_t cagrid_data_type;
-/* camapping_data_type was retired in 3.0 (R.3: CAMapping removed; a[mapper]
-   now builds a CAGrid/CAStride normalize chain). */
 extern const rb_data_type_t caobject_data_type;
 extern const rb_data_type_t careduce_data_type;
 extern const rb_data_type_t carefer_data_type;
@@ -927,7 +947,6 @@ extern const rb_data_type_t cawindow_data_type;
 extern const rb_data_type_t carray_mask_data_type;
 extern const rb_data_type_t cablock_mask_data_type;
 extern const rb_data_type_t cagrid_mask_data_type;
-extern const rb_data_type_t camapping_mask_data_type;
 extern const rb_data_type_t careduce_mask_data_type;
 extern const rb_data_type_t carefer_mask_data_type;
 extern const rb_data_type_t caselect_mask_data_type;
@@ -984,67 +1003,78 @@ extern VALUE rb_cCArrayObject;
 
 #define CA_CHECK_DATA_TYPE(data_type) \
   do { \
-    if ( data_type <= CA_NONE || data_type >= CA_NTYPE ) { \
-      rb_raise(rb_eRuntimeError, "invalid data_type id %i", data_type);     \
+    int ca_dt_ = (data_type); \
+    if ( ca_dt_ <= CA_NONE || ca_dt_ >= CA_NTYPE ) { \
+      rb_raise(rb_eArgError, "invalid data_type id %i", ca_dt_);     \
     } \
-    if ( ! ca_valid[data_type] ) { \
-      rb_raise(rb_eRuntimeError, "data_type %s is disabled", ca_type_name[data_type]);    \
+    if ( ! ca_valid[ca_dt_] ) { \
+      rb_raise(rb_eCADataTypeError, "data_type %s is disabled", ca_type_name[ca_dt_]);    \
     } \
   } while (0)
 
 #define CA_CHECK_DATA_TYPE_NUMERIC(data_type) \
-  if ( data_type <= CA_NONE || data_type >= CA_NTYPE || !ca_valid[data_type] || data_type == CA_FIXLEN || data_type == CA_OBJECT ) { \
-    rb_raise(rb_eRuntimeError, "invalid numeric data type"); \
-  }
+  do { \
+    int ca_dt_ = (data_type); \
+    if ( ca_dt_ <= CA_NONE || ca_dt_ >= CA_NTYPE || !ca_valid[ca_dt_] || \
+         ca_dt_ == CA_FIXLEN || ca_dt_ == CA_OBJECT ) { \
+      rb_raise(rb_eCADataTypeError, "invalid numeric data type"); \
+    } \
+  } while (0)
 
 #define CA_CHECK_RANK(ndim) \
-  if ( ndim <= 0 || ndim > CA_RANK_MAX ) { \
-    rb_raise(rb_eRuntimeError, "invalid ndim"); \
-  }
+  do { \
+    if ( (ndim) <= 0 || (ndim) > CA_RANK_MAX ) { \
+      rb_raise(rb_eArgError, "invalid ndim"); \
+    } \
+  } while (0)
 
 #define CA_CHECK_DIM(ndim, dim)     \
-  { \
+  do { \
     int8_t i_; \
-    for (i_=0; i_<ndim; i_++) { \
-      if ( dim[i_] < 0 ) { \
-        rb_raise(rb_eRuntimeError, "negative size dimension at %i-dim", i_);  \
+    for (i_=0; i_<(ndim); i_++) { \
+      if ( (dim)[i_] < 0 ) { \
+        rb_raise(rb_eArgError, "negative size dimension at %i-dim", i_);  \
       } \
     } \
-  }
+  } while (0)
 
+/* A fixlen cell is at least one byte wide.  A zero-width cell has one
+   possible value, and a strided view of it cannot say which cell is which:
+   its byte strides are all zero. */
 #define CA_CHECK_BYTES(data_type, bytes) \
-  if ( data_type == CA_FIXLEN ) { \
-    if ( bytes < 0 ) {                             \
-      rb_raise(rb_eRuntimeError, "invalid bytes"); \
+  do { \
+    if ( (data_type) == CA_FIXLEN ) { \
+      if ( (bytes) <= 0 ) {                            \
+        rb_raise(rb_eArgError,                   \
+                 "invalid bytes (a fixlen needs bytes: of 1 or more)"); \
+      } \
     } \
-  } \
-  else { \
-    bytes = ca_sizeof[data_type]; \
-    if ( bytes <= 0 ) {           \
-      rb_raise(rb_eRuntimeError, "invalid bytes"); \
+    else { \
+      (bytes) = ca_sizeof[(data_type)]; \
+      if ( (bytes) <= 0 ) {           \
+        rb_raise(rb_eArgError, "invalid bytes"); \
+      } \
     } \
-  }
+  } while (0)
+
+/* An index into `n` places, counted from the end when negative, outside of
+   which IndexError is raised naming the method the user called, `what` the
+   index is ("index", "address") and the value given. */
+NORETURN(void ca_index_out_of_range (ca_size_t idx, ca_size_t n, const char *what));
 
+/* Normalise `index` in place against `dim` (a negative one counts from the
+   end) and raise through ca_index_out_of_range when it falls outside. */
 #define CA_CHECK_INDEX(index, dim) \
   do { \
-    if ( index < 0 ) {       \
-      index += (dim);     \
+    ca_size_t ca_check_index_given_ = (index); \
+    if ( (index) < 0 ) {       \
+      (index) += (dim);     \
     } \
-    if ( index < 0 || index >= (dim) ) { \
-      rb_raise(rb_eIndexError, "index out of range ( %" PRId64 " <=> 0..%" PRId64 " )", (int64_t) index, (int64_t) dim-1); \
+    if ( (index) < 0 || (index) >= (dim) ) { \
+      ca_index_out_of_range(ca_check_index_given_, (dim), "index"); \
     } \
   } while (0)
 
-#define CA_CHECK_BOUND(ca, idx) \
-  { \
-    int8_t i; \
-    for (i=0; i<ca->ndim; i++) { \
-      if ( idx[i] < 0 || idx[i] >= ca->dim[i] )  { \
-        rb_raise(rb_eRuntimeError, "index out of range at %i-dim ( %i <=> 0..%i )", i, idx[i], ca->dim[i]-1); \
-      } \
-    } \
-  }
-
 /* -------------------------------------------------------------------- */
 
 /* complex <-> Ruby Complex conversion
@@ -1070,6 +1100,10 @@ extern VALUE rb_cCArrayObject;
 #  endif
 #endif
 
+/* A string as a complex cell: a real number read as Float() reads it
+   (nan / inf included), else as Complex() does; anything else raises. */
+double complex ca_str_to_cmplx (VALUE str);
+
 static inline double complex
 rb_carray_num2cmplx (VALUE num)
 {
@@ -1079,8 +1113,18 @@ rb_carray_num2cmplx (VALUE num)
   if ( RB_FLOAT_TYPE_P(num) || RB_INTEGER_TYPE_P(num) ) {
     return (double complex) NUM2DBL(num);
   }
+  if ( RB_TYPE_P(num, T_STRING) ) {
+    return ca_str_to_cmplx(num);
+  }
+  if ( NIL_P(num) ) {
+    rb_raise(rb_eTypeError, "can't convert nil into Complex");
+  }
   if ( rb_respond_to(num, rb_intern("to_c")) ) {
     VALUE c = rb_funcall(num, rb_intern("to_c"), 0);
+    if ( ! RB_TYPE_P(c, T_COMPLEX) ) {
+      rb_raise(rb_eTypeError, "can't convert %"PRIsVALUE" to Complex (%"PRIsVALUE"#to_c gives %"PRIsVALUE")",
+               rb_obj_class(num), rb_obj_class(num), rb_obj_class(c));
+    }
     return CMPLX(NUM2DBL(rb_complex_real(c)), NUM2DBL(rb_complex_imag(c)));
   }
   if ( rb_respond_to(num, rb_intern("to_f")) ) {
@@ -1125,6 +1169,7 @@ double    OBJ2DBL (VALUE v);
    object->int/float cast loop so an unparseable cell becomes UNDEF instead
    of a silent 0.0 (float) or a raise (int).  See ext/carray_cast.c. */
 int   ca_obj2dbl_ok   (VALUE v, double *out);
+int   ca_obj2cmplx_ok (VALUE v, double complex *out);
 int   rb_obj2long_ok  (VALUE v, long *out);
 int   rb_obj2ulong_ok (VALUE v, unsigned long *out);
 int   rb_obj2ll_ok    (VALUE v, long long *out);
@@ -1156,8 +1201,7 @@ enum {
   CA_IDX_SCALAR,
   CA_IDX_ALL,
   CA_IDX_BLOCK,
-  CA_IDX_SYMBOL,
-  CA_IDX_REPEAT
+  CA_IDX_SYMBOL
 }; /* CA_INDEX_TYPE */
 
 typedef union {
@@ -1226,14 +1270,14 @@ VALUE    rb_carray_new_safe (int8_t data_type,
    already hold a freshly decoded buffer and want to avoid a copy.  The
    buffer must be ruby_xmalloc()'d and at least elements*bytes long; it
    is freed with xfree() when the array is collected.  data_type must not
-   be CA_OBJECT. */
+   be CA_OBJECT.  When the call raises (a bad argument), the buffer stays
+   the caller's. */
 CArray  *carray_new_adopt (int8_t data_type,
                            int8_t ndim, ca_size_t *dim, ca_size_t bytes, char *ptr);
 VALUE    rb_carray_new_adopt (int8_t data_type,
                               int8_t ndim, ca_size_t *dim, ca_size_t bytes, char *ptr);
 
-/* Capstone helper: allocate
-   a reduction-output CArray for kernel_iterator authors.  Computes
+/* Allocate a reduction-output CArray for kernel_iterator authors.  Computes
    output shape = self.dim with slab axes removed (ascending order),
    collapses to shape [1] when fully reduced.  See
    ext/carray_core.c for docstring + semantics. */
@@ -1244,10 +1288,10 @@ VALUE    rb_ca_new_reduced (VALUE self, int8_t *slab_axes,
 VALUE    rb_ca_new_reduced_bytes (VALUE self, int8_t *slab_axes, int8_t naxes,
                                   int32_t data_type, ca_size_t bytes, int keep_axis);
 
-/* Capstone helper: parse
-   variadic axis argv into validated int8_t array.  Accepts Integer
-   args or a single Array arg, normalises negative axes (Python-style),
-   range / duplicate / overflow checks all raise ArgumentError.
+/* Parse variadic axis argv into a validated int8_t array.  Accepts Integer
+   args or a single Array arg (no argument = every axis), counts negative
+   axes from the end, and raises ArgumentError for an axis out of range or
+   given twice.
    Returns the validated naxes. */
 int8_t   rb_ca_parse_reduce_axes (int argc, VALUE *argv,
                                   CArray *ca, int8_t *out_axes);
@@ -1293,6 +1337,14 @@ VALUE    rb_ca_farray (VALUE self);
 
 /* --- ca_obj_stride.c --- */
 
+/* The strides and base_offset are taken as given: they are not checked
+   against the parent's extent, so a view that reaches outside it reads
+   and writes outside it.
+
+   ca_stride_setup with ca == NULL runs its checks and returns 0 without
+   writing.  ca_stride_new calls it that way before it allocates, so a
+   rejected argument leaves no struct behind; a subclass constructor can
+   do the same through its own setup function. */
 int       ca_stride_setup (CAStride *ca, int8_t obj_type, CArray *parent,
                            int8_t data_type, ca_size_t bytes,
                            int8_t ndim, ca_size_t *dim,
@@ -1362,8 +1414,16 @@ void    ca_broadcast_pair (volatile VALUE *self, volatile VALUE *other);
      ca_install_obj_type(klass, &td, mask_klass, &mask_td,
                          &my_func, sizeof(my_func));
 
+   The table must reach at least through xfer_all: xfer_index, xfer_addrs
+   and xfer_all have no default.  fold_stride may be NULL (the view is a
+   fold boundary); xfer_stride, the pool slots, fill_addrs and fill_stride
+   fall back to a default when NULL.  A shorter table raises RuntimeError.
    A func_size larger than this build's struct means the caller was compiled
-   against a newer carray; that is reported rather than truncated. */
+   against a newer carray; that is reported rather than truncated.
+
+   The obj_type parameters of ca_array_alloc, ca_array_pool_alloc,
+   ca_stride_setup and ca_stride_new are int8_t, so an obj_type is numbered
+   below 128: an install that would number one at 128 or above raises. */
 
 int
 ca_install_obj_type (VALUE klass,
@@ -1430,19 +1490,24 @@ int     ca_is_mask_array (void *ap);
 #define GetCArray(obj, ca) \
     TypedData_Get_Struct((obj), CArray, &carray_data_type, (ca))
 
-/* True iff ca_attach(ca) is essentially O(1) — entity arrays (already
-   attached), CAWrap, CScalar, and CAStride-family views whose composed
-   strides are row-major contiguous (alias-attach path).  Used by
-   kernel_iterator's L1 alias decision (ca_iter_can_alias level 1) and
-   by overlay-view dispatch.  The name says the structural property
-   (= aliasable without materialise), not the perf characteristic. */
+/* True when ca_attach(ca) gives ca->ptr the cells in place, without
+   materialising: entity arrays, CAWrap, CScalar, and CAStride-family
+   views whose composed strides are row-major contiguous over an attached
+   root (alias-attach path).  It is not the same as "attach is O(1)": a
+   Face attaches in O(1) by borrowing its parent and answers false, and a
+   CASource entity that publishes its ptr only while attached answers
+   true.  Used by the kernel iterator's alias decision, the sweep engine,
+   and the views and mask paths that skip a sync when nothing was copied. */
 int     ca_attach_is_alias (void *ap);
 
 /* OR operand masks into
    ca_out->mask without ca_attach on operand masks (= gathers via
-   ca_xfer_all into arena scratch then byte OR-folds).  ca_out must be
-   a freshly templated entity.  For bang variant where ca_out IS one of
-   the operands, the existing mask is preserved as initial accumulator. */
+   ca_xfer_all into arena scratch then byte OR-folds).  ca_out's mask is
+   written through its ptr, so ca_out is an entity or an attached view.
+   Each operand other than a scalar has ca_out's number of elements
+   (ArgumentError otherwise); n is at most 8.  For bang variant where
+   ca_out IS one of the operands, the existing mask is preserved as
+   initial accumulator. */
 void    ca_mask_overlay_safe (CArray *ca_out, int n, ...);
 
 #define ca_is_caobject(ca) ( (ca)->obj_type == CA_OBJ_OBJECT )
@@ -1459,6 +1524,7 @@ int     ca_is_object_type (void *ap);
 
 void    ca_check_type (void *ap, int8_t data_type);
 #define ca_check_data_type(ap, data_type) ca_check_type(ap, data_type)
+void    ca_check_uninitialized (void *ap);  /* initialize / initialize_copy entry */
 void    ca_check_ndim (void *ap, int ndim);
 void    ca_check_shape (void *ap, int ndim, ca_size_t *dim);
 void    ca_check_same_data_type (void *ap1, void *ap2);
@@ -1474,7 +1540,7 @@ int     ca_is_valid_index (void *ap, ca_size_t *idx);
 
 /* API : allocate, attach, update, sync, detach */
 
-/* Attach lifecycle contract (R1-R5).  Ownership-based, and NOT transitive.
+/* Attach lifecycle contract (R1-R6).  Ownership-based, and NOT transitive.
    This block is the canonical statement of the contract; the other documents
    copy it.  guides/devel/04_attach_lifecycle.md discusses it at length.
 
@@ -1491,15 +1557,34 @@ int     ca_is_valid_index (void *ap, ca_size_t *idx);
                      internally (views carry an attach refcount; entities do
                      not).
      R5 (traffic)    Attach hands you a buffer, not a live array.  Use x->ptr;
-                     a view derived from x composes past the buffer to the
-                     root.
+                     a view derived from x may read past the buffer to the
+                     root (a CAStride-family view over a CAStride-family x
+                     does) or read the buffer (others), so writes to the
+                     buffer are not seen through derived views until x is
+                     synced.
+     R6 (raising)    ca_allocate and ca_attach that raise have taken
+                     nothing; ca_allocate_n and ca_attach_n take all of
+                     their arrays or none.  Close a window with
+                     ca_sync_detach, which detaches even when the sync
+                     raises -- ca_sync then ca_detach leaves the window open
+                     on a raise.  ca_sync_detach syncs, so it raises on a
+                     read-only array; a window that only read closes with
+                     ca_detach.  Anything between that can raise (Ruby
+                     called from inside the window) needs an ensure of its
+                     own.
 */
 
+/* ca_allocate opens a window for writing every cell: what the cells held
+   before is not kept, also when the array is already attached (object cells
+   are reset to 0 and the mask is cleared). */
 void    ca_allocate (void *ap);
 void    ca_attach (void *ca);
+/* Re-gather an attached view's buffer from its parent (one level: a parent
+   that holds its own buffer is read as it is). */
 void    ca_update (void *ca);
 void    ca_sync (void *ca);
 void    ca_detach (void *ca);
+void    ca_sync_detach (void *ca);
 
 void    ca_allocate_n (int n, ...);
 void    ca_attach_n (int n, ...);
@@ -1507,17 +1592,70 @@ void    ca_update_n (int n, ...);
 void    ca_sync_n (int n, ...);
 void    ca_detach_n (int n, ...);
 
+/* API : lending the addresses of cells
+
+   A kernel that reads cells by address itself -- a stencil reading
+   a[i-1][j] and a[i+1][j] from its own loop -- needs, for each array, a
+   pointer to cell (0, ..., 0) and the byte distance between neighbours
+   along each axis.  ca_with_address_bases lends that for the duration of
+   `body`, whatever the arrays are, and puts back what the kernel wrote:
+
+     - an entity, or a view the engine can fold down to one (a slice, a
+       transpose, a reshape), is addressed in place;
+     - any other view (a selection, a conversion, a lazy expression) has
+       the cells the kernel touches copied into a buffer, which is lent
+       instead and, for a writable array, sent back afterwards: only the
+       cells the kernel changed, through the view.
+
+   `box_start[i]` / `box_count[i]` (ndim values each) say which cells
+   array i's kernel touches -- its loop range, widened by how far the
+   kernel reaches (one cell each way for a[i-1] .. a[i+1]).  They decide
+   what the second case copies; the first case lends the whole array
+   either way.  Pass NULL for `box_start` and `box_count` (or for an
+   entry of them) to lend the whole array.  A box outside the array is
+   refused.  Address only the box, whichever way the array was lent.
+
+   `writable[i]` says whether the kernel writes array i (NULL: none is
+   written); a read-only array is refused for writing.  An object array
+   is refused (its cells are Ruby values, not numbers), and so is a view
+   with a mask that reinterprets the element size (its mask cells do not
+   map one to one onto the parent's).
+
+   A masked array also lends its mask: one boolean8_t per cell (nonzero =
+   masked), addressed with mask_strides the same way.  A write to the
+   mask is put back like a write to a cell.  `mask` is NULL for an array
+   with no mask.
+
+   `body` may raise: the arrays are still written back and closed.
+   Returns what `body` returns.  The CArray pointers must stay alive for
+   the call (keep the VALUEs they came from). */
+typedef struct {
+  char       *ptr;                        /* cell (0, ..., 0) */
+  ca_size_t   strides[CA_RANK_MAX];       /* byte step along each axis */
+  boolean8_t *mask;                       /* NULL when no mask */
+  ca_size_t   mask_strides[CA_RANK_MAX];  /* byte step in the mask */
+  int         writable;
+} ca_address_basis_t;
+
+VALUE   ca_with_address_bases (int32_t n, CArray **arrays, const int *writable,
+                               const ca_size_t *const *box_start,
+                               const ca_size_t *const *box_count,
+                               VALUE (*body)(ca_address_basis_t *bases,
+                                             VALUE arg),
+                               VALUE arg);
+
 /* API : copying */
 
 void   *ca_clone (void *ap);          /* use rb_obj_clone() */
+/* A CA_OBJECT copy holds VALUEs the GC does not see until the struct is
+   wrapped, and wrapping allocates: for an object array use rb_ca_copy, which
+   keeps them alive and returns the wrapped copy. */
 CArray *ca_copy (void *ap);           /* use rb_ca_copy() */
 CArray *ca_template (void *ap);       /* use rb_ca_template() */
 CArray *ca_template_safe (void *ap);  /* use rb_ca_template() */
 CArray *ca_template_safe2 (void *ap, int8_t data_type, ca_size_t bytes);
                                       /* use rb_ca_template() */
 
-/* ca_paste / ca_clip / ca_cut (sub-region copy in/out) removed in 3.0; see
-   lib/extras/crop_paste.rb for the Ruby thin wrapper replacements. */
 void    ca_fill (void *ap, void *ptr);
 
 /* API : fetch, store */
@@ -1538,9 +1676,10 @@ void    ca_xfer_addrs (void *ap, ca_size_t n, ca_size_t *addrs, void *data, int
    opportunistic engine dispatch. */
 int     ca_xfer_addrs_is_sequential_run (ca_size_t n, ca_size_t *addrs,
                                          ca_size_t *base_out);
-/* Y.1.e: resolve cand through identity CAStride compose-fold to find an
+/* Resolve cand through identity CAStride compose-fold to find an
    attached root.  Returns cand if cand->ptr is set, cand is not CAStride
-   family, or no identity compose-fold path exists; otherwise returns the
+   family, or no identity compose-fold path exists (the cells differ from
+   the root's in data type, width or position); otherwise returns the
    resolved root (which has ptr).  Used by view xfer_addrs slots to lift
    parent->ptr gate through view CAStride layers (= chain pattern). */
 CArray *ca_resolve_attached_root_via_identity (CArray *cand);
@@ -1616,6 +1755,8 @@ void    ca_fill_stride_whole (void *ap, void *ptr);
 extern VALUE CA_UNDEF;
 extern VALUE CA_UNSPECIFIED;
 
+/* The mask's buffer, which a view's mask has only while attached: NULL
+   otherwise. */
 boolean8_t *ca_mask_ptr (void *ap);
 int     ca_has_mask (void *ap);
 int     ca_is_any_masked (void *ap);
@@ -1632,7 +1773,7 @@ void    ca_copy_mask_overwrite (void *ap, ca_size_t elements, int n, ...);
 ca_size_t ca_count_masked (void *ap);
 ca_size_t ca_count_not_masked (void *ap);
 void    ca_unmask (void *ap, char *fill_value);
-CArray *ca_unmasked_copy (void *ap, char *fill_value);
+CArray *ca_unmask_copy (void *ap, char *fill_value);
 
 /* API : cast, conversion */
 
@@ -1646,7 +1787,7 @@ void    ca_ptr2val (void *ap1, void *ptr1, int8_t data_type2, void *ptr2);
 void    ca_val2ptr (int8_t data_type1, void *ptr1, void *ap2, void *ptr2);
 void    ca_val2val (int8_t data_type1, void *ptr1, int8_t data_type2, void *ptr2);
 VALUE   ca_ptr2obj (void *ap, void *ptr);            /* use rb_ca_ptr2obj() */
-void    ca_obj2ptr (void *ap, VALUE obj, void *ptr); /* use rb_ca_ptr2obj() */
+void    ca_obj2ptr (void *ap, VALUE obj, void *ptr); /* use rb_ca_obj2ptr() */
 
 #define ca_wrap_writable(obj, data_type) \
   (obj = rb_ca_wrap_writable(obj, INT2NUM(data_type)), (CArray*) DATA_PTR(obj))
@@ -1672,6 +1813,7 @@ void    ca_parse_range_without_check (VALUE arg, ca_size_t size,
                         ca_size_t *offset, ca_size_t *count, ca_size_t *step);
 
 int     ca_equal (void *ap, void *bp);
+int     ca_eql_storage (void *ap, void *bp);
 void    ca_zerodiv(void)  __attribute__((noreturn));
 /* ca_rand removed in 3.0; use rb_random_real/rb_random_ulong_limited instead */
 ca_size_t ca_bounds_normalize_index (int8_t bounds, ca_size_t size0, ca_size_t k);
@@ -1695,6 +1837,8 @@ void    rb_check_carray_object (VALUE arg);
 
 /* specific Data_Wrap_Struct for carray */
 VALUE   ca_wrap_struct (void *ap);
+/* As ca_wrap_struct, under the class klass.  klass is not checked: it must
+   be a CArray class whose instances share ap's TypedData. */
 VALUE   ca_wrap_struct_as (void *ap, VALUE klass);
 
 /* query data_type */
@@ -1703,7 +1847,8 @@ void    rb_ca_guess_type_and_bytes (VALUE rtype, VALUE rbytes,
                                     int8_t *data_type, ca_size_t *bytes);
 int     rb_ca_is_type (VALUE arg, int type);
 
-/* scan index */ 
+/* scan index.  info->range_check is read, not written: set it (1 to check
+   each index against ca_dim) before the call. */
 void    rb_ca_scan_index (int ca_ndim, ca_size_t *ca_dim, ca_size_t elements,
                           long argc, VALUE *argv, CAIndexInfo *info);
 
@@ -1810,9 +1955,13 @@ VALUE   rb_ca_fill_copy (VALUE self, VALUE val);
 /* address calculation */
 VALUE   rb_ca_addr2index (VALUE self, VALUE raddr);
 
-/* elemental access like ca[i,j,k] or ca[addr] */
+/* A cell's bytes (self's data type, self->bytes wide) as the value ca[i]
+   gives for that cell: true or false for a boolean, the element for a
+   Face, a record for a struct.  The mask is not consulted. */
 VALUE   rb_ca_ptr2obj (VALUE self, void *ptr);
 #define rb_ca_fetch_ptr(self, ptr) rb_ca_ptr2obj(self, ptr)
+
+/* elemental access like ca[i,j,k] or ca[addr] */
 VALUE   rb_ca_fetch_index (VALUE self, ca_size_t *idx);
 VALUE   rb_ca_fetch_addr (VALUE self, ca_size_t addr);
 VALUE   rb_ca_fetch (VALUE self, VALUE index);