carray-jit 0.1.1 → 0.1.3

data/CHANGELOG.md

@@ -37,6 +37,860 @@ version you have and a newer one.
      a release needs is said in the gemspec, and an entry says so only
      when the answer changes. -->
 
+## 0.1.3
+
+- New: `CArray::JIT.call_provider` is asked at a `jit_call` site before
+  anything is compiled, and answering `nil` means "not mine, compile it". It
+  is handed the prototype, the block -- whose binding says which method and
+  which module the site is in -- and the names the declaration gave, and
+  answers anything that responds to `call`. The one client is carray-aot,
+  which builds these same sites into a shared object ahead of the program so
+  that a machine running that gem reaches no compiler; it is the position
+  `jit_extern` puts a function from a library in, said about a call rather
+  than about a name.
+
+- New: `CArray.jit_call(prototype) { ... }` compiles the block as a C
+  function and calls it where it stands, with the locals around it. The
+  declaration's parameter names are the join and do the work twice: they are
+  the body's parameters, so the block declares none, and they name the locals
+  the call reads -- `CArray.jit_call("void (*)(double *out, const double
+  *values, size_t n, size_t window)")` inside a method holding `out`,
+  `values`, `n` and `window`. In C a parameter's name in a prototype is
+  decoration; here it is the whole binding, and a declared name with no local
+  behind it is refused at the call rather than read as nil inside it. What it
+  saves over `jit_function` and a `call` is the argument list, which restates
+  the declaration in an order nothing checks; what it costs is reading those
+  locals through the block's binding, about 0.3 microseconds against a call
+  that costs several. Compiled once per call site, and `clear_registry`
+  reaches those as it reaches the rest.
+
+- New: `CArray::JIT::CFunction#c_source_as(symbol)` hands the compiled C over
+  under a symbol the caller picked, for a caller writing it into a file of
+  its own rather than letting this compile it -- the symbol this compiler
+  writes carries a digest of the body, which is right for an object in a
+  cache and wrong for one committed to a repository. A name C cannot spell
+  and a name in this compiler's own `carray_jit_` namespace are refused; a
+  name the C library already has is the caller's to avoid, since the prefix
+  that closes that hazard is what is being replaced. A function bound with
+  `jit_extern` has no C of its own and says so.
+
+- New: a parallel assignment is in the subset -- `a, b = b, a`, and the
+  `a, b = b, a + b` a recurrence advances by. Every value on the right is
+  settled before anything on the left is written, as in Ruby, so the
+  temporary that spelling saves no longer has to be written by hand. A cell
+  is a target as much as a name is (`a[i], a[j] = a[j], a[i]`), each value
+  keeps its own type and carries its mask. The readings that take a single
+  value apart are refused by name: `a, b = f(x)`, `a, b = [1, 2]`,
+  `a, *rest = ...`, `a, (b, c) = ...`, and a count that does not match.
+
+- New: a local array may be larger than a stack frame should hold, and its
+  shape may be written over an integer the block captured --
+  `CArray.double(n)`, which was refused. Either way the kernel allocates the
+  array once at its entry and frees it at its exit, so a constructor written
+  inside the cell loop is still one allocation; 4 KiB for one array and
+  16 KiB for one kernel's arrays together now say where an array lives rather
+  than whether it is allowed, and nothing is refused for its size. A kernel
+  whose arrays all fit in the frame emits the C it emitted before. Where the
+  length is one the kernel works out, every subscript on that axis is checked
+  where the cell is reached rather than as the block is read, and a C
+  function takes the array only through a pointer that declares no length
+  (`const double *v`, not `const double v[3]`). The same block at two lengths
+  is one compiled kernel: the length travels as an argument and is not in the
+  C. A shape that comes to zero or less raises `ArgumentError` when the
+  kernel runs, and an allocation the system refuses raises `NoMemoryError`,
+  both naming the array and what its shape came to. A `jit_function` body
+  allocates nothing -- it is called once per cell -- and refuses such an
+  array, naming the pointer parameter to take it through instead.
+
+- New: a kernel that carries masks takes a local array, which it refused
+  before. Every local array of such a kernel is declared with a shadow of one
+  byte a cell beside its cells, and a cell carries a mask the way a plain
+  local does: what the expression written into it carried. So a window copied
+  into a workspace keeps its holes. `w[k] = UNDEF` marks a cell and
+  `w[k] == UNDEF` asks about one; the zeroed spellings clear the shadow with
+  the cells, so a cell starts every pass present, while `CArray.empty` leaves
+  both unspecified. The shadow counts against the 4 KiB an array is held to
+  and the 16 KiB a kernel is, so an array that fits by its cells alone may
+  not fit once it carries masks. Two things still refuse such an array:
+  `sum`, `min`, `max` and `sort`, because what they should do with a missing
+  cell is not decided, and a C function, because a mask travels in no C
+  declaration -- both say so where they used to be refused for having no mask
+  at all. A kernel that carries no masks emits what it emitted before, and a
+  compiled function's body carries none at all.
+
+- New: an inner loop's range may be written over another index --
+  `3.times { |p| (p+1...3).each { |r| ... } }`, the shape a triangular loop
+  takes -- where that index is one of the loops around it. Forward
+  elimination and Neville's interpolation are the two this was wanted for,
+  and both now read as they do on paper rather than as a full loop with an
+  `if` inside it. The C was always emitted; what stood in the way was the
+  call, where each index's range is worked out so that a subscript can be
+  held to its array. A range over another index has no single pair of
+  numbers to be, so it is read as an interval, at its widest: every pass the
+  loop could take and sometimes more. Where that refuses a reach the loop
+  never makes, the message says which index the range was written over and
+  that it was read at its widest. A range over a local variable, a sibling
+  loop's index or a deeper one is still refused.
+
+- New: a local array may have more than one axis --
+  `CArray.double(3, 4)`, `CArray.new(:float64, [2, 3, 4])` -- in any of the
+  five places one can be made. The shape is written out as it always was, so
+  the strides are constants: `m[r, c]` is `m[(r) * 4 + (c)]`, one subscript
+  per axis, and each axis is checked against its own extent. That is what
+  flattening by hand gives up -- `m[r * 4 + c]` with a column of 4 reads a
+  cell of the next row and says nothing, where `m[r, c]` is refused by name
+  and a computed column raises. The stack limits count cells rather than
+  axes, so `CArray.double(32, 32)` is 8 KiB and past the 4 KiB an array is
+  held to. Handed to a C function the array goes as the flat run of cells it
+  is, row after row, so a `double[3][4]` reaches `const double a[12]` and the
+  length is matched over every cell. The four intrinsics still take one axis.
+
+- New: a `CArray.jit_function` body may make a local array and use
+  `sum`/`min`/`max`/`sort` over one, which completes the four entry points.
+  A body closes over nothing, so this is the only place scratch space could
+  come from other than an extra parameter -- and a signature settled
+  elsewhere, a callback's, has no room for one. The array is declared at the
+  head of the function, a recursive body gets one per call, and a body hands
+  one to another compiled function under the same rules a kernel does. The
+  helpers an intrinsic needs travel with the body: carried in its own file
+  when it is compiled alone, and merged into the kernel's preamble when it is
+  pasted, one helper per element type and length however many bodies want it.
+  The stack limits stay per function -- 4 KiB an array, 16 KiB a body -- and a
+  chain of pasted functions is not counted, so a deep chain stands as many
+  frames as it has; that is the bargain a deep recursion already takes. Still
+  excluded: more than one axis, and a contraction.
+
+- New: a local array may be handed to a C function -- one from
+  `CArray.jit_function` or `CArray.jit_extern` -- wherever the declaration
+  takes a pointer, from any of the four entry points that make one. What the
+  declaration says is matched as the block is read rather than at the call,
+  both the element type and the length being written in the block: an exact
+  element type, and at least as many cells as a sized declarator asks for.
+  A parameter that is not `const` may be written through, and the line after
+  the call reads what the callee left; the zeroed constructors still clear at
+  the line, so nothing carries into the next cell. Passing one array to two
+  parameters is fine, the declarations carrying no `restrict`. Note that a
+  borrowed function which keeps the pointer past the call is left pointing at
+  a stack frame that has gone, and that a declaration carrying no length --
+  `const double *x` -- gives nothing to check against. Still excluded when this landed: a `jit_function` body,
+  more than one axis, and a contraction; the first two arrived later in this
+  release, and a contraction is still refused.
+
+- New: a local array, and the four intrinsics over one, may be written in a
+  `CArray.jit_each`, `CArray.jit_map` or `CArray.jit_stencil` block as well as
+  in `CArray.jit_for`. These are the spellings that wanted one: a block with
+  no index cannot pick a row of a captured array, so a `jit_stencil` median
+  filter had nowhere to put its window -- it is now nine doubles on the cell's
+  stack and `sort(w)`. `border: :mask` takes one, the frame being marked
+  before the loop runs rather than carried through it. A name the block makes
+  an array under is refused where the block also closes over an array of that
+  name, since in these spellings an assignment writes that array's cell;
+  rename one of the two. A `jit_map` block may not end by making an array, its
+  value having to fit in a cell. Still excluded when this landed: a `jit_function` body, a
+  contraction, more than one axis, passing one to a C function, and a kernel
+  that carries masks; all but the contraction arrived later in this release.
+
+- New: `sum(w)`, `min(w)`, `max(w)` and `sort(w)` inside a `CArray.jit_for`
+  block, over a local array of one axis. They are bare calls, the compiler's
+  own names, rather than methods on the array -- `w.sum` is refused, and
+  `sum = 0.0` beside `sum(w)` is still a local. `sum` accumulates in the
+  element's computation type in index order; `min` and `max` skip a NaN
+  wherever it stands, and answer `NaN` for an array of nothing but NaN,
+  which is what `CArray#min` and `#max` answer (they answered the type's
+  limit until a later change in this release). `sort`
+  is a statement and orders the cells ascending with every NaN after every
+  number, as `CArray#sort` does; the relative order of `-0.0` and `0.0` is
+  not promised. Up to 16 cells it emits a comparator network with no branch
+  in it, above that an insertion sort. Excluded for now: a captured array
+  (a whole-array reduction is `CArray#sum`), more than one axis, two
+  arguments, boolean for all four, Complex for `min` / `max` / `sort`, and
+  the other entry points.
+
+- New: a `CArray` made inside a `CArray.jit_for` block is a C array on the
+  block's stack -- `w = CArray.double(9)`, `CArray.new(:int64, [256])` or
+  `CArray.empty(:float64, [9])`, read and written at a subscript. One axis,
+  with the length written out as an integer or integers joined by `+`, `-` and
+  `*`; the zeroed spellings are cleared each time the line runs, as Ruby makes
+  a fresh array there. A subscript is checked as the block is read where the
+  loop's range says it can be, and at the access otherwise, raising
+  `IndexError`. One array is held to 4 KiB of stack and one kernel's to 16 KiB.
+  Excluded for now: more than one axis, passing one to a C function, the other
+  entry points (`jit_each`, `jit_map`, `jit_stencil`, `jit_function`), a kernel
+  that carries masks, and CArray's Numo/NumPy spellings (`CArray.zeros`,
+  `CArray::Int64.empty`), which are refused with the carray spelling named.
+  Note `CArray.float` is float32 and `CArray.complex` is cmplx64.
+
+- New: `CArray#jit_init` fills an array from a formula over its indices, with
+  the block compiled: `CArray.int32(1000, 1000).jit_init { |i, j| (i + j) % 2 }`
+  is what the constructor block `CArray.int32(n, n) { |i, j| ... }` says,
+  without the Ruby call per cell. One parameter per axis, the block's value is
+  the cell, and the receiver comes back. It is the only entry point here that
+  is an instance method, because the array being written is the receiver: the
+  extents are its shape, so neither the index space nor the target is said
+  twice, where `CArray.jit_for(n, n) { |i, j| z[i, j] = ... }` says both. A
+  block outside the compilable subset raises rather than running the slow
+  loop, as every other entry point here does. Reach for it where the formula
+  will not go through whole-array arithmetic -- where it will, that needs no
+  compiler and is faster still.
+
+- New: a kernel can draw random numbers, from a `CArray::Rng`. `rand =
+  CArray::Rng.new(seed: 4)` and then `rand.random` in a `jit_for`, `jit_each`
+  or `jit_map` block draws one double in `[0.0, 1.0)` per cell, at about
+  0.8 ns; `random(rng: rand)` is the same draw spelled as
+  `CArray#random!(rng:)` spells it; `rand.randomn` is a standard normal, at
+  about 10 ns, and `randomn(rng: rand)` the same; and `rand.bits` is the raw
+  word a draw came from. All of them read one generator, so mixing them in a
+  kernel walks one sequence. The generator is CArray's and there is no entry point here: a
+  block closing over one is what a kernel needs. Each has its own state, so
+  two in one kernel are two sequences, and the state survives the call --
+  a second kernel carries on rather than starting again. `seed:` is data
+  rather than code, so every seed shares one compiled kernel. A sequence can
+  begin with `a.random!(rng: rand)` and continue in a kernel: those are the
+  same numbers one `random!` over both arrays would have laid down, because
+  CArray hands out the generator's C and this gem pastes it. Needs CArray
+  3.0.2 or newer, which is where `CArray::Rng` arrived; an older one is
+  refused where the block closes over the generator, and leaves every kernel
+  that draws nothing alone. A draw is refused inside `jit_function`, which
+  has nowhere to keep a state; take `int64_t state[4]` as a parameter there
+  and pass `rand.state`. Which draw lands in which cell is still the loop's
+  order, so where that has to be settled, fill an array with
+  `CArray#random!` before the call.
+
+- New: `CFunction#watching`, and `#clear_error` / `#report_error` beside it,
+  for the window in which a compiled function's address is lent to a C
+  library. `#call` answers for one call; a library given `#pointer` calls as
+  often as it likes, and `f.watching { ... }` is what puts the flag down
+  before that and raises what the body reported after it. A failure inside
+  the block outranks the library's own complaint about the stand-in it was
+  handed. Windows nest, and a `#call` made inside one leaves it armed.
+
+- New: `Math.gamma`, which is not `tgamma` and is not lowered to one: Ruby's
+  answer is tgamma with a table of exact values in front of it for a whole
+  number up to 23, and a `Math::DomainError` where tgamma answers a negative
+  whole number or negative infinity with a NaN. Both are reproduced -- the
+  table is written into the generated C, filled from the Ruby that compiled
+  it, as `Math::PI` is emitted as the double Ruby would have used, and the
+  error carries Ruby's class and Ruby's words. A cell with no value in it
+  does not raise. Measured over the whole numbers to 26, the halves, the
+  infinities and the overflow, a kernel and the Ruby loop agree in every bit.
+
+- New: `Math.erf` and `Math.erfc`, which are 1:1 with math.h's `erf` and
+  `erfc` -- Ruby calls those very functions, so a kernel and the Ruby loop
+  agree to the bit, infinities included. A float32 cell is worked on narrow
+  and so gets `erff`, as it gets `sinf`. There is no postfix `x.erf`:
+  `CArray::CoreExtensions` does not provide one, and this compiles the
+  refinement's names rather than inventing them.
+
+- New: `x.clamp(low, high)`, which answers the value or whichever bound it
+  ran past. The value and both bounds have to be one class: Ruby hands back
+  the receiver in one branch and a bound in the other, so `1.clamp(0.0, 3.0)`
+  is an Integer and `5.clamp(0.0, 3.0)` a Float, and no type settled before
+  the loop runs is both -- the refusal says which way round it is and what to
+  write. Two widths of one class are not that case, so a float32 cell keeps
+  its width. What Ruby raises `ArgumentError` for is raised here too: bounds
+  the wrong way round, and a NaN that cannot be ordered. The class is Ruby's
+  and so are the words for the first; for the NaN the message names the
+  reason rather than the value, since what comes back from a kernel is a code
+  and not a number. A cell with no value in it does not raise. The range
+  form, `x.clamp(0.0..1.0)`, is not in the subset -- two bounds are two
+  bounds.
+
+- New: a compiled function may take and return a C99 complex --
+  `CArray.jit_function("double _Complex step(double _Complex z)") { |z| z * z
+  + Complex(0.0, 1.0) }`. `double _Complex`, `float _Complex` and
+  `<complex.h>`'s `double complex` all read, by value or as a pointer, where
+  `double _Complex v[]` takes a `cmplx128` array as `double v[]` takes a
+  `float64` one. A kernel calls such a function as C calls it. A call from
+  Ruby goes through a second entry point compiled beside the body, since
+  Fiddle has no type to carry a complex by value in; it calls the body rather
+  than repeating it, so `f.call` and `f.block.call` stay the same body run
+  two ways. A function bound with `jit_extern` and declared with a complex is
+  callable from a kernel but not from Ruby -- there is no source here to
+  compile an entry point beside -- and says so.
+
+- New: a `jit_function` body may take an unsigned 64-bit value by parameter --
+  `CArray.jit_function("size_t stride(size_t n, size_t width)") { |n, w| n * w }`
+  -- where before only a pointer to one could be taken. The value arrives
+  whole above 2^63 and the arithmetic on it is unsigned, wrapping at the width
+  as CArray's own `uint64` operators wrap. A kernel's captured scalars are
+  unchanged: those travel in the kernel's own buffers, which carry doubles,
+  int64s and complexes.
+
+- New: `x.nan?` and `x.finite?`, which compile to C's `isnan` and `isfinite`
+  and answer what Ruby answers. `nan?` is a Float's question: an Integer and
+  a Complex have no method by that name and raise `NoMethodError` in Ruby, so
+  a kernel refuses both rather than answering false. `finite?` answers for an
+  Integer (true, whatever it holds) and for a Complex (both parts finite, as
+  Ruby asks it) as well as for a Float. `infinite?` is refused: Ruby answers
+  it with nil, 1 or -1 rather than true or false, and a kernel has no nil to
+  answer with -- the message names `x.abs == Float::INFINITY`, or
+  `x == Float::INFINITY` where the sign is the question.
+
+- New: the operator assignments -- `+= -= *= /= %= **= &= |= ^= <<= >>=` --
+  on a local, on a cell (`out[i] += e`, `work[i, k] += e`, a scatter such as
+  `counts[bin[i]] += 1`), on a CScalar and through a `jit_function`'s pointer
+  parameter. Each is read as the assignment it stands for, `x = x + e`, so
+  the type rules, the mask propagation and the fold that splits an
+  accumulator into partial sums are the ones already there: a reduction
+  written `total += values[j]` is still split. `||=` and `&&=` are refused,
+  being about whether a value is nil or false rather than about arithmetic.
+
+- New: an inner loop counts by a stride, written the way an extent writes
+  one: `(n-1).step(0, -1) { |k| ... }` is a downward sweep and
+  `(0...n).step(2) { |k| ... }` a stride of two. `step` includes the index it
+  is given, as Ruby's does, where a `...` range excludes it, and the stride
+  is a literal because it is what says which way the loop runs. This is the
+  other half of a row of workspace -- filling one and walking back down it no
+  longer needs `k = width - 1 - t`, which made the position a value the
+  kernel worked out and so put a bounds test on every cell of the sweep: 0.41
+  ns/cell against 0.24 for the same sweep written with `step`. An accumulator
+  is split into partial sums only for a loop counting by one; a stride keeps
+  the serial chain, and so keeps Ruby's order. `downto`, `upto` and
+  `reverse_each` are refused by name, naming `step` as what to write.
+
+- New: an inner loop's index may address a write, so a cell can be given a
+  row of workspace -- `(0...width).each { |k| work[i, k] = ... }` fills it,
+  and `work[i, k]` reads it back inside the same cell. That is what an
+  algorithm needing a few numbers per cell is written with: a small dense
+  solve, a tableau, a sweep and the pass back down it, in one kernel rather
+  than in several that each pay a call. The cell is bounds-checked before the
+  kernel runs, as one addressed by `i` is. Inside the row the body may do as
+  it likes -- sort it, walk it backwards, write at a position it works out --
+  which is what a median filter needs and what no extra axis can say. Reading
+  an array the kernel writes through an inner index is still refused where
+  the read leaves the cell the outer indices picked: a read carrying an inner
+  index addresses every axis some write walks with an outer index with that
+  same index, at whatever offset, or it reaches cells another outer iteration
+  owns. Where the sweep can be said as an extra axis instead --
+  `jit_for(rows, 1...width)` -- that remains the faster form once the rows
+  are long.
+
+- New: a function compiled with `CArray.jit_function` may call another one
+  compiled with `CArray.jit_function`, by the name the block reaches it by --
+  `hypot = CArray.jit_function("double (*)(double, double)") { |a, b|
+  root.call(a * a + b * b) }`. The called body is pasted into the caller's C
+  and reached by symbol, so what comes back is still one self-contained
+  object with one address, and a chain of any depth arrives together with the
+  messages its bodies raise. Everything else a body closes over is refused as
+  before -- a number, an array, and a function bound with `jit_extern`, which
+  is only an address and has nowhere in a compiled object to live. The name
+  may be a constant as well as a local, which is what lets a method reach
+  one: `def` closes over nothing.
+
+- New: `CArray::JIT.contraction_of` returns the number that multiplies the
+  product as `:scale`, which is 1 where there is none, so
+  `a[i,k] * b[k,j] * 2.0` comes back as its two terms and 2.0 rather than as
+  nil. A number is not a term -- it has no indices and no cell -- but it is
+  not a reason to give up on the terms either, and a caller that takes them
+  apart puts it back. Written out or closed over is the same number; anything
+  a name holds that is not a Numeric is still nil. This shipped in 0.1.2,
+  whose entry describes the same two methods without mentioning it.
+
+- Change: this gem no longer builds a C extension, so installing it needs no
+  compiler for itself -- one is still needed at run time to compile a kernel.
+  The addressing it used to carry is `CArray::AddressBasis`, in carray, which
+  is where the knowledge about carray's views belonged; `CArray::JIT::Access`
+  remains as an alias for this release. carray 3.0.2 or newer is required,
+  which the gemspec already asked for.
+
+- Change: `CArray.jit_for`, `CArray.jit_each` and `CArray.jit_map` are this
+  gem's alone. From CArray 3.0.2 they are not defined until
+  `require "carray/jit"` has run, so a program that calls one without it gets
+  `NoMethodError` rather than CArray's `NotImplementedError`. With the gem
+  required nothing changes, against any CArray this gem accepts.
+
+- Change: `CArray::JIT::CFunction#name` answers the name the declaration gave
+  -- `:square` for `CArray.jit_function("double square(double x)")` -- and
+  the new `#symbol` answers the name in the object, which for a compiled
+  function carries a digest of the body. It used to answer whichever of the
+  two its constructor was handed: the declared name for a function bound with
+  `jit_extern`, the symbol for one compiled from a block. Code reading
+  `#name` to reach or paste a function wants `#symbol`; code putting it in a
+  message wants `#name`, which is `nil` where the declaration named no
+  function. `#to_s` now prints the declaration rather than the symbol.
+
+- Change: a compiled function whose body has failed does no more work until
+  its flag is put down again -- it returns 0 without running, and one
+  declared `void` leaves its out-parameters alone. Before, it reported the
+  first failure and then answered normally, so a library that kept calling
+  could converge on values it was no longer entitled to. Nothing changes for
+  a caller using `#call`, which puts the flag down for each call; a caller
+  holding `#pointer` opens a window with `#watching` or `#clear_error`. A
+  kernel is unaffected: it is handed its own error slot and never reaches
+  this flag.
+
+- Change: naming a contraction's axes now replaces the convention rather than
+  adding a clause to it. `CArray.jit_contract(:i, :j) { ... }` names all of
+  the result's axes, so every index left out of the list is summed at however
+  few positions it sits -- where before, one sitting at a single position was
+  refused as a free index with nowhere to go. So `jit_contract(:i) { |k|
+  a[i,k] }` is the row sums, and `contract_terms(terms, free: [])` over a
+  product is its total; both were refused. (`a.sum(axis: 1)` remains the
+  faster way to write a reduction, being one.) With nothing named the
+  convention is unchanged: a repetition is a sum and a single position is
+  free. What this makes exact is the correspondence with einsum's two modes,
+  the argument list being the arrow's right-hand side; `"ik->i"` and
+  `"ik,kj->"` can now be said.
+
+  Where the block assigns into an array of yours, an axis on the left-hand
+  side that the list leaves out is still refused -- it is the list falling
+  short of the result rather than an index to sum, and the left-hand side is
+  the one place that can be seen. The message says so in those terms now.
+
+- Change: `min(w)` and `max(w)` over a floating local array answer `NaN` when
+  every cell is `NaN`, where they answered `Infinity` and `-Infinity`. This
+  follows CArray 3.0.2, which made the same change to its own `min` and `max`;
+  the gemspec already asks for that version. An array holding at least one
+  number answers as before, a `NaN` still losing to any number, and an integer
+  local array is unchanged.
+
+- Change: `CArray.jit_contract` refuses an index that stands inside a
+  subscript the kernel works out -- `a[i, idx[k]] * v[k]` -- saying that a
+  contraction counts positions and this one is a position of `idx`. It was
+  read as an index appearing once, so the sum the notation asks for did not
+  happen and the result came back a whole matrix. Write such a gather with
+  `CArray.jit_for`.
+
+- Change: an indexed kernel (`CArray.jit_for` and the rest) refuses an
+  operand it cannot walk -- a gather, a lazy array -- that is a view of an
+  array the same kernel writes, naming `a[order[i]]` as the spelling that
+  means something. Such an operand is copied before the loop and put back
+  after it, so the loop read cells that had stopped being current and a
+  direct write to the same array was dropped at the end.
+
+- Change: arithmetic between two booleans -- `flag[i] * flag[i]`, `+`, `-`,
+  `/`, `%` -- raises `CArray::JIT::Unsupported` where the operator stands,
+  as `true * true` raises in Ruby. Used as a condition it compiled and ran.
+  `&`, `|` and `^` on booleans are unchanged.
+
+- Change: a captured Integer above 2**63-1 meeting an integer is refused,
+  where before it was absorbed into that integer's width and computed from a
+  wrapped value. CArray refuses the same expression whatever the array's own
+  type is -- `CArray.uint64(1) { 5 } + 2**63` raises `bignum too big to
+  convert into 'long long'` -- and this follows it: a bare Integer brings no
+  width, and the message names `CScalar.uint64() { big }`, which a kernel reads
+  as the one-cell array it is. A Float or a Complex on the other side is
+  unaffected, and so is a capture that fits an int64. A loop that adds such a
+  capture to an accumulator is refused for the same reason: state the width
+  once with a CScalar, for the seed and for the value.
+
+- Change: a `CArray.jit_each` or `CArray.jit_map` block whose *only* array is
+  handed to a C function whole is now refused, naming the array and saying
+  that it does not settle how many cells there are to compute.
+  `CArray.jit_map { DOT4.call(w, w) }` used to answer an array as long as `w`
+  -- a length that came from an array nobody walks -- and the same block under
+  `jit_each` failed inside Fiddle with `unknown symbol "ca_call_cslab_0_r"`.
+  `CArray.jit_for` with a count takes these, as it always did.
+
+- Change: a block parameter that names a loop index is refused when the
+  generated C already uses that name for a captured array (`p_a`, `m_a`,
+  `a_s0`, `a_ms0` or `a_n0` for an array `a`), or when it contains `__` or
+  starts with `carray_jit_`. Rename the index.
+
+- Change: a `CArray.jit_function` body that subscripts a pointer parameter
+  with a literal outside the length its declaration gave -- `v[7]` or
+  `v[-1]` against `double v[2]` -- raises `CArray::JIT::Unsupported` as the
+  body is read. It compiled, and wrote or read past what the caller was
+  held to. A computed subscript, and any subscript on a pointer declared
+  without a length, are unchecked as before.
+
+- Change: an extent that counts down as a `Range` -- `(n-2)..0` -- raises
+  `CArray::JIT::Unsupported` naming `(n-2).step(0, -1)`, the spelling Ruby
+  iterates backwards with. Ruby gives such a Range no elements, so the
+  kernel ran no passes and said nothing, which is what the guide says this
+  refusal exists to prevent. An empty range whose ends agree (`0...0`) is a
+  count of zero as before.
+
+- Change: a body compiled with `CArray.jit_function` or `CArray.jit_call` may
+  call a function bound with `jit_extern`. It was refused -- a borrowed
+  function is only an address, and a compiled body has no `functions` buffer
+  to take one in -- but an address is not what a body needs from it. It needs
+  the name, which is what the declaration states and what a linker or a
+  loader resolves; `jit_extern` opened the library to find the function, so
+  the symbol is in the process by the time the body is compiled. The
+  generated file declares it (`double j0(double);`) and calls it by name. A
+  kernel is unchanged and still takes the address through its buffer, which
+  is what a kernel has and a body has not. A file built ahead of the program
+  links the library the usual way: one that is not linked by default is the
+  caller's to add.
+
+- Change: `require "carray/jit/call"` defines `CArray.jit_call` without
+  loading the compiler, and the compiler is required at the first call site
+  no provider answers. A program whose sites were all built ahead of it --
+  by carray-jit-aot -- never loads the analyzer, the generator or the cache
+  at all, where before it loaded them and reached none of them.
+  `require "carray/jit"` loads everything as it did, and a program that
+  knows nothing about this sees no difference.
+
+- Change: a subscript that walks with one index and adds another --
+  `a[i + r]`, `r` an inner loop's index -- is refused as the block is read,
+  with a message that says so and that the sum put in a local first
+  (`k = i + r`, then `a[k]`) is checked at each cell and runs. It was
+  refused at the call, for a reason about an inner loop's range. The
+  exception is `CArray::JIT::Unsupported`, as it was.
+
+- Change: a kernel or `jit_function` body that reads a local after an inner
+  loop's block in which the local was first assigned, or after a `while` in
+  which it was first assigned, is refused with a message naming the local.
+  These did not compile before either, failing in the C compiler instead.
+  Give the local a value before the loop.
+
+- Change: a local assigned before the summand of a `CArray.jit_contract`
+  block is refused saying so -- a contraction is one expression, which is
+  why it takes no local array either. It was refused as "`u` is read before
+  it is assigned", about a local assigned on the line above.
+
+- Change: the refusal for a `CArray.jit_stencil` writing into a view of an
+  array it reads says that the two are views of one array and that the test
+  is the storage rather than the cells, so two slabs that share none are
+  refused too, and names the copy to read from. It said a stencil writes
+  into an array of its own, which of two slabs is not true.
+
+- Change: the refusal for a block whose source cannot be read names
+  `RubyVM.keep_script_lines = true` and `CArray::JIT.compile`, which takes a
+  kernel as text. It named `source:`, which is a keyword no entry point
+  takes; the guide said the same.
+
+- Change: `CArray#jit_init` given a block that takes a splat or an optional
+  parameter says so, where it said "the block names -1 indices".
+
+- Change: a keyword in value position is named as it was written --
+  `unless` in `CArray.jit_map { unless a > 1.0 then ... end }` says
+  "`unless` -- write it as `if` with the condition negated", where it said
+  "unsupported expression Unless". Statement position already did.
+
+- Change: a statement outside the subset is named as it was written --
+  ``got `unless` -- write it as `if` with the condition negated`` rather than
+  `got Unless`, which was this compiler's reading of it and not anything
+  anyone typed. The list of what a body may hold was written out in two
+  places and they had come apart; it is one place now.
+
+- Change: the three names left in Ruby's `Math` say why they are not lowered
+  rather than saying that C has no counterpart, which was untrue of all of
+  them -- `lgamma`, `frexp` and `ldexp` all exist. `Math.lgamma` and
+  `Math.frexp` each answer with a pair, and a cell holds one number;
+  `Math.ldexp` takes an exponent where a math call here computes every
+  argument in the type of its result. A name Ruby's `Math` does not have says
+  that instead of guessing at a reason.
+
+- Change: a compiler this process cannot find -- `CARRAY_JIT_CC` naming
+  something that is not there -- raises `CArray::JIT::CompilationError`
+  saying so and naming the variable, where it raised `Errno::ENOENT` from
+  the spawn with the program name and nothing else.
+
+- Change: a cache directory owned by another user is refused, as one other
+  users can write to already was; everything in it is `dlopen`ed. A cache
+  root that is a symlink is followed as before, and the owner of the
+  directory it lands on is what is asked about. Set `CARRAY_JIT_CACHE` to a
+  directory of your own where this refuses.
+
+- Change: the docs now say what a compare-exchange costs under a mask. A
+  swap writes two cells where an ordinary assignment writes one, and a sort
+  runs one over every cell repeatedly, so a single missing cell spreads
+  across the row -- the ordinary rule for a branch decided by a missing
+  cell, at an unusually high gain. A sort written by hand is not refused
+  the way `sort` on a local array is, so ask `a[i] == UNDEF` first and
+  decide it.
+
+- Change: the docs now say what a branch not taken costs under a mask. A
+  branch decided by a missing cell masks what it writes; taking the other
+  path writes nothing, so a conclusion reached that way -- `found` left at
+  -1 for a row whose only candidate was masked -- is reported as an ordinary
+  value. Ask about the mask with `a[i] == UNDEF` where that matters.
+
+- Change: the docs now say that a negative Float to a fractional power is
+  `NaN`, as `pow` and CArray answer, where Ruby answers a Complex. This was
+  already the behaviour; a whole-number exponent or a non-negative base is
+  Ruby's number.
+
+- Change: the docs now say that an Integer compared with a Float is
+  compared as two doubles, as CArray compares them, so past 2^53 the answer
+  can differ from Ruby's exact comparison. This was already the behaviour;
+  below 2^53 nothing differs.
+
+- Change: the docs now say that `Math.sqrt`, `log`, `log2`, `log10`, `asin`,
+  `acos`, `acosh` and `atanh` answer `NaN` outside their domain, as `math.h`
+  does, where Ruby raises `Math::DomainError`, and that `Math.sqrt(-0.0)` is
+  `-0.0`. This was already the behaviour. `Math.gamma` still raises as Ruby
+  does. Test the argument in the block where it may leave the domain.
+
+- Fix: a loop whose bound is an unsigned parameter -- `size_t n` and its kin
+  -- runs the passes Ruby runs. The counter is an `int64_t` and the bound was
+  compared against it uncast, so C converted the *counter* to unsigned
+  instead: `(-3...n).each` over `n = 4` ran no passes where Ruby runs seven,
+  and answered without saying anything. A count that never goes below zero
+  was unaffected, which is every `n.times`. The cast is written down now, so
+  the generated C also compiles clean where it carried `-Wsign-compare`
+  before.
+
+- Fix: a `CArray.jit_each` or `CArray.jit_map` pass that reads a view of an
+  array it also writes -- two blocks that share cells, a transpose written
+  over itself, a gather held in `g` and written back as `src = g + 1.0` --
+  reads the values the expression started with, as Ruby and CArray's own
+  operators do. Such an operand was read as the pass went, so it came back
+  holding the kernel's own output: `hi = lo * 2.0` over overlapping blocks
+  gave all zeros, and a gather over 20000 cells was wrong in 8192 of them.
+  It is copied once before the loop instead. `a = a + 1.0`, and views that
+  share a root without sharing a cell, are untouched.
+
+- Fix: `CArray.jit_contract` takes a summand that calls a function made with
+  `CArray.jit_function` or `CArray.jit_extern`, which the docs say it does;
+  it was refused as an unsupported method. What the function hands back
+  types the result the contraction is collected into.
+
+- Fix: a cell of a local array written under an `if` or a `while` whose
+  condition read a missing cell is masked, as a plain local and a cell of an
+  array now are. It was left present deliberately; the rule the docs give
+  for it is the one the other two keep.
+
+- Fix: a local assigned under an `if` or a `while` whose condition read a
+  missing cell is masked, as a cell written there already was. It came back
+  a number like any other, so `found = -1; ...; if a[i, j] > x then found =
+  j end; out[i] = found` reported a position found under a mask. A condition
+  that asks about the mask itself (`a[i] == UNDEF`) still masks nothing.
+
+- Fix: a build no longer fails with "could not load freshly compiled" when
+  another process evicts its object in the moment between the build and the
+  load. It opens the object before publishing it to the cache. Reachable
+  where `CARRAY_JIT_CACHE_LIMIT` is smaller than the number of processes
+  building at once: with five of them, a limit of 2 lost every one.
+
+- Fix: a build whose compile fails leaves no `.c` behind in the cache. Such
+  a file was never looked up -- a cache hit is an object -- and eviction
+  passes over it, so one stayed for good, and one more for every kernel of
+  every run against a toolchain that cannot compile.
+
+- Fix: two threads of one process compiling at the same time no longer
+  raise `Errno::ENOENT`; three threads in four did. A build now takes a lock
+  for the length of the compile, so the second thread finds the object the
+  first one left and reuses it rather than building its own. Compiling two
+  different kernels in two threads is that much less parallel -- four of
+  them took 970 ms here against 800.
+
+- Fix: multiplying two Complex numbers, or a real number by a Complex
+  (`x * z`), gives Ruby's answer where an infinity meets a zero:
+  `0.0 * Complex(Float::INFINITY, 0.0)` is `0.0+0.0i`, where it was
+  `NaN+NaN*i`. Finite products are unchanged, `cmplx64` included, and
+  `z * x` still scales each part as it did.
+
+- Fix: `%` by a float zero raises `ZeroDivisionError`, as Ruby's does --
+  `x % 0.0`, `x % -0.0`, an integer cell `% 0.0` -- in a kernel and in a
+  `CArray.jit_function` alike. It answered `NaN`, which is what CArray's `%`
+  answers and not what the docs promised. A float `/` by zero is still an
+  infinity, as it is in Ruby.
+
+- Fix: `min(w)` and `max(w)` over a floating local array keep the first of
+  two cells that compare equal, as CArray's `min` and `max` do, so `0.0`
+  and `-0.0` come back in the order they stood; which zero came back was
+  left to the C library. NaN is still skipped, and an array of nothing but
+  NaN still answers `NaN`.
+
+- Fix: `floor`, `ceil`, `round`, `truncate` and `to_i` on a Float raise
+  `FloatDomainError` for a NaN or an infinity, as Ruby does, and `RangeError`
+  for a result past int64; they gave a clamped or arbitrary number. Written
+  straight into a float cell, or returned from a `CArray.jit_function`
+  declared `double`, the result is Ruby's however large -- `1e20.floor` is
+  `1e20`. A loop doing little but rounding runs slower for the check.
+
+- Fix: `.abs` on an integer compiles in `CArray.jit_for`, `CArray.jit_map`,
+  `CArray.jit_function` and the other entry points; it raised
+  `CArray::JIT::CompilationError` unless the kernel also allocated a local
+  array. `(-2**63).abs` in an int64 wraps to itself, as other int64
+  overflow does. Float and complex `.abs` are unchanged.
+
+- Fix: an inner loop stepping by more than one over a start written over
+  another index -- `2.times { |p| (p...8).step(3) { |k| ... } }` -- is held
+  to the cells every pass reaches, not only the pass from the earliest
+  start. A subscript one pass took past the end of an array was let through
+  and written; it is now refused as the call is prepared. A step of one, and
+  a start that does not move, are read as before.
+
+- Fix: a local array whose shape is written over captured integers --
+  `CArray.double(n, m)` -- raises `ArgumentError` when its lengths each fit
+  but their product does not count in bytes. Such a product wrapped to a
+  small number, the kernel allocated that, and subscripts in range on every
+  axis wrote past it. A shape of one axis, or of lengths whose product
+  fits, is unaffected.
+
+- Fix: `CArray::JIT.clear_registry` now forgets the functions
+  `CArray.jit_function` compiled, as it already did kernels, so the next
+  call reads them back from the cache on disk.
+
+- Fix: a block run through `eval` -- in a console, or from code that builds
+  its kernels as text -- no longer stays in memory for the life of the
+  process once nothing refers to it. On Ruby 3.2 it still does.
+
+- Fix: a kernel over a masked array read and wrote the wrong cells of its
+  mask, and on a large enough array wrote past the end of it, when an
+  unmasked operand whose number of axes differs from the kernel's -- a row
+  added across a grid, or a contraction's operand -- sorted by name before
+  the masked one. Kernels whose operands all share the kernel's rank, and
+  kernels over no masked array, were not affected.
+
+- Fix: a local array indexed by an inner loop whose range is not known until
+  the kernel runs -- a bound that is a captured integer, and now a range
+  written over another index -- is checked where the cell is reached. Such a
+  subscript was checked nowhere: the check that reads the loop's range could
+  not settle it, and the check at the access did not cover an index, so a
+  write past the end of the array went into the block's stack frame. It now
+  raises `IndexError` as every other unsettled subscript does.
+
+- Fix: in a `CArray.jit_each`, `CArray.jit_map` or `CArray.jit_stencil`
+  block, an array handed to a C function whole -- and read in no other way --
+  is no longer lined up with the operands. One whose length differed from
+  theirs used to fail with `broadcast_to: cannot broadcast axis 0`, which
+  named an axis and said nothing about the call it was written for; a set of
+  weights four cells long may now stand beside a thousand cells of operand.
+  What decides which arrays those are is the declaration, not the spelling: a
+  parameter taking a number by value reads the cell, so that array is walked
+  and lines up as before, and an array both read by cell and handed over is
+  an operand too.
+
+- Fix: a local in a kernel or `jit_function` body, or a captured variable
+  starting `carray_jit_`, may be given a name the generated C also uses -- a
+  kernel parameter such as `error`, a C keyword such as `int`, `a_n0` beside a
+  captured array `a`, or a name containing `__`. It failed to compile, raised
+  an `IndexError` for an index in range, or shared its value with another
+  name; it is now renamed in the generated C only.
+
+- Fix: two inner loops in one kernel or `jit_function` body may assign a
+  local of the same name, at one type or two, and a local assigned inside a
+  `while` may be read after it when it was also assigned before it. The
+  first failed in the C compiler or was refused as changing type; the second
+  failed in the C compiler.
+
+- Fix: a loop in a `jit_function` body, and a `while` or inner loop in a
+  kernel whose body held the kernel's first way to fail, kept running after
+  an integer division by zero, a computed index out of range, `clamp` or
+  `Math.gamma` had reported a failure -- so a `while` decided by the value
+  handed back could run forever. Such a loop now leaves at the head of its
+  next pass, and the call raises as it already did.
+
+- Fix: `CArray.jit_each` and `CArray.jit_map` no longer refuse a block that
+  hands a one-cell array to a C function. Those entries line their operands up
+  with the expression's shape, and an array passed to a pointer parameter was
+  lined up with the rest -- so a one-cell array holding state came back
+  stretched and read-only, and the copy-back after the call raised `can not
+  modify read-only array`. An array handed over by address is passed whole
+  rather than walked, so it is left as it is now. `jit_for` was never
+  affected, and a `CScalar` was affected the same way an array was.
+
+- Fix: a captured Integer above 2**63-1 reaches a kernel whole. It was packed
+  into the int64 slot the kernel reads its integers from, which took the value
+  modulo the width and said nothing: `big / 3`, `big > 100` and `big * 1.0`
+  answered from a negative number, while `+` and `*` came out right and hid it.
+  Such a capture is a uint64 now -- the width CArray has for those values --
+  and a value neither an int64 nor a uint64 holds is refused where the capture
+  is read, naming the value.
+
+- Fix: a C declaration written with `ptrdiff_t` compiles. `size_t` and the
+  other `<stddef.h>` names have read since 0.1.0, but the C generated for a
+  body that took one declared no such type, so `CArray.jit_function("ptrdiff_t
+  (*)(ptrdiff_t)")` failed in the C compiler with `unknown type name`.
+  `size_t` was unaffected, by luck rather than by design.
+
+- Fix: two inner loops in one body may both be written `{ |k| ... }`. They
+  are one name in the block and were one index here, so the second loop's
+  range replaced the first's and a reach was checked against the wrong one --
+  `a[k-1]` in a loop from 1 was refused for starting at 0 once a later loop
+  started there. Each loop now counts in an identifier of its own, and the
+  messages go on speaking the name the block wrote.
+
+- Fix: a block holding a character outside ASCII no longer raises. The file a
+  block sits in was read with `File.read`, which uses
+  `Encoding.default_external` -- a setting that has nothing to do with a
+  source's encoding: on a machine with no locale set it is US-ASCII, and the
+  file came back as its own bytes under a tag that the first `rstrip` on a
+  line holding a comment in Japanese raised on. The file is now read as bytes
+  and given the encoding the parser gave it: UTF-8, or what a `coding` magic
+  comment names on the first line or on the second where a shebang takes the
+  first.
+
+
+## 0.1.2
+
+- New: `CArray.jit_contract` takes the result's axes as symbols, which says
+  which indices are free: `CArray.jit_contract(:p) { |k| x[p,k] * y[p,k] }` is
+  one number per point, and `CArray.jit_contract(:a) { q[a,a] }` is the
+  diagonal rather than the trace. A named index stays free however often it
+  appears, which is what an index that numbers things -- a point, a sample, a
+  batch -- does. What a repetition means is unchanged, so the whole rule is
+  that an index which repeats is summed and one that is named is free. Naming
+  the axes also states their order. With no arguments nothing changes.
+
+- New: `CArray::JIT.contract_terms` runs the contraction a structure describes
+  rather than one a block writes --
+  `CArray::JIT.contract_terms([[a, [:i, :k]], [b, [:k, :j]]], free: [:i, :j])`
+  is a matrix product -- and `CArray::JIT.contraction_of` reads a block and
+  returns the terms it is a product of, or nil when it is not one. They are
+  `jit_contract` with the block taken out of the middle, for a caller that
+  rearranges a contraction before running it: the terms are compiled by the
+  same analyzer under the same rules, so `free:` is required and an index that
+  is not named must appear at more than one position.
+
+- New: `CArray::JIT.cache_root = "path"` puts an application's compiled
+  kernels somewhere of its own, rather than in the cache shared under the home
+  directory. Say it before the first kernel is compiled; the path is expanded
+  where it is given. `CARRAY_JIT_CACHE` and `CARRAY_JIT_NO_CACHE` still come
+  first, and `nil` restores the default.
+
+- Change: a contraction's sum is split into partial sums, as `jit_for`'s
+  reduction and CArray's own reduce kernels are, which makes `jit_contract` as
+  fast as the same loop written with `jit_for` rather than three times slower.
+  A floating-point contraction therefore answers what the split accumulation
+  answers -- usually the more accurate number, never the one a serial Ruby
+  loop gives. `CArray::JIT.reassociate = false`, or `CARRAY_JIT_REASSOCIATE=0`
+  for a whole process, asks for the serial order; `jit_contract` takes no
+  per-call licence. Integer contractions are unaffected.
+
+- Change: `CArray.jit_contract` sums an index that repeats however often it
+  repeats, rather than refusing more than two positions. `q[i,i,i]` is the sum
+  along a cube's long diagonal, and `a[i,k] * b[k,k]` sums `k` at three
+  positions across two arrays. Nothing that compiled before compiles
+  differently: what changes is that these are accepted instead of raising
+  `CArray::JIT::Unsupported`.
+
+- Fix: a contraction with nothing to assign into is collected into the type its
+  summand computes in. `CArray.jit_contract { |i, j, k| a[i,k] * b[k,j] }` over
+  float32 arrays came back int64 with every value truncated; over uint64 it came
+  back int64 and wrapped; over cmplx64 it raised. The assigned form -- the same
+  contraction written `c[i,j] = ...` -- was right throughout, and `jit_for`,
+  `jit_each` and `jit_stencil` were never affected.
+
+- Fix: a contraction that writes an array it also reads is refused when the
+  block gave that array two names -- `y = x`, or a view of something being
+  read -- as it always was when one name was used for both. It compiled and
+  returned an answer that depended on the order the cells were reached in.
+  `CArray::JIT.contract_terms` refuses `into:` for the same reason. Write it
+  with `jit_for`, which is what a recurrence is for.
+
+- Fix: `CArray.jit_stencil(source, into: source)` is refused rather than
+  computing a pass whose cells feed the ones after them. A window that reaches
+  nowhere -- one that reads only the cell it is on -- still writes in place, as
+  it always did.
+
+- Fix: assigning to a loop index inside a kernel is refused. `jit_for(3) { |i|
+  i = 2; out[i] = ... }` assigned to the counter, so the loop walked somewhere
+  else -- outside the array, for a value outside its extent -- while Ruby reads
+  the same line as rebinding the parameter and runs the loop unchanged. Use a
+  local of another name; nothing that has an index only on the right changes.
+
+- Fix: an index named after something the generated C already uses is refused
+  where it is written rather than by the compiler. `jit_contract { |int, j, k|
+  ... }` reached clang as a declaration of `int`, and an index named
+  `contraction` shared its identifier with the accumulator the compiler writes,
+  which made the sum come out zero with nothing said.
+
+- Fix: a C function may take a `uint64_t *` and return a `uint64_t`.
+  `CArray.jit_function("void (*)(uint64_t *, int64_t)")` reached its cells as
+  an opaque slot rather than an array, and a `uint64_t` return type was
+  refused as "no value a compiled body can produce" -- from a table written
+  before uint64 was a type a kernel computes in.
+
+- Fix: `CArray.jit_map` collects a cmplx64 value into a cmplx64 array rather
+  than refusing to allocate one. Nothing else changes type: a block whose value
+  is cmplx128 still gives cmplx128.
+
 ## 0.1.1
 
 - Fix: a zero divisor in a `CArray.fuse` expression no longer turns