carray 3.0.1 → 3.0.2

data/ext/ca_sweep_engine.h

@@ -13,7 +13,7 @@
  *          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)
+ *    (2) operand pairing (scalar collapse; arrays must agree in shape)
  *    (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[]
@@ -84,14 +84,20 @@ typedef struct ca_sweep_state {
   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 */
+  int             chunked_state; /* 0=pre-init, 1=active, 2=done,
+                                    3=aborted (a read raised; resources
+                                    already given back) */
   boolean8_t     *mask_scratch;  /* chunk-sized staging for the per-chunk
                                     mask OR; NULL when no INPUT is masked */
 } 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). */
+/* Validate fsync length, pair the operands (shape), acquire per-op
+ * buffers, build mask m0, propagate mask to OUTPUTs.  May raise: refusals
+ * (fsync length, shape mismatch, masked INPUT in a NO_MASK form) before
+ * anything is held, and a raising operand read after -- in which case
+ * everything acquired so far is detached / freed before the raise
+ * propagates, so the caller must not call release.  The chunked path
+ * does the same for acquire_chunked and each ca_sweep_next_chunk. */
 void ca_sweep_acquire (ca_sweep_state_t *st);
 
 /* Reverse-order release: sync OUTPUTs, detach attached / xfree owned_buf,
@@ -99,6 +105,21 @@ void ca_sweep_acquire (ca_sweep_state_t *st);
  * state without re-initializing the caller-owned arrays. */
 void ca_sweep_release (ca_sweep_state_t *st);
 
+/* Run walk(arg) -- the caller's loop over the acquired state -- and then
+ * release.  If walk raises (a callback refusing a value), everything the
+ * engine holds is detached / freed without syncing before the raise
+ * propagates.  Use in place of calling ca_sweep_release /
+ * ca_sweep_release_chunked yourself whenever the loop can raise.  The
+ * chunked walk calls ca_sweep_next_chunk itself. */
+void ca_sweep_run         (ca_sweep_state_t *st, VALUE (*walk)(VALUE), VALUE arg);
+void ca_sweep_run_chunked (ca_sweep_state_t *st, VALUE (*walk)(VALUE), VALUE arg);
+
+/* Shape pairing shared with rb_ca_template_n: non-zero when a and b have
+ * the same ndim and dims; the refusal raises ArgumentError naming both
+ * shapes. */
+int  ca_sweep_same_shape (CArray *a, CArray *b);
+NORETURN(void ca_sweep_refuse_shapes (CArray *a, CArray *b));
+
 /* 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. */

data/ext/carray.h

@@ -922,7 +922,6 @@ extern const rb_data_type_t careduce_data_type;
 extern const rb_data_type_t carefer_data_type;
 extern const rb_data_type_t caselect_data_type;
 extern const rb_data_type_t cashift_data_type;
-extern const rb_data_type_t caunboundrepeat_data_type;
 extern const rb_data_type_t cawindow_data_type;
 
 extern const rb_data_type_t carray_mask_data_type;
@@ -933,7 +932,6 @@ 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;
 extern const rb_data_type_t cashift_mask_data_type;
-extern const rb_data_type_t caunboundrepeat_mask_data_type;
 extern const rb_data_type_t cawindow_mask_data_type;
 
 /* -------------------------------------------------------------------- */
@@ -1476,6 +1474,27 @@ 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.
+   This block is the canonical statement of the contract; the other documents
+   copy it.  guides/devel/04_attach_lifecycle.md discusses it at length.
+
+     R1 (validity)   ca_attach(x) makes x->ptr only valid.  It says nothing
+                     about any other array.
+     R2 (no transit) Attaching a child does not attach its parent.  An
+                     implementation may do so as an internal optimisation;
+                     never rely on it.
+     R3 (necessity)  To touch ca->parent->ptr, call ca_attach(ca->parent)
+                     yourself.
+     R4 (ordering)   Attaching both parent and child: open parent -> child,
+                     close child -> parent, sync in attach order.  Symmetric
+                     nesting stays correct when a view double-attaches
+                     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.
+*/
+
 void    ca_allocate (void *ap);
 void    ca_attach (void *ca);
 void    ca_update (void *ca);

data/ext/carray_access.c

@@ -19,7 +19,7 @@ static ID id_begin, id_end, id_excl_end;
 #define RANGE_EXCL(r) (rb_funcall(r, id_excl_end, 0))
 
 static ID id_to_ca;
-static VALUE sym_star, sym_perc, sym_under, sym_gt, sym_tilde;
+static VALUE sym_perc, sym_under, sym_gt, sym_tilde;
 static VALUE S_CAInfo;
 
 VALUE
@@ -1089,11 +1089,8 @@ rb_ca_fetch_method (int argc, VALUE *argv, VALUE self)
      already-a-Face case (some builders lift their own result) is handled
      inside ca_wrapper_lift.
 
-     Every CA_REG_* branch converges here, so this one line covers all of
-     them -- but not every index form: `a[:*, nil]` builds a CAUnboundRepeat,
-     whose shape stays open until an operand binds it, and a marker copies
-     shape at construction.  ca_wrapper_lift refuses that one, in one place,
-     because `unbound_repeat` reaches it by a second route. */
+     Every CA_REG_* branch converges here, so this one line covers every
+     index form that returns a CArray. */
   CA_WRAPPER_LIFT(obj, self, ca);
 
   return obj;
@@ -1107,6 +1104,8 @@ rb_ca_fetch_newaxis (int argc, VALUE *argv, VALUE self, CArray *ca)
 {
   int i;
   int nclean = 0;
+  int nscalar = 0;
+  int nunder = 0;
   VALUE clean[CA_RANK_MAX];
   volatile VALUE base;
   ca_size_t final_dims[CA_RANK_MAX];
@@ -1118,11 +1117,17 @@ rb_ca_fetch_newaxis (int argc, VALUE *argv, VALUE self, CArray *ca)
   /* Build clean argv (strip :_); reject disjoint sigils + rubber dim. */
   for (i = 0; i < argc; i++) {
     VALUE a = argv[i];
-    if ( a == sym_under ) continue;
-    if ( a == sym_gt || a == sym_star || a == sym_perc
+    if ( a == sym_under ) {
+      nunder++;
+      continue;
+    }
+    if ( FIXNUM_P(a) || RB_TYPE_P(a, T_BIGNUM) ) {
+      nscalar++;
+    }
+    if ( a == sym_gt || a == sym_perc
          || a == Qfalse || a == sym_tilde ) {
       rb_raise(rb_eIndexError,
-               "newaxis (:_) cannot be combined with :>, :*, :%%, "
+               "newaxis (:_) cannot be combined with :>, :%%, "
                "or rubber dim (false / :~)");
     }
     if ( nclean >= CA_RANK_MAX ) {
@@ -1140,18 +1145,26 @@ rb_ca_fetch_newaxis (int argc, VALUE *argv, VALUE self, CArray *ca)
              nclean, (int) ca->ndim);
   }
 
-  base = rb_ca_fetch_method(nclean, clean, self);
-
-  /* Degenerate: all real axes scalar -> base is a scalar element, not a
-     CArray.  Out of scope (rare + degenerate); user indexes the element
-     and reshapes explicitly.  IndexError keeps it catchable + consistent
-     with the other newaxis rejects. */
-  if ( ! rb_obj_is_kind_of(base, rb_cCArray) ) {
-    rb_raise(rb_eIndexError,
-             "newaxis (:_) needs at least one non-scalar axis "
-             "(all-scalar indexing yields a single element)");
+  /* Every real axis indexed by a scalar: fetching `clean` would yield the
+     element itself, and there would be nothing left to reshape.  Ask for a
+     length-1 block on each axis instead, so the base stays a CArray and the
+     result is a view into self.  The result carries exactly the axes :_ asked
+     for, all of length 1 -- an operand that states rank nunder and one
+     element, which is what the shape rules then hold it to. */
+  if ( nscalar == nclean ) {
+    VALUE blocks[CA_RANK_MAX];
+    for (i = 0; i < nclean; i++) {
+      blocks[i] = rb_assoc_new(clean[i], INT2FIX(1));
+    }
+    base = rb_ca_fetch_method(nclean, blocks, self);
+    for (i = 0; i < nunder; i++) {
+      dim_argv[i] = INT2FIX(1);
+    }
+    return rb_ca_reshape(nunder, dim_argv, base);
   }
 
+  base = rb_ca_fetch_method(nclean, clean, self);
+
   TypedData_Get_Struct(base, CArray, &carray_data_type, cb);
 
   /* Reconstruct final shape: walk original argv.  :_ -> size-1, scalar
@@ -2076,7 +2089,6 @@ Init_carray_access (void)
   id_excl_end = rb_intern("exclude_end?");
 
   id_to_ca = rb_intern("to_ca");
-  sym_star  = ID2SYM(rb_intern("*"));
   sym_perc  = ID2SYM(rb_intern("%"));
   sym_under = ID2SYM(rb_intern("_"));
   sym_gt    = ID2SYM(rb_intern(">"));