carray 3.0.2 → 3.0.4

data/ext/ca_obj_array.c

@@ -9,6 +9,7 @@
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "carray_internal.h"
 
 /* -------------------------------------------------------------------- */
 
@@ -60,7 +61,10 @@ const rb_data_type_t carray_data_type = {
         .dsize = ca_dsize,
         .dcompact = NULL
     },
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+    /* A frozen entity is shared between Ractors: reading it writes nothing
+       to its struct (an entity takes no attach count), so each Ractor makes
+       its own views of it. */
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_FROZEN_SHAREABLE,
 };
 
 const rb_data_type_t cawrap_data_type = {
@@ -84,7 +88,10 @@ const rb_data_type_t cscalar_data_type = {
         .dsize = ca_dsize,
         .dcompact = NULL
     },
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
+    /* A frozen entity is shared between Ractors: reading it writes nothing
+       to its struct (an entity takes no attach count), so each Ractor makes
+       its own views of it. */
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_FROZEN_SHAREABLE
 };
 
 const rb_data_type_t caview_data_type = {
@@ -137,31 +144,16 @@ carray_setup_i (CArray *ca,
                 CArray *mask, int allocate, int use_calloc, char *adopt_ptr)
 {
   ca_size_t elements;
-  double  length;
   int8_t i;
   ca_size_t k;
 
   /* check arguments */
-  CA_CHECK_DATA_TYPE(data_type);
-  CA_CHECK_RANK(ndim);
-  CA_CHECK_DIM(ndim, dim);
-  CA_CHECK_BYTES(data_type, bytes);
-
-  /* calculate total byte length using double to detect overflow */
-  length = bytes;
-  for (i=0; i<ndim; i++) {
-    length *= dim[i];
-  }
+  CA_CHECK_DATA_TYPE_GIVEN(data_type);
+  CA_CHECK_RANK_GIVEN(ndim);
+  CA_CHECK_DIM_GIVEN(ndim, dim);
+  CA_CHECK_BYTES_GIVEN(data_type, bytes);
 
-  if ( length > CA_LENGTH_MAX ) {
-    rb_raise(rb_eRuntimeError, "too large byte length");
-  }
-
-  /* calculate total number of elements (safe after length check above) */
-  elements = 1;
-  for (i=0; i<ndim; i++) {
-    elements *= dim[i];
-  }
+  elements = ca_shape_elements(ndim, dim, bytes);
 
   /* An adopted buffer produces an owning entity (CA_OBJ_ARRAY), not a
      wrap: free_carray xfree()s ca->ptr, so the caller's buffer must be
@@ -173,6 +165,12 @@ carray_setup_i (CArray *ca,
              "cannot adopt a raw buffer as a CA_OBJECT array");
   }
 
+  /* ca == NULL asks for the checks above only, so that a constructor can
+     run them before it allocates. */
+  if ( ca == NULL ) {
+    return 0;
+  }
+
   /* set values to the struct members */
   if ( allocate || adopt_ptr ) {
     ca->obj_type = CA_OBJ_ARRAY;
@@ -198,16 +196,14 @@ carray_setup_i (CArray *ca,
 
     /* allocate memory for entity */
     if ( use_calloc ) {
-      /* ca->ptr = ALLOC_N(char, elements * bytes); */
-      ca->ptr = xmalloc(elements * bytes);
+      ca->ptr = xmalloc(elements * bytes);  /* cells: set to 0 below */
       MEMZERO(ca->ptr, char, elements * bytes);
     }
     else {
-      /* ca->ptr = ALLOC_N(char, elements * bytes); */
-      ca->ptr = xmalloc(elements * bytes);
+      ca->ptr = xmalloc(elements * bytes);  /* cells: set to 0 below */
     }
 
-    /* initialize elements with Qnil for CA_OBJECT data_type */
+    /* an object array starts with every cell 0 */
     if ( allocate && data_type == CA_OBJECT ) {
       volatile VALUE zero = SIZE2NUM(0);
       VALUE *p = (VALUE *) ca->ptr;
@@ -223,6 +219,7 @@ carray_setup_i (CArray *ca,
 
   ca->mask = NULL;
   if ( mask ) {
+    /* mask: only initialize_copy passes one, on a struct Ruby owns */
     ca_setup_mask(ca, mask);
   }
 
@@ -251,9 +248,12 @@ ca_wrap_setup (CArray *ca,
   int ret;
 
   ret = carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 0, 0, NULL);
-  if ( (!ptr) && (ca->elements != 0) ) {
+  if ( (!ptr) && ca_shape_elements(ndim, dim, bytes) != 0 ) {
     rb_raise(rb_eRuntimeError, "wrapping NULL pointer with an non-empty array");
   }
+  if ( ca == NULL ) {                            /* checks only */
+    return ret;
+  }
   ca->ptr = ptr;
   return ret;
 }
@@ -266,26 +266,55 @@ ca_wrap_setup_null (CArray *ca,
   int ret;
 
   ret = carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 0, 0, NULL);
-  ca->ptr = NULL;
+  if ( ca != NULL ) {
+    ca->ptr = NULL;
+  }
   return ret;
 }
 
+static VALUE
+carray_new_copy_mask (VALUE arg)
+{
+  void **a = (void **) arg;
+  ca_setup_mask((CArray *) a[0], (CArray *) a[1]);
+  return Qnil;
+}
+
+/* Reading the mask to copy can call Ruby (a CAObject's mask hooks) and
+   raise, while the new array belongs to no Ruby object yet.  The array is
+   built without it, and the mask is copied in under ca_fill_or_free. */
+static CArray *
+carray_new_with_mask (CArray *ca, CArray *mask)
+{
+  if ( mask ) {
+    void *a[2];
+    a[0] = ca;
+    a[1] = mask;
+    ca_fill_or_free(ca, carray_new_copy_mask, (VALUE) a);
+  }
+  return ca;
+}
+
 CArray *
 carray_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask)
 {
-  CArray *ca  = (CArray *) ca_array_alloc(CA_OBJ_ARRAY, ndim);
-  carray_setup(ca, data_type, ndim, dim, bytes, mask);
-  return ca;
+  CArray *ca;
+  carray_setup(NULL, data_type, ndim, dim, bytes, NULL);
+  ca = (CArray *) ca_array_alloc(CA_OBJ_ARRAY, ndim);
+  carray_setup(ca, data_type, ndim, dim, bytes, NULL);
+  return carray_new_with_mask(ca, mask);
 }
 
 CArray *
 carray_new_safe (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask)
 {
-  CArray *ca  = (CArray *) ca_array_alloc(CA_OBJ_ARRAY, ndim);
-  carray_safe_setup(ca, data_type, ndim, dim, bytes, mask);
-  return ca;
+  CArray *ca;
+  carray_safe_setup(NULL, data_type, ndim, dim, bytes, NULL);
+  ca = (CArray *) ca_array_alloc(CA_OBJ_ARRAY, ndim);
+  carray_safe_setup(ca, data_type, ndim, dim, bytes, NULL);
+  return carray_new_with_mask(ca, mask);
 }
 
 /* Create an entity that adopts a caller-provided data buffer instead of
@@ -301,6 +330,7 @@ carray_new_adopt (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes
   if ( ! ptr ) {
     rb_raise(rb_eRuntimeError, "carray_new_adopt: NULL data pointer");
   }
+  carray_setup_i(NULL, data_type, ndim, dim, bytes, NULL, 0, 0, ptr);
   ca = (CArray *) ca_array_alloc(CA_OBJ_ARRAY, ndim);
   carray_setup_i(ca, data_type, ndim, dim, bytes, NULL, 0, 0, ptr);
   return ca;
@@ -310,18 +340,22 @@ CAWrap *
 ca_wrap_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask, char *ptr)
 {
-  CAWrap *ca  = (CAWrap *) ca_array_alloc(CA_OBJ_ARRAY_WRAP, ndim);
-  ca_wrap_setup(ca, data_type, ndim, dim, bytes, mask, ptr);
-  return ca;
+  CAWrap *ca;
+  ca_wrap_setup(NULL, data_type, ndim, dim, bytes, NULL, ptr);
+  ca = (CAWrap *) ca_array_alloc(CA_OBJ_ARRAY_WRAP, ndim);
+  ca_wrap_setup(ca, data_type, ndim, dim, bytes, NULL, ptr);
+  return (CAWrap *) carray_new_with_mask((CArray *) ca, mask);
 }
 
 CAWrap *
 ca_wrap_new_null (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                   CArray *mask)
 {
-  CAWrap *ca  = (CAWrap *) ca_array_alloc(CA_OBJ_ARRAY_WRAP, ndim);
-  ca_wrap_setup_null(ca, data_type, ndim, dim, bytes, mask);
-  return ca;
+  CAWrap *ca;
+  ca_wrap_setup_null(NULL, data_type, ndim, dim, bytes, NULL);
+  ca = (CAWrap *) ca_array_alloc(CA_OBJ_ARRAY_WRAP, ndim);
+  ca_wrap_setup_null(ca, data_type, ndim, dim, bytes, NULL);
+  return (CAWrap *) carray_new_with_mask((CArray *) ca, mask);
 }
 
 void
@@ -364,8 +398,14 @@ static int
 cscalar_setup (CScalar *ca,
                int8_t data_type, ca_size_t bytes, CArray *mask)
 {
-  CA_CHECK_DATA_TYPE(data_type);
-  CA_CHECK_BYTES(data_type, bytes);
+  CA_CHECK_DATA_TYPE_GIVEN(data_type);
+  CA_CHECK_BYTES_GIVEN(data_type, bytes);
+
+  /* ca == NULL asks for the checks above only, so that a constructor can
+     run them before it allocates. */
+  if ( ca == NULL ) {
+    return 0;
+  }
 
   ca->obj_type  = CA_OBJ_SCALAR;
   ca->data_type = data_type;
@@ -374,7 +414,7 @@ cscalar_setup (CScalar *ca,
   ca->bytes     = bytes;
   ca->elements  = 1;
   ca->dim       = &(ca->_dim);
-  ca->ptr       = xmalloc(bytes);
+  ca->ptr       = xmalloc(bytes);  /* cells: the one cell is set to 0 below */
   ca->mask      = NULL;
 
   ca->dim[0] = 1;
@@ -387,6 +427,7 @@ cscalar_setup (CScalar *ca,
   }
 
   if ( mask ) {
+    /* mask: the constructors pass none (carray_new_with_mask copies it) */
     ca_setup_mask((CArray *)ca, mask);
   }
 
@@ -402,9 +443,11 @@ cscalar_setup (CScalar *ca,
 CScalar *
 cscalar_new (int8_t data_type, ca_size_t bytes, CArray *mask)
 {
-  CScalar *ca = ALLOC(CScalar);
-  cscalar_setup(ca, data_type, bytes, mask);
-  return ca;
+  CScalar *ca;
+  cscalar_setup(NULL, data_type, bytes, NULL);
+  ca = ALLOC(CScalar);
+  cscalar_setup(ca, data_type, bytes, NULL);
+  return (CScalar *) carray_new_with_mask((CArray *) ca, mask);
 }
 
 /*
@@ -414,7 +457,9 @@ cscalar_new (int8_t data_type, ca_size_t bytes, CArray *mask)
 CScalar *
 cscalar_new2 (int8_t data_type, ca_size_t bytes, char *val)
 {
-  CScalar *ca = ALLOC(CScalar);
+  CScalar *ca;
+  cscalar_setup(NULL, data_type, bytes, NULL);
+  ca = ALLOC(CScalar);
   cscalar_setup(ca, data_type, bytes, NULL);
   memcpy(ca->ptr, val, ca->bytes);
   return ca;
@@ -583,6 +628,8 @@ ca_fill_stride_buffer (char *dst, ca_size_t bytes, ca_size_t base, int8_t ndim,
   ca_size_t inner_count, inner_step;
   int8_t    outer_ndim, k;
 
+  if ( ca_region_is_empty(ndim, counts) ) return;
+
   if ( ndim <= 0 ) {
     memcpy(dst + base * bytes, ptr, bytes);
     return;
@@ -593,6 +640,7 @@ ca_fill_stride_buffer (char *dst, ca_size_t bytes, ca_size_t base, int8_t ndim,
   outer_ndim  = ndim - 1;
 
   for ( k = 0; k < outer_ndim; k++ ) idx[k] = 0;
+  /* empty: the function returns on an empty region at its entry */
   while ( 1 ) {
     ca_size_t addr = base;
     char     *p;
@@ -826,7 +874,7 @@ rb_ca_s_allocate (VALUE klass)
 }
 
 /* Reads the (data_type, dim, bytes: nil) argument list that CArray.new
-   and CArray.__empty__ share.  The two differ only in whether the buffer
+   and CArray.empty_of_data_type share.  The two differ only in whether the buffer
    is filled, so the rule for reading their arguments -- the optional
    bytes for a fixlen, the refusal of a Class, the guess of the data type,
    the demand that dim be an Array -- is written once here. */
@@ -857,6 +905,7 @@ ca_scan_construct_args (int argc, VALUE *argv, int8_t *data_type,
   rb_ca_guess_type_and_bytes(rtype, rbytes, data_type, bytes);
 
   Check_Type(rdim, T_ARRAY);
+  CA_CHECK_RANK_GIVEN(RARRAY_LEN(rdim));     /* before dim[] is filled */
   *ndim = RARRAY_LEN(rdim);
   for (i=0; i<*ndim; i++) {
     dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
@@ -886,6 +935,10 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
   ca_scan_construct_args(argc, argv, &data_type, &bytes, &ndim, dim);
 
   TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
+  ca_check_uninitialized(ca);
+  /* Checks first: a rejected argument leaves the struct as allocated, so
+     it takes no pool and can be initialized again. */
+  carray_safe_setup(NULL, data_type, ndim, dim, bytes, NULL);
   if ( ca_func[CA_OBJ_ARRAY].pool_init ) {
     ca_array_pool_alloc(ca, CA_OBJ_ARRAY, ndim);
   }
@@ -904,18 +957,20 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
          with the multi-dimensional subscript yielded as individual
          integer arguments, so |i|, |i,j|, |i,j,k| all work uniformly
          across ranks.  Block forms that want the whole subscript as
-         an Array should write |*idx|. */
-    if ( rb_proc_arity(rb_block_proc()) == 0 ) {
+         an Array should write |*idx|.
+       An array of no cells calls neither, as Array.new(0) { ... } does
+       not. */
+    if ( ca->elements == 0 ) {
+      ;
+    }
+    else if ( rb_proc_arity(rb_block_proc()) == 0 ) {
       volatile VALUE rval = rb_yield_values2(0, NULL);
       rb_ca_store_all(self, rval);
     }
     else if ( ca->ndim > 0 ) {
       ca_size_t idx[CA_RANK_MAX];
       volatile VALUE ridx = rb_ary_new2(ca->ndim);
-      ca_attach(ca);
       rb_ca_index_walk(self, ca, 0, idx, ridx, CA_LOOP_STORE);
-      ca_sync(ca);
-      ca_detach(ca);
     }
     else {
       /* 0-D safety net (rare from CArray.new path): yield no args. */
@@ -1109,6 +1164,7 @@ rb_ca_initialize_copy (VALUE self, VALUE other)
   rb_call_super(1, &other);
 
   TypedData_Get_Struct(self,  CArray, &carray_data_type, ca);
+  ca_check_uninitialized(ca);
   TypedData_Get_Struct(other, CArray, &carray_data_type, cs);
 
   ca_update_mask(cs);
@@ -1117,11 +1173,114 @@ rb_ca_initialize_copy (VALUE self, VALUE other)
   }
   carray_setup(ca, cs->data_type, cs->ndim, cs->dim, cs->bytes, cs->mask);
 
-  memcpy(ca->ptr, cs->ptr, ca_length(cs));
+  if ( cs->ptr ) {
+    memcpy(ca->ptr, cs->ptr, ca_length(cs));
+  }
+  else {
+    /* An entity cold at rest (a CAObject's mask, a source) is read
+       through its slots. */
+    ca_copy_data(cs, ca->ptr);
+  }
+
+  return self;
+}
+
+/* dup and clone go through here before each class's initialize_copy.  A
+   view's copy is another view onto the same parent (Ruby's shallow copy),
+   rebuilt by that class from the parent, so what the original was told
+   about itself -- that it is a value array, read-only, a mask -- has to be
+   carried across here, once for every class.  An entity's copy owns new
+   memory, so it is not a value array and its writability is its own, but
+   a copy of a mask is still a mask (its class, CArrayMask, says so) and
+   can no more hold a mask of its own than the original. */
+static void
+ca_dup_keep_state (VALUE self, VALUE other)
+{
+  CArray *ca, *cs;
+  if ( ! rb_obj_is_kind_of(other, rb_cCArray) ) {
+    return;
+  }
+  TypedData_Get_Struct(self,  CArray, &carray_data_type, ca);
+  TypedData_Get_Struct(other, CArray, &carray_data_type, cs);
+  if ( ca_is_view(cs) ) {
+    ca_keep_chain_flags(ca, cs);
+  }
+  else if ( ca_is_mask_array(cs) ) {
+    ca_set_flag(ca, CA_FLAG_MASK_ARRAY);
+  }
+}
 
+static VALUE
+rb_ca_initialize_dup (VALUE self, VALUE other)
+{
+  rb_call_super(1, &other);
+  ca_dup_keep_state(self, other);
+  rb_ca_own_attr(self);
   return self;
 }
 
+/* clone freezes its result without calling #freeze, so the read-only flag
+   that CArray#freeze sets would be missing: the copy refuses writes as
+   frozen but answers read_only? false.  Set it here when the result is
+   going to be frozen (freeze: true, or freeze: omitted and the original
+   frozen). */
+static VALUE
+rb_ca_initialize_clone (int argc, VALUE *argv, VALUE self)
+{
+  VALUE orig, opts, vfreeze = Qnil;
+  int will_freeze;
+
+  rb_call_super_kw(argc, argv, RB_PASS_CALLED_KEYWORDS);
+  rb_scan_args(argc, argv, "1:", &orig, &opts);
+  ca_dup_keep_state(self, orig);
+  rb_ca_own_attr(self);
+
+  if ( ! NIL_P(opts) ) {
+    vfreeze = rb_hash_lookup2(opts, ID2SYM(rb_intern("freeze")), Qnil);
+  }
+  will_freeze = NIL_P(vfreeze) ? OBJ_FROZEN(orig) : RTEST(vfreeze);
+  if ( will_freeze ) {
+    CArray *ca;
+    TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
+    ca_set_flag(ca, CA_FLAG_READ_ONLY);
+  }
+  return self;
+}
+
+/* A wrap borrows memory it does not own.  Object#dup would give the copy
+   the wrap's class over memory the copy owns, so a subclass that names what
+   it borrows (a libvips image's pixels) would name an array that borrows
+   nothing.  The copy is a plain CArray, as #copy is: the name goes with
+   what is borrowed. */
+static VALUE
+rb_ca_wrap_dup (VALUE self)
+{
+  return rb_ca_copy(self);
+}
+
+static VALUE
+rb_ca_wrap_clone (int argc, VALUE *argv, VALUE self)
+{
+  VALUE opt = Qnil, rfreeze = Qnil;
+  volatile VALUE obj;
+  rb_scan_args(argc, argv, "0:", &opt);
+  if ( ! NIL_P(opt) ) {
+    /* rb_get_kwargs refuses any key but freeze:, as Kernel#clone does. */
+    ID kw[1];
+    VALUE val[1];
+    kw[0] = rb_intern("freeze");
+    rb_get_kwargs(opt, kw, 0, 1, val);
+    if ( val[0] != Qundef ) {
+      rfreeze = val[0];
+    }
+  }
+  obj = rb_ca_copy(self);
+  if ( RTEST(rfreeze) || ( NIL_P(rfreeze) && OBJ_FROZEN(self) ) ) {
+    rb_obj_freeze(obj);
+  }
+  return obj;
+}
+
 /* @overload wrap (data_type, dim, bytes=0) { target }
 
 [TBD] (Construction)
@@ -1144,6 +1303,7 @@ rb_ca_s_wrap (int argc, VALUE *argv, VALUE self)
   rb_ca_guess_type_and_bytes(rtype, rbytes, &data_type, &bytes);
 
   Check_Type(rdim, T_ARRAY);
+  CA_CHECK_RANK_GIVEN(RARRAY_LEN(rdim));     /* before dim[] is filled */
   ndim = RARRAY_LEN(rdim);
   for (i=0; i<ndim; i++) {
     dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
@@ -1212,6 +1372,7 @@ rb_cs_initialize (int argc, VALUE *argv, VALUE self)
   rb_ca_guess_type_and_bytes(rtype, rbytes, &data_type, &bytes);
 
   TypedData_Get_Struct(self, CScalar, &cscalar_data_type, ca);
+  ca_check_uninitialized(ca);
   cscalar_setup(ca, data_type, bytes, NULL);
 
   if ( rb_block_given_p() ) {
@@ -1405,6 +1566,7 @@ rb_cs_initialize_copy (VALUE self, VALUE other)
   CScalar *ca, *cs;
 
   TypedData_Get_Struct(self,  CScalar, &cscalar_data_type, ca);
+  ca_check_uninitialized(ca);
   TypedData_Get_Struct(other, CScalar, &cscalar_data_type, cs);
 
   cscalar_setup(ca, cs->data_type, cs->bytes, NULL);
@@ -1447,6 +1609,7 @@ rb_ca_s_alloc_uninit (VALUE klass, VALUE rtype, VALUE rshape)
   int8_t i;
   rb_ca_guess_type_and_bytes(rtype, Qnil, &data_type, &bytes);
   Check_Type(rshape, T_ARRAY);
+  CA_CHECK_RANK_GIVEN(RARRAY_LEN(rshape));   /* before dim[] is filled */
   ndim = (int8_t) RARRAY_LEN(rshape);
   for (i = 0; i < ndim; i++) dim[i] = NUM2SIZE(rb_ary_entry(rshape, i));
   return rb_carray_new(data_type, ndim, dim, bytes, NULL);
@@ -1490,7 +1653,7 @@ Init_ca_obj_array (void)
   rb_define_method(rb_cCArray, "initialize", rb_ca_initialize, -1);
   rb_define_singleton_method(rb_cCArray, "__alloc_uninit__",
                              rb_ca_s_alloc_uninit, 2);
-  rb_define_singleton_method(rb_cCArray, "__empty__", rb_ca_s_empty, -1);
+  rb_define_private_method(rb_singleton_class(rb_cCArray), "empty_of_data_type", rb_ca_s_empty, -1);
 
   rb_define_singleton_method(rb_cCArray, "fixlen", rb_ca_s_fixlen, -1);
   rb_define_singleton_method(rb_cCArray, "boolean", rb_ca_s_boolean, -1);
@@ -1521,6 +1684,10 @@ Init_ca_obj_array (void)
 #endif
 
   rb_define_method(rb_cCArray, "initialize_copy", rb_ca_initialize_copy, 1);
+  rb_define_method(rb_cCArray, "initialize_dup", rb_ca_initialize_dup, 1);
+  rb_define_method(rb_cCArray, "initialize_clone", rb_ca_initialize_clone, -1);
+  rb_define_method(rb_cCAWrap, "dup",   rb_ca_wrap_dup, 0);
+  rb_define_method(rb_cCAWrap, "clone", rb_ca_wrap_clone, -1);
   rb_define_singleton_method(rb_cCArray, "wrap", rb_ca_s_wrap, -1);
 
   /* ------------------------------------------------------------------- */