carray 3.0.1 → 3.0.3

data/ext/carray_address_basis.c

@@ -0,0 +1,731 @@
+#include "carray.h"
+#include "carray_internal.h"
+
+/* ---------------------------------------------------------------------------
+
+  Address bases -- CArray::AddressBasis.
+
+  Some code addresses cells itself.  A generated kernel reads a[i-1] and
+  writes a[i] from its own loop, so what it needs from CArray is not element
+  delivery but an addressing basis: a pointer, already shifted to cell zero,
+  and one byte stride per axis.  That is why this does not sit on the kernel
+  iterator (per-cell / per-slab delivery, and no N-ary form) or on the
+  call_cfunc families (which flatten the array and cannot recover the axis
+  structure a stencil needs).
+
+  This is a runtime facility at the same layer as ca_attach, not a user
+  surface.  It hands raw addresses to Ruby, and nothing decodes them except a
+  consumer that already knows what to do with them -- today carray-jit, the
+  one companion carray knows by name, and the gem that runs its output
+  ahead of time.  It is documented in guides/devel/, not in the user-facing
+  docs/ tree, and it is not advertised as API.
+
+  Arrays are classified in the order the public predicates suggest:
+
+    1. ca_is_entity          -> the buffer is already the basis
+    2. ca_is_stride_family,  -> ca_stride_compose_to_root folds the whole
+       and the fold reaches      view chain into root + base + strides, so a
+       an entity                 transpose or a column slice is addressed in
+                                 place, with no gather and no scatter.  A
+                                 fold that stops short of an entity is not
+                                 this tier; see folds_to_an_entity below
+    3. otherwise             -> ca_xfer_stride moves only the box the kernel
+                                actually touches -- the loop range grown by
+                                how far the kernel reaches, per array and per
+                                axis -- into a packed buffer, and writes that
+                                box back
+
+  Tier 3 deliberately never calls ca_attach on the view.  A whole-view
+  materialise costs the same whether the kernel touches ten cells or ten
+  million: measured on a four-million-element gather view, ca_attach was
+  2.7 ms regardless, while the region transfer was 0.001 ms for a hundred
+  cells and 2.3 ms for a million.  A cost that does not scale with the work
+  is a cost the caller cannot reason about, and hiding one behind a JIT
+  would make its promise meaningless.  What tier 3 does cost is proportional
+  to what the kernel asked to touch.
+
+  The block form (`open` with four arguments) yields one descriptive Hash per
+  array.  The packed form (a fifth argument that is true) yields four byte
+  buffers instead, in a layout the consumer reads by offset; that layout is a
+  contract between the two and is written out as such in
+  guides/devel/21_address_basis.md.  See packed_body below.
+
+--------------------------------------------------------------------------- */
+
+/* Rounded so that each section of the block below starts where the widest
+   thing in it may be read. */
+#define ROUND_UP_8(n) (((n) + 7u) & ~(size_t) 7u)
+
+#define TIER_ENTITY 1
+#define TIER_STRIDE 2
+#define TIER_XFER   3
+
+/* Slot layout: slot i is array i, slot count + i is that array's mask.
+   A mask is a CArray of the same shape as its parent and, for a view, the
+   same kind of view -- a CABlock's mask is a CABlockMask -- so it is opened
+   by exactly the same tier logic as the data. */
+typedef struct {
+  char      *block;           /* the one allocation the arrays below carve up */
+  int        count;
+  int        slots;
+  VALUE      arrays;
+  CArray   **carrays;
+  CArray   **roots;
+  int       *tier;
+  int       *writable;
+  int       *attached_root;
+  char     **region;          /* tier 3 packed buffer, NULL otherwise */
+  ca_size_t *region_start;    /* count * CA_RANK_MAX */
+  ca_size_t *region_count;
+  VALUE      bases;
+  VALUE      box_starts;      /* per array, per axis; nil for "all of it" */
+  VALUE      box_counts;
+  int        body_done;       /* the block returned without raising */
+  volatile VALUE put_error;   /* the first write-back that raised, or nil */
+} open_state;
+
+/* The view's own row-major byte layout, which is the address space
+   ca_xfer_stride describes a region in. */
+static void
+native_steps (CArray *ca, ca_size_t *steps)
+{
+  ca_size_t step = ca->bytes;
+  int8_t k;
+  for ( k = ca->ndim - 1; k >= 0; k-- ) {
+    steps[k] = step;
+    step *= ca->dim[k];
+  }
+}
+
+/* Whether [start, start + count) leaves [0, dim).  Written so that no sum
+   is formed: a start and a count near the top of the integer range add up
+   to a negative number, which `start + count > dim` lets through. */
+static int
+outside_axis (ca_size_t start, ca_size_t count, ca_size_t dim)
+{
+  return start < 0 || count < 0 || start > dim || count > dim - start;
+}
+
+/* Checks one array's box description, all of it: that it is one start and one
+   count per axis, that they are numbers, and that the box they describe is
+   inside the array.
+
+   Run for every array before any of them is opened, whatever tier each turns
+   out to land in.  Only tier 3 goes on to read the box -- tiers 1 and 2
+   address the whole array, which covers any box inside it -- so this is the
+   only place a caller's description is looked at at all for two of the three
+   tiers.  Checking it there too is what keeps the same call refused the same
+   way whatever the arrays turn out to be, rather than a box that is wrong
+   about a plain array being noticed only once the same code is handed a
+   gather view.  And it is a C extension, where a wrong type has to be a
+   message and not a crash. */
+static void
+verify_box (VALUE box_starts, VALUE box_counts, int index, CArray *ca)
+{
+  VALUE  starts, counts;
+  int8_t k;
+  if ( NIL_P(box_starts) ) return;
+  starts = rb_ary_entry(box_starts, index);
+  counts = rb_ary_entry(box_counts, index);
+  if ( NIL_P(starts) && NIL_P(counts) ) return;
+  Check_Type(starts, T_ARRAY);
+  Check_Type(counts, T_ARRAY);
+  if ( RARRAY_LEN(starts) != ca->ndim || RARRAY_LEN(counts) != ca->ndim ) {
+    rb_raise(rb_eArgError,
+             "a region is described by one start and one count per axis; "
+             "this array has %d", (int) ca->ndim);
+  }
+  for ( k = 0; k < ca->ndim; k++ ) {
+    ca_size_t start = ca_integer_arg(rb_ary_entry(starts, k), "a region start",
+                                     "CArray::AddressBasis.open");
+    ca_size_t count = ca_integer_arg(rb_ary_entry(counts, k), "a region count",
+                                     "CArray::AddressBasis.open");
+    if ( outside_axis(start, count, ca->dim[k]) ) {
+      rb_raise(rb_eArgError,
+               "the requested region falls outside the array on axis %d", (int) k);
+    }
+  }
+}
+
+/* Reads one array's box out of the Ruby-side description, defaulting to the
+   whole array.  verify_box checked it, and checks it again here because this
+   is the last thing between a caller's numbers and pointer arithmetic. */
+static void
+read_box (open_state *state, int index, CArray *ca,
+          ca_size_t *starts, ca_size_t *counts)
+{
+  VALUE per_array_start = Qnil, per_array_count = Qnil;
+  int8_t k;
+
+  if ( ! NIL_P(state->box_starts) ) {
+    per_array_start = rb_ary_entry(state->box_starts, index);
+    per_array_count = rb_ary_entry(state->box_counts, index);
+  }
+
+  for ( k = 0; k < ca->ndim; k++ ) {
+    if ( NIL_P(per_array_start) ) {
+      starts[k] = 0;
+      counts[k] = ca->dim[k];
+    } else {
+      starts[k] = NUM2LL(rb_ary_entry(per_array_start, k));
+      counts[k] = NUM2LL(rb_ary_entry(per_array_count, k));
+    }
+    if ( outside_axis(starts[k], counts[k], ca->dim[k]) ) {
+      rb_raise(rb_eArgError,
+               "the requested region falls outside the array on axis %d", (int) k);
+    }
+  }
+}
+
+static void
+row_major_strides (CArray *ca, ca_size_t *strides)
+{
+  ca_size_t step = ca->bytes;
+  int8_t k;
+  for ( k = ca->ndim - 1; k >= 0; k-- ) {
+    strides[k] = step;
+    step *= ca->dim[k];
+  }
+}
+
+static VALUE
+size_array (ca_size_t *values, int8_t count)
+{
+  VALUE list = rb_ary_new_capa(count);
+  int8_t k;
+  for ( k = 0; k < count; k++ ) {
+    rb_ary_push(list, LL2NUM((long long) values[k]));
+  }
+  return list;
+}
+
+/* Refuses what a generated kernel cannot express, rather than letting it
+   produce quietly wrong numbers. */
+static void
+verify_usable (VALUE object, CArray *ca, int writable)
+{
+  if ( ca->data_type == CA_OBJECT ) {
+    rb_raise(rb_eArgError, "object arrays hold Ruby values, not numbers");
+  }
+  if ( writable && ca_is_readonly(ca) ) {
+    rb_raise(rb_eRuntimeError, "%"PRIsVALUE" is read-only",
+             rb_obj_class(object));
+  }
+}
+
+/* The stride tier addresses the fold's root directly, which is only sound
+   when that root owns its memory.  ca_stride_compose_to_root stops at the
+   first thing it cannot fold through, and that need not be an entity: a
+   CARefer over a gather view (`whole[whole >= 0].reshape(4, 4)`) folds one
+   step and lands on the CASelect.  Attaching a root like that materialises a
+   temporary, and detaching it throws the kernel's writes away -- silently.
+   So a fold that does not reach an entity is not the stride tier; the box
+   transfer handles it, and moves only the cells the kernel asked for. */
+static int
+folds_to_an_entity (CArray *ca)
+{
+  CArray   *root;
+  ca_size_t strides[CA_RANK_MAX];
+  ca_size_t base = 0;
+  ca_stride_compose_to_root((CAStride *) ca, &root, strides, &base);
+  return ca_is_entity(root);
+}
+
+/* A view that reinterprets the element size -- refer(CA_INT32, ...) over
+   a float64 array -- gets a mask of its own shape, but one mask cell of it
+   covers a fraction of a parent cell, so writing cell i's mask also marks
+   its neighbour.  A per-cell kernel writes cells independently and cannot
+   express that.  Checked for every tier: a box transfer moves the same
+   mask, and the neighbour is marked when it is written back. */
+static void
+verify_mask_cells (VALUE object, CArray *ca)
+{
+  CArray   *root;
+  ca_size_t strides[CA_RANK_MAX];
+  ca_size_t base = 0;
+  if ( ! ca->mask || ! ca_is_stride_family(ca) ) return;
+  ca_stride_compose_to_root((CAStride *) ca, &root, strides, &base);
+  if ( ca->bytes != root->bytes ) {
+    rb_raise(rb_eArgError,
+             "%"PRIsVALUE" reinterprets the element size and carries a mask; "
+             "its mask cells do not map one to one onto the parent's",
+             rb_obj_class(object));
+  }
+}
+
+static int
+tier_for (CArray *ca)
+{
+  if ( ca_is_entity(ca) ) return TIER_ENTITY;
+  if ( ca_is_stride_family(ca) && folds_to_an_entity(ca) ) return TIER_STRIDE;
+  return TIER_XFER;
+}
+
+/* Attaches or transfers one array and answers where its first cell is,
+   filling `strides` with how far apart the rest are.  This is everything a
+   basis says that a kernel actually reads; the hash around it is for the
+   callers that want to look. */
+static char *
+acquire_basis (open_state *state, int index, ca_size_t *strides)
+{
+  CArray   *ca = state->carrays[index];
+  ca_size_t base = 0;
+  char     *pointer;
+
+  switch ( state->tier[index] ) {
+  case TIER_ENTITY: {
+    CArray *root = ca;
+    ca_attach(root);   /* window: released by open_ensure */
+    state->roots[index] = root;
+    state->attached_root[index] = 1;
+    row_major_strides(ca, strides);
+    pointer = ca->ptr;
+    break;
+  }
+
+  case TIER_STRIDE: {
+    CArray *root;
+    ca_stride_compose_to_root((CAStride *) ca, &root, strides, &base);
+    ca_attach(root);   /* window: released by open_ensure */
+    state->roots[index] = root;
+    state->attached_root[index] = 1;
+    pointer = root->ptr + base;
+    break;
+  }
+
+  default: {
+    /* Only the requested box crosses, never the whole view. */
+    ca_size_t starts[CA_RANK_MAX], counts[CA_RANK_MAX], steps[CA_RANK_MAX];
+    ca_size_t elements = 1, shift = 0, step;
+    int8_t    k;
+    char     *buffer;
+
+    native_steps(ca, steps);
+    read_box(state, index, ca, starts, counts);
+    for ( k = 0; k < ca->ndim; k++ ) elements *= counts[k];
+
+    /* ca_xfer_stride packs the box row-major, so the buffer's strides come
+       from the box's own extents, not the view's. */
+    step = ca->bytes;
+    for ( k = ca->ndim - 1; k >= 0; k-- ) {
+      strides[k] = step;
+      step *= counts[k];
+    }
+
+    /* Recorded before the read: the read can raise, and open_ensure
+       frees what state->region holds.  The counts stay zero until the
+       read is done, so a buffer that was never filled is not written
+       back. */
+    /* A writable box keeps a second copy of what it read, so that the
+       write-back can send only the cells the kernel changed (see
+       put_changed). */
+    buffer = ALLOC_N(char, (state->writable[index] ? 2 : 1)
+                           * (elements > 0 ? elements : 1) * ca->bytes);
+    for ( k = 0; k < ca->ndim; k++ ) {
+      state->region_count[index * CA_RANK_MAX + k] = 0;
+    }
+    state->region[index] = buffer;
+    if ( elements > 0 ) {
+      ca_xfer_stride(ca, starts, counts, steps, buffer, CA_XFER_GET);
+      if ( state->writable[index] ) {
+        memcpy(buffer + elements * ca->bytes, buffer, elements * ca->bytes);
+      }
+    }
+
+    for ( k = 0; k < ca->ndim; k++ ) {
+      state->region_start[index * CA_RANK_MAX + k] = starts[k];
+      state->region_count[index * CA_RANK_MAX + k] = counts[k];
+      shift += starts[k] * strides[k];
+    }
+    /* Shifted so that the box's first cell lands on buffer[0], the way a
+       view's base_offset shifts its parent's pointer. */
+    pointer = buffer - shift;
+    break;
+  }
+  }
+
+  return pointer;
+}
+
+static VALUE
+basis_for (open_state *state, int index)
+{
+  CArray   *ca = state->carrays[index];
+  ca_size_t strides[CA_RANK_MAX];
+  char     *pointer = acquire_basis(state, index, strides);
+  VALUE     result;
+
+  result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("tier")), INT2NUM(state->tier[index]));
+  rb_hash_aset(result, ID2SYM(rb_intern("pointer")),
+               ULL2NUM((unsigned long long)(uintptr_t) pointer));
+  rb_hash_aset(result, ID2SYM(rb_intern("strides")), size_array(strides, ca->ndim));
+  rb_hash_aset(result, ID2SYM(rb_intern("dim")), size_array(ca->dim, ca->ndim));
+  rb_hash_aset(result, ID2SYM(rb_intern("bytes")), LL2NUM((long long) ca->bytes));
+  rb_hash_aset(result, ID2SYM(rb_intern("data_type")), INT2NUM(ca->data_type));
+  rb_hash_aset(result, ID2SYM(rb_intern("writable")),
+               state->writable[index] ? Qtrue : Qfalse);
+  return result;
+}
+
+/* Each array's basis, with its mask's basis folded in under :mask_pointer
+   and :mask_strides (nil when the array carries no mask). */
+static VALUE
+open_body (VALUE argument)
+{
+  open_state *state = (open_state *) argument;
+  int i;
+  for ( i = 0; i < state->count; i++ ) {
+    VALUE basis = basis_for(state, i);
+    if ( state->carrays[state->count + i] ) {
+      VALUE mask = basis_for(state, state->count + i);
+      rb_hash_aset(basis, ID2SYM(rb_intern("mask_pointer")),
+                   rb_hash_aref(mask, ID2SYM(rb_intern("pointer"))));
+      rb_hash_aset(basis, ID2SYM(rb_intern("mask_strides")),
+                   rb_hash_aref(mask, ID2SYM(rb_intern("strides"))));
+    } else {
+      rb_hash_aset(basis, ID2SYM(rb_intern("mask_pointer")), Qnil);
+      rb_hash_aset(basis, ID2SYM(rb_intern("mask_strides")), Qnil);
+    }
+    rb_ary_push(state->bases, basis);
+  }
+  {
+    VALUE result = rb_yield(state->bases);
+    state->body_done = 1;
+    return result;
+  }
+}
+
+typedef struct {
+  CArray    *ca;
+  ca_size_t *start;
+  ca_size_t *count;
+  ca_size_t *steps;
+  char      *data;
+  char      *read;      /* the box as it was read */
+} write_back_args;
+
+/* Sends back the cells whose bytes differ from what was read, one run
+   along the last axis at a time.  Sending the whole box would also send the
+   cells the kernel never wrote, and those do not come back unchanged
+   through a view that converts -- a float64 array seen through an int32
+   view reads 1.75 as 1 and would be left holding 1.0.  It would also
+   overwrite what the kernel wrote to the same cells through another basis
+   that addresses them in place. */
+static VALUE
+write_back (VALUE argument)
+{
+  write_back_args *w = (write_back_args *) argument;
+  CArray   *ca    = w->ca;
+  int8_t    nd    = ca->ndim;
+  size_t    bytes = ca->bytes;
+  ca_size_t inner = w->count[nd - 1];
+  ca_size_t outer = 1;
+  ca_size_t idx[CA_RANK_MAX], start[CA_RANK_MAX], count[CA_RANK_MAX];
+  ca_size_t o, j, e;
+  int8_t    k;
+
+  for ( k = 0; k < nd - 1; k++ ) {
+    outer *= w->count[k];
+    idx[k] = 0;
+    count[k] = 1;
+  }
+  for ( o = 0; o < outer; o++ ) {
+    char *row  = w->data + o * inner * bytes;
+    char *read = w->read + o * inner * bytes;
+    for ( k = 0; k < nd - 1; k++ ) start[k] = w->start[k] + idx[k];
+    j = 0;
+    while ( j < inner ) {
+      if ( ! memcmp(row + j * bytes, read + j * bytes, bytes) ) { j++; continue; }
+      e = j + 1;
+      while ( e < inner && memcmp(row + e * bytes, read + e * bytes, bytes) ) e++;
+      start[nd - 1] = w->start[nd - 1] + j;
+      count[nd - 1] = e - j;
+      ca_xfer_stride(ca, start, count, w->steps, row + j * bytes, CA_XFER_PUT);
+      j = e;
+    }
+    for ( k = nd - 2; k >= 0; k-- ) {
+      if ( ++idx[k] < w->count[k] ) break;
+      idx[k] = 0;
+    }
+  }
+  return Qnil;
+}
+
+/* Closes in reverse order, and runs whether or not the kernel raised.  A
+   write-back that raises -- the array's own transfer slot failing -- is
+   set aside so that every other region is still written and freed and
+   every root detached; the block's own exception, if it raised, wins. */
+static VALUE
+open_ensure (VALUE argument)
+{
+  open_state *state = (open_state *) argument;
+  int i;
+  for ( i = state->slots - 1; i >= 0; i-- ) {
+    CArray *ca = state->carrays[i];
+    if ( ca == NULL ) continue;
+    /* A tier-1 or tier-2 basis addresses the root's own memory, so a write is
+       already where it belongs.  Only a region buffer has to be sent back. */
+    if ( state->region[i] ) {
+      ca_size_t elements = 1;
+      int8_t k;
+      for ( k = 0; k < ca->ndim; k++ ) {
+        elements *= state->region_count[i * CA_RANK_MAX + k];
+      }
+      if ( state->writable[i] && elements > 0 ) {
+        ca_size_t       steps[CA_RANK_MAX];
+        write_back_args w;
+        int             tag = 0;
+        native_steps(ca, steps);
+        w.ca    = ca;
+        w.start = &state->region_start[i * CA_RANK_MAX];
+        w.count = &state->region_count[i * CA_RANK_MAX];
+        w.steps = steps;
+        w.data  = state->region[i];
+        w.read  = state->region[i] + elements * ca->bytes;
+        rb_protect(write_back, (VALUE) &w, &tag);
+        if ( tag ) {
+          if ( NIL_P(state->put_error) ) {
+            state->put_error = rb_errinfo();
+          }
+          rb_set_errinfo(Qnil);
+        }
+      }
+      xfree(state->region[i]);
+    }
+    if ( state->attached_root[i] ) {
+      ca_detach(state->roots[i]);
+    }
+  }
+  xfree(state->block);
+  if ( state->body_done && RTEST(rb_obj_is_kind_of(state->put_error,
+                                                   rb_eException)) ) {
+    rb_exc_raise(state->put_error);
+  }
+  return Qnil;
+}
+
+/* What a kernel is handed, rather than what a reader wants to see.
+ *
+ * The hash form above exists so that a caller can ask an array how it was
+ * opened.  A kernel never asks: it packs the pointers and the strides into
+ * four buffers and passes their addresses to the C.  Building a Hash and an
+ * Array per array so that Ruby can immediately pack them back into bytes is
+ * a round trip through the object heap that nothing looks at, and it cost
+ * more than the opening did.  So this writes the four buffers directly.
+ *
+ * An array with no mask still takes its slots in the mask strides, one per
+ * axis of its own, zero.  Its own rank and not the kernel's: the generated C
+ * finds an array's mask strides at the sum of the ranks of the arrays before
+ * it, and an operand of lower rank than the kernel -- a row broadcast over a
+ * grid -- padded to the kernel's rank moved every mask after it.
+ */
+static VALUE
+packed_body (VALUE argument)
+{
+  open_state     *state   = (open_state *) argument;
+  int             count   = state->count;
+  int             i;
+  long            stride_slots = 0, mask_stride_slots = 0;
+  VALUE           pointers, strides, mask_pointers, mask_strides;
+  uint64_t       *pointer_slot, *mask_pointer_slot;
+  int64_t        *stride_slot, *mask_stride_slot;
+
+  for ( i = 0; i < count; i++ ) {
+    stride_slots += state->carrays[i]->ndim;
+    mask_stride_slots += state->carrays[count + i]
+                       ? state->carrays[count + i]->ndim
+                       : state->carrays[i]->ndim;
+  }
+
+  pointers      = rb_str_new(NULL, (long) (count * sizeof(uint64_t)));
+  mask_pointers = rb_str_new(NULL, (long) (count * sizeof(uint64_t)));
+  strides       = rb_str_new(NULL, stride_slots * (long) sizeof(int64_t));
+  mask_strides  = rb_str_new(NULL, mask_stride_slots * (long) sizeof(int64_t));
+
+  pointer_slot      = (uint64_t *) RSTRING_PTR(pointers);
+  mask_pointer_slot = (uint64_t *) RSTRING_PTR(mask_pointers);
+  stride_slot       = (int64_t *)  RSTRING_PTR(strides);
+  mask_stride_slot  = (int64_t *)  RSTRING_PTR(mask_strides);
+
+  for ( i = 0; i < count; i++ ) {
+    CArray   *ca = state->carrays[i];
+    ca_size_t own[CA_RANK_MAX];
+    char     *pointer = acquire_basis(state, i, own);
+    int8_t    k;
+
+    *pointer_slot++ = (uint64_t)(uintptr_t) pointer;
+    for ( k = 0; k < ca->ndim; k++ ) *stride_slot++ = (int64_t) own[k];
+
+    if ( state->carrays[count + i] ) {
+      CArray   *mask = state->carrays[count + i];
+      ca_size_t mask_own[CA_RANK_MAX];
+      char     *mask_pointer = acquire_basis(state, count + i, mask_own);
+      *mask_pointer_slot++ = (uint64_t)(uintptr_t) mask_pointer;
+      for ( k = 0; k < mask->ndim; k++ ) *mask_stride_slot++ = (int64_t) mask_own[k];
+    } else {
+      *mask_pointer_slot++ = 0;
+      for ( k = 0; k < ca->ndim; k++ ) *mask_stride_slot++ = 0;
+    }
+  }
+
+  {
+    VALUE result = rb_yield_values(4, pointers, strides, mask_pointers,
+                                   mask_strides);
+    state->body_done = 1;
+    return result;
+  }
+}
+
+/*
+ * Opens every array, yields what it opened, and closes them all on the way
+ * out -- including when the block raises.
+ *
+ * With four arguments the block is handed one basis hash per array, which is
+ * the form to read an array's opening in.  Given a fifth that is true, it is
+ * handed the four packed buffers a kernel passes to the C instead: pointers,
+ * strides, mask pointers, mask strides.
+ */
+static VALUE
+address_basis_open (int argc, VALUE *argv, VALUE module)
+{
+  VALUE arrays, writable_flags, box_start, box_count, packed;
+  open_state state;
+  int i;
+
+  rb_scan_args(argc, argv, "23", &arrays, &writable_flags, &box_start,
+               &box_count, &packed);
+  Check_Type(arrays, T_ARRAY);
+  Check_Type(writable_flags, T_ARRAY);
+  if ( NIL_P(box_start) != NIL_P(box_count) ) {
+    rb_raise(rb_eArgError, "a region needs both starts and counts");
+  }
+  if ( ! NIL_P(box_start) ) {
+    Check_Type(box_start, T_ARRAY);
+    Check_Type(box_count, T_ARRAY);
+    if ( RARRAY_LEN(box_start) != RARRAY_LEN(arrays) ||
+         RARRAY_LEN(box_count) != RARRAY_LEN(arrays) ) {
+      rb_raise(rb_eArgError, "one region per array is required");
+    }
+  }
+  if ( RARRAY_LEN(arrays) != RARRAY_LEN(writable_flags) ) {
+    rb_raise(rb_eArgError, "one writable flag per array is required");
+  }
+
+  /* Every argument is checked before the block below is allocated: a
+     refusal raises, and it must find nothing to free. */
+  for ( i = 0; i < (int) RARRAY_LEN(arrays); i++ ) {
+    VALUE   object = rb_ary_entry(arrays, i);
+    CArray *ca;
+    GetCArray(object, ca);
+    /* A view takes its mask from its parent when first asked for it; one
+       added to the parent after the view was made is not on ca->mask yet. */
+    ca_update_mask(ca);
+    verify_usable(object, ca, RTEST(rb_ary_entry(writable_flags, i)));
+    verify_mask_cells(object, ca);
+    verify_box(box_start, box_count, i, ca);
+  }
+
+  state.count         = (int) RARRAY_LEN(arrays);
+  state.slots         = state.count * 2;
+  /* Our own copy: the caller's Array can be emptied inside the block, and
+     the arrays it held are attached until open_ensure has run. */
+  state.arrays        = rb_ary_dup(arrays);
+  state.bases         = rb_ary_new_capa(state.count);
+  /* One allocation, carved up, rather than eight.  Every array here is the
+     same length in slots and lives exactly as long as the open, so there is
+     nothing for eight separate lifetimes to buy -- and this is a per-call
+     cost on a path whose whole point is to be cheap enough to cross often.
+     Zeroed once as a block, which is also what the slots want to start as:
+     a NULL array, a NULL root, not writable, not attached, no region. */
+  {
+    size_t n        = (size_t) state.slots + 1;
+    size_t pointers = ROUND_UP_8(n * sizeof(CArray *));
+    size_t chars    = ROUND_UP_8(n * sizeof(char *));
+    size_t sizes    = ROUND_UP_8(n * CA_RANK_MAX * sizeof(ca_size_t));
+    size_t ints     = ROUND_UP_8(n * sizeof(int));
+    size_t total = 2 * pointers + chars + 2 * sizes + 3 * ints;
+    char  *p;
+    state.block = ALLOC_N(char, total);
+    MEMZERO(state.block, char, total);
+    p = state.block;
+    state.carrays       = (CArray **)  p; p += pointers;
+    state.roots         = (CArray **)  p; p += pointers;
+    state.region        = (char **)    p; p += chars;
+    state.region_start  = (ca_size_t *) p; p += sizes;
+    state.region_count  = (ca_size_t *) p; p += sizes;
+    state.tier          = (int *)      p; p += ints;
+    state.writable      = (int *)      p; p += ints;
+    state.attached_root = (int *)      p;
+  }
+  state.box_starts    = box_start;
+  state.box_counts    = box_count;
+  state.body_done     = 0;
+  state.put_error     = Qnil;
+
+  for ( i = 0; i < state.count; i++ ) {
+    VALUE   object = rb_ary_entry(state.arrays, i);
+    CArray *ca;
+    GetCArray(object, ca);
+    state.carrays[i]  = ca;
+    state.writable[i] = RTEST(rb_ary_entry(writable_flags, i));
+    state.tier[i] = tier_for(ca);
+
+    if ( ca->mask ) {
+      CArray *mask = ca->mask;
+      state.carrays[state.count + i]  = mask;
+      state.writable[state.count + i] = state.writable[i];
+      state.tier[state.count + i] = tier_for(mask);
+    }
+  }
+
+  {
+    VALUE result = RTEST(packed)
+      ? rb_ensure(packed_body, (VALUE) &state, open_ensure, (VALUE) &state)
+      : rb_ensure(open_body, (VALUE) &state, open_ensure, (VALUE) &state);
+    RB_GC_GUARD(state.arrays);
+    return result;
+  }
+}
+
+/* Reports how an array would be opened, without opening it. */
+static VALUE
+address_basis_classify (VALUE module, VALUE object)
+{
+  CArray *ca;
+  VALUE   result;
+  int     tier;
+
+  GetCArray(object, ca);
+  tier = tier_for(ca);
+
+  result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("tier")), INT2NUM(tier));
+  rb_hash_aset(result, ID2SYM(rb_intern("entity")), ca_is_entity(ca) ? Qtrue : Qfalse);
+  rb_hash_aset(result, ID2SYM(rb_intern("stride_family")),
+               ca_is_stride_family(ca) ? Qtrue : Qfalse);
+  rb_hash_aset(result, ID2SYM(rb_intern("read_only")), ca_is_readonly(ca) ? Qtrue : Qfalse);
+  rb_hash_aset(result, ID2SYM(rb_intern("masked")), ca_has_mask(ca) ? Qtrue : Qfalse);
+  rb_hash_aset(result, ID2SYM(rb_intern("dim")), size_array(ca->dim, ca->ndim));
+  rb_hash_aset(result, ID2SYM(rb_intern("bytes")), LL2NUM((long long) ca->bytes));
+  rb_hash_aset(result, ID2SYM(rb_intern("data_type")), INT2NUM(ca->data_type));
+  return result;
+}
+
+/* ------------------------------------------------------------------- */
+/* Init_carray_address_basis                                            */
+/* ------------------------------------------------------------------- */
+
+void
+Init_carray_address_basis (void)
+{
+  VALUE mAddressBasis = rb_define_module_under(rb_cCArray, "AddressBasis");
+
+  rb_define_singleton_method(mAddressBasis, "open", address_basis_open, -1);
+  rb_define_singleton_method(mAddressBasis, "classify",
+                             address_basis_classify, 1);
+
+  rb_define_const(mAddressBasis, "TIER_ENTITY", INT2NUM(TIER_ENTITY));
+  rb_define_const(mAddressBasis, "TIER_STRIDE", INT2NUM(TIER_STRIDE));
+  rb_define_const(mAddressBasis, "TIER_XFER", INT2NUM(TIER_XFER));
+}