carray-jit 0.1.0

data/docs/04_Compiling.md

@@ -0,0 +1,234 @@
+# Compiling, caching and inspecting
+
+## What compiling costs, and where kernels are kept
+
+### Requirements on the array
+
+Contiguity is not one of them. What is:
+
+- **not an object array** -- `CA_OBJECT` holds Ruby values, not numbers
+- **not a size-reinterpreting view carrying a mask** -- see [Masks](03_SupportedFeatures.md#masks)
+- **writable**, when the kernel writes to it
+
+### What compiling costs
+
+Compiling is not free, and the shape of the trade is worth stating. `benchmark/break_even.rb` measures it where you are; what follows is the shape to expect, not a figure to hold this to.
+
+Only the first time is expensive. Compiling a kernel never seen before costs a couple of hundred milliseconds, and most of that is the operating system checking a freshly written binary rather than the compiler working -- the same C through `cc -O3 -fPIC -shared` by hand takes a fraction of it. After that the object is on disk, and a new process pays single-digit milliseconds to load it.
+
+The third level is not the compiler at all. A call that finds everything already loaded still costs tens of microseconds, and that figure does not move with the size of the array: it is reading the block's source, splitting the captures, broadcasting the shapes and packing the buffers. So a kernel called in a loop does not pay for itself at one element, and where it starts to depends on what it is being weighed against -- which is two different questions with two different answers.
+
+Against **a Ruby loop** -- the reader who came here from `jit_for`, writing a recurrence or a stencil that has no array form -- the crossing is early, at tens of elements for a wide expression and around a hundred for one as narrow as `a * 2 + 1`.
+
+Against **the array expression** -- the reader choosing `jit_each` over `a + b * c`, which already runs in C -- it is thousands, and the narrower the expression the later it comes: what is being saved is the passes over the data, and a narrow expression has fewer of them to save.
+
+Below those, write the expression. The compiled kernel is for the sizes where the passes cost more than the call does.
+
+Which is why the cache is on by default. Turning it off with `CARRAY_JIT_NO_CACHE` makes every run pay the compile again.
+
+### Caching
+
+A kernel is compiled once, and every later call takes a fast path. Three levels, outermost first:
+
+| Level | Key | Skips |
+| --- | --- | --- |
+| Block source | the block's instruction sequence | reading and parsing the file |
+| Kernel | source, dtype, capture types | analysis, type assignment, code generation, `dlopen` |
+| Shared object | SHA-256 of the C source and flags | the C compiler, across processes |
+
+Measured, on a kernel called repeatedly:
+
+```
+first call (compiles)       2090 us
+repeat call, block            9.2 us
+repeat call, source:          6.4 us
+calling the kernel directly   3.1 us
+```
+
+Nothing on that path is free enough to repeat: parsing the file a block lives in costs about 110 us, and analysis and type assignment about 80 us together, against roughly 3 us to call a compiled kernel. So all of it is memoized.
+
+The block cache is keyed on the instruction sequence because CRuby hands back the same one for every Proc made from a single block literal -- a free identity for the block, with no source comparison needed.
+
+What is *not* cached is the value of a captured variable: it is read from the binding on every call, so a kernel keeps working when the value changes. Only its class is part of the kernel key, since only the class changes the C signature.
+
+The remaining ~9 us is per call, not per element, so it disappears into any array worth compiling for: at a million elements it is 0.1% of the run.
+
+### Where compiled kernels are kept
+
+In `~/.cache/carray-jit` (honouring `XDG_CACHE_HOME`), one directory per version, CArray version and architecture, holding a pair of files per kernel named by the SHA-256 of the C source, the compiler and its flags:
+
+```
+~/.cache/carray-jit/
+├── 0.1.0-carray3.0.1-arm64-darwin24/
+│   ├── 014f77ae....c        the generated C, kept so an object can be identified
+│   └── 014f77ae....bundle   the compiled kernel, about 17 KB
+└── 0.1.0-carray3.0.1-x86_64-linux/
+```
+
+A kernel is only good for the version that generated it and the architecture it was built for, so those get their own directories. CArray's version is there for the same reason and one of its own: a kernel is handed CArray's memory, on layouts CArray decides, so one compiled against one version and run against the next would answer wrongly rather than fail to load.
+
+The two numbers say different things and move on their own clocks: the first is the version that generated the kernel, the second the version it was generated against. This gem is not versioned with CArray, and one release of it meets more than one -- the dependency is `>= 3.0.1, < 3.1`, so 3.0.1 and 3.0.4 both satisfy it -- and a layout the kernel reaches into can move between them. A new release does not spend its cache budget on entries nothing can reach any more, and a home directory shared between machines -- over NFS, or between Rosetta and native -- does not have one architecture evicting the other's kernels. A directory whose newest entry has not been touched in 30 days (`CARRAY_JIT_CACHE_MAX_AGE_DAYS`) is removed.
+
+```ruby
+CArray::JIT.cache_root                 #=> "/home/you/.cache/carray-jit"
+CArray::JIT.cache_directory            #=> ".../0.1.0-carray3.0.1-arm64-darwin24"
+CArray::JIT.cache_entry_count          #=> 12
+CArray::JIT.cache_byte_size            #=> 208_320
+CArray::JIT.stale_cache_environments   #=> [".../0.0.9-carray3.0.1-arm64-darwin24"]
+CArray::JIT.clear_cache                #=> 12   (kernels already loaded keep working)
+CArray::JIT.clear_cache(everything: true)
+```
+
+It survives the process on purpose. Rebuilding a kernel costs about 60 ms to compile, plus roughly **180 ms on macOS the first time a freshly written binary is loaded** -- Gatekeeper checking it, not anything Ruby does. Another process loading the same file pays 0.2 ms:
+
+```
+process A, just compiled    dlopen  177.8 ms
+process B, existing file    dlopen    0.2 ms
+process C, existing file    dlopen    0.2 ms
+```
+
+Set `CARRAY_JIT_NO_CACHE=1` (or `CARRAY_JIT_CACHE=none`) to put the cache in a temporary directory that is removed at exit, at that cost per kernel per run.
+
+The cache is **bounded**: past `CARRAY_JIT_CACHE_LIMIT` kernels per environment (512 by default, so about 9 MB) the least recently used are evicted, source and object together. Reuse updates an entry's timestamp, so what a program actually runs stays. This is the one place carray-jit deliberately parts with RubyInline, whose `~/.ruby_inline` has no eviction at all and grows for the life of the account.
+
+Removing a cached object never breaks a kernel already in use: unlinking a loaded shared object leaves its mapping intact.
+
+Because the cache is shared across processes and across time, the key covers the C source, the compiler *binary* (its path, size and mtime -- a stat rather than the ~50 ms of asking it for `--version`), the flags and the architecture. A toolchain upgrade therefore invalidates entries rather than reusing what the old compiler produced.
+
+An entry that will not load -- a truncated write, an OS or toolchain change -- is deleted and rebuilt rather than raised. A cache that outlives the process must not be able to turn one bad write into a permanent failure of every future run. A staging file left behind by a process killed mid-compile is swept once it is old enough to be certain nothing is still writing it.
+
+The directory is created 0700, and a cache directory other users can write to is refused rather than used -- everything in it gets `dlopen`ed, so a shared writable cache would be a way to run code as you.
+
+## Inspecting a kernel
+
+### Seeing the generated C
+
+```
+CARRAY_JIT_DUMP=1 ruby your_script.rb
+```
+
+prints the source before it is compiled. It opens by saying where it came from -- the file and line the block was written at, and the block itself -- because a generated file that says only what it does is hard to place months later:
+
+```c
+/*
+ *  Generated by carray-jit 0.1.0.
+ *
+ *  /home/you/work/legendre.rb:12
+ *
+ *    { |i|
+ *      w  = x * legendre[i-1]
+ *      wy = w - legendre[i-2]
+ *      legendre[i] = wy + w - wy / i
+ *    }
+ */
+```
+
+That header is kept out of the hash the cache is keyed by, so two call sites that generate the same kernel share one compiled object, and editing the lines above a kernel does not throw its object away. The file then names the first site that compiled it. Every kernel carries two loops and decides between them once, outside the loop -- the contiguous form indexes a typed pointer, which the compiler can vectorise, and the strided form is what lets a view run without being copied first:
+
+```c
+static void
+carray_jit_contiguous (char **pointers, int64_t *strides, int64_t *bounds, ...)
+{
+  char *const p_legendre = pointers[0];
+  const int64_t legendre_s0 = strides[0];
+  const double x = reals[0];
+
+  for (int64_t i = bounds[0]; i < bounds[1]; i++) {
+    double w = x * ((double *)(p_legendre))[i - 1];
+    double wy = w - ((double *)(p_legendre))[i - 2];
+    ((double *)(p_legendre))[i] = wy + w - wy / (double)i;
+  }
+}
+```
+
+Every kernel has that same signature, which is what lets one Fiddle::Function shape serve all of them; the per-kernel detail arrives in the buffers and is unpacked into named locals at the top, where it also reads better. Abridged above are the ones this kernel barely uses: `reals` and `integers` for the captured scalars, `functions` and `data` for the address of each C function the block called and of each array it handed to one whole, `mask_pointers` and `mask_strides` for the masks, and `error` for the one thing a cell can raise. `bounds` carries a start, a limit and a step per axis -- which is also what a chunk looks like, and is why CArray's sweep can call this kernel directly.
+
+### The carray-jit command
+
+Installing the gem provides a small command for looking after the cache. It loads only the compiler and its cache, so it works whether or not CArray and the compiled extension can be loaded -- the CArray version in the environment name is the one RubyGems says a `require` would activate, which is the one a running program would have reported itself.
+
+```
+$ carray-jit
+root         /home/you/.cache/carray-jit
+environment  0.1.0-carray3.0.1-arm64-darwin24
+kernels      3
+size         50.1 KB
+limit        512 kernels
+
+other environments:
+  0.0.9-carray3.0.1-arm64-darwin24  1.2 MB  last used 2026-01-01
+```
+
+```
+$ carray-jit list
+5a29d9e696a2  16.5 KB  2026-09-01 13:31  /home/you/work/smooth.rb:42
+fff2e2d74333  16.5 KB  2026-09-01 13:31  /home/you/work/solve.rb:17
+5070c61b1a43  16.5 KB  2026-09-01 13:31  /home/you/work/solve.rb:23
+```
+
+A hash says nothing about which kernel it names, so `list` shows where the kernel was written, and `show` prints the source -- which begins by saying the same thing, and quotes the block it was generated from:
+
+```
+$ carray-jit show 5a29d9e6
+/*
+ *  Generated by carray-jit 0.1.0.
+ *
+ *  /home/you/work/smooth.rb:42
+ *
+ *    { |i|
+ *      values[i] = alpha * price[i] + (1.0 - alpha) * values[i-1]
+ *    }
+ */
+
+#include <stdint.h>
+#include <math.h>
+
+static void
+carray_jit_contiguous (char **pointers, int64_t *strides, int64_t *bounds, ...)
+{
+  char *const p_values = pointers[0];
+  ...
+```
+
+| Command | |
+| --- | --- |
+| `carray-jit` / `carray-jit status` | where the cache is and how big it is |
+| `carray-jit list` | the kernels cached for this environment, and where each was written |
+| `carray-jit show <prefix>` | the C source of one cached kernel, block and all |
+| `carray-jit clear` | remove this environment's kernels |
+| `carray-jit clear --all` | remove every environment's kernels |
+
+### Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `CARRAY_JIT_DUMP` | Print generated C to stderr before compiling |
+| `CARRAY_JIT_CACHE` | Cache directory (default `~/.cache/carray-jit`), or `none` |
+| `CARRAY_JIT_NO_CACHE` | Keep the cache in a temporary directory, removed on exit |
+| `CARRAY_JIT_CACHE_LIMIT` | Kernels retained on disk, per environment (default 512) |
+| `CARRAY_JIT_CACHE_MAX_AGE_DAYS` | Days an unused environment's directory is kept (default 30) |
+| `CARRAY_JIT_CC` | C compiler (default `RbConfig::CONFIG["CC"]`) |
+| `CARRAY_JIT_REASSOCIATE` | `0` makes the serial accumulator the default for the process |
+
+## Testing
+
+```
+rake test
+rake benchmark
+```
+
+Every kernel in the suite is checked against the same computation written as an ordinary Ruby loop -- except the masked ones, which are checked against CArray's operators -- and the float comparisons are exact rather than within a tolerance -- a tolerance would hide the two bugs most worth catching, FMA contraction and computing in the wrong precision. A test whose kernel reduces says `reassociate: false`, which is what makes its answer comparable to a Ruby loop's at all.
+
+The tridiagonal solver in `test/test_thomas.rb` is the case the design had to be able to express: two sweeps in opposite directions, one of them writing two arrays that share a denominator. It is checked bit for bit against a plain Ruby solver, and by the residual of `A x - d`.
+
+`benchmark/thomas.rb` times it against a Ruby loop and against LAPACK. Run it rather than reading a figure off this page: what it prints depends on the machine it is run on, and what is worth reading is the ratio between the rows.
+
+The Ruby loop is the comparison this gem is about. The LAPACK row is **not** a claim that this is faster than LAPACK, and three things stand between it and any such reading:
+
+- `?gtsv` does LU with partial pivoting and solves systems that are not diagonally dominant. This solves the ones that are. Skipping the pivot is most of the difference.
+- What is timed is `CArray::Linalg.solve_tridiagonal`, not `?gtsv` itself: the diagonals are passed as views, so there are contiguity copies, plus validation and output allocation, inside that number.
+- The four arguments `?gtsv` overwrites have to be copied first, and that is excluded from the figure, because it is not part of solving.
+
+What the comparison is good for is the other direction. `?gtsv` exists, so this kernel can be checked against it, and it agrees to within rounding. The algorithms `jit_for` is actually for, a periodic tridiagonal solve or a domain-specific recurrence, have no LAPACK entry point to be checked against at all.
+
+`test/test_views.rb` covers the access tiers: a contiguous row, a strided column, a reversal, a slice of a slice, and a gather view whose region is transferred and written back.

data/docs/05_DesignNotes.md

@@ -0,0 +1,136 @@
+# Design notes
+
+Decisions that were not obvious, and why.
+
+## The type is C's, and so is the arithmetic where the width is real
+
+The storage type is CArray's, mapped to C exactly -- `int64_t`, `uint8_t`, `float` -- and everything the type itself decides follows from that: the width, the wrap on store, the bit patterns, what a shift does past the width. There a kernel agrees with CArray, because both are the same C.
+
+The arithmetic follows the same rule where the width makes a difference to the answer, and Ruby's where it does not. That splits the types in two.
+
+**Floating point computes in its own width.** A `float32` cell is read as a `float`, worked on as a `float`, and stored as one; the literal it meets takes the same width, since one `double` in a C expression takes the whole expression with it. So a kernel over float32 arrays gives what CArray's own operators give:
+
+```ruby
+one = CArray.float32(1); one[0] = 1.0
+tiny = CArray.float32(1); tiny[0] = 1.0e-8
+
+((one + tiny) - one)[0]                     #=> 0.0, computed in float
+CArray.jit_for(1) { |i| out[i] = (one[i] + tiny[i]) - one[i] }
+out[0]                                      #=> 0.0, the same
+```
+
+Ruby's answer for that loop is 9.99e-09, because Ruby has no float32 arithmetic to give: every cell it reads becomes a Float, which is a double. Where Ruby has no width to have an opinion about, the opinion followed is CArray's.
+
+**The integers compute in `int64_t`,** as they always have. Reading an `int32` cell gets an Integer that does not stop at 2^31, and that is what a kernel gives it -- `int32 + int32` is worked out in 64 bits and truncated at the store.
+
+Narrowing them was tried and dropped, because it would change the answer and buy nothing. Truncation commutes with add, subtract and multiply, so a compiler can prove the wide computation equals the narrow one and emits the narrow vectors by itself: `int16` multiplication comes out as `mul.8h` on arm64 and `pmullw` on x86 whether the C says `int16_t` or `int64_t`, with no widening instruction anywhere. Floating point has no such property -- each step rounds -- which is exactly why it has to be narrow to be narrow, and why it is about twice as fast now that it is.
+
+`uint64` is neither: it is the width that cannot fold into `int64_t` at all, since the values it holds above 2^63 are the ones `int64_t` cannot carry, so it computes in a `uint64_t` of its own. See [Types](03_SupportedFeatures.md#unsigned-64-bit).
+
+**A value with no data type follows Ruby.** A literal and a captured Numeric have no width of their own, so `2.0` is a double and `2` an Integer -- until they meet an array of their own kind, which lends them its width: `f32 * 2.0` is float32. What an array can lend is a width, never a kind, so `i32 * 2.0` is a float64 and `f32 * 1i` a cmplx128. A local that wants a particular type is seeded from a `CScalar`, which is a value with a data type. See [Locals](03_SupportedFeatures.md#locals-types-and-postfix-math).
+
+`CArray.float` is float32; `CArray.double` is float64.
+
+## `-ffp-contract=off` is mandatory
+
+Without it, clang and gcc fuse `a*b + c` into a single FMA instruction -- **at `-O0` as well as `-O2` on arm64** -- which changes the last bit of the result. Measured on a two-term recurrence: 13 of 24 cells disagree with the Ruby loop with contraction on, and all 24 agree with it off.
+
+The Legendre kernel happens to be immune, because its product is bound to a variable used twice and so never forms the fusable pattern. That makes this a bug a narrow test suite would miss entirely.
+
+Fusing is not forbidden the way reassociating a reduction is not forbidden -- one rounding in place of two is if anything the more accurate -- so licensing it would be the same kind of move. It has not been made because it does not pay: measured here, contraction is worth about 1.2x on a coefficient-heavy stencil and makes the 300-cube matrix multiply about 1.3x *slower*, the vectoriser deciding differently. Off is also what keeps `a*b - a*b` and the error-free transformations meaning what they say.
+
+## A sine beside a cosine is `sincos`, and is allowed to be
+
+A kernel that asks for `Math.sin(x)` and `Math.cos(x)` of the same argument in the same pass does not get two library calls. The generated C says `sin(x)` and `cos(x)` on two lines and clang answers both with one call to `sincos`, whose sine is not always the one `sin` returns in the last bit. Ruby calls `sin`. So this is the one place where a kernel over `double` disagrees with the Ruby loop it replaces without the block having asked for anything unusual: measured over 200,000 arguments, a sine on its own agrees with Ruby's everywhere, and the same sine written beside a cosine of the same argument disagrees for 1748 of them, by a bit. [kepler.rb](../examples/applications/kepler.rb) prints both counts.
+
+It is the same family of thing as fusing `a*b + c`, and the reason it is treated differently is that the flag is not the same shape. `-ffp-contract=off` stops one transformation and costs nothing. The two flags that stop this one cost, measured here on arm64 with Apple clang -- three processes, cache off, against the default flags:
+
+```
+                                   default   -ffp-model=strict   -fno-builtin
+  element-wise a + b*c (4M)        1.91 ms    2.71 ms (1.42x)    2.10 ms (1.10x)
+  five-point stencil (2000x2000)   1.92 ms    4.09 ms (2.14x)    2.08 ms (1.09x)
+  row sums (2000x2000)             0.65 ms    0.68 ms (1.06x)    0.65 ms (1.01x)
+  recurrence (4M)                 19.43 ms   27.02 ms (1.39x)   18.68 ms (0.96x)
+  Kepler by Newton (200k)         11.74 ms   12.79 ms (1.09x)   12.42 ms (1.06x)
+  exp and sqrt (4M)                7.25 ms    8.05 ms (1.11x)    9.47 ms (1.31x)
+```
+
+`-ffp-model=strict` brings `-frounding-math` and strict exception behaviour with it, so it does not stop one transformation -- it stops the vectoriser reasoning about floating point at all, which is where the stencil's 2.14x comes from. `-fno-builtin` is cheaper and better aimed, but it aims at the same place from the other side: it stops `sin` being recognised as `sin`, which also stops `sqrt` and `exp` being the instructions they have on this target. `-fno-builtin-sincos` does not stop the merge here at all.
+
+So the merge stays, and is written down instead. A kernel wanting the last bit Ruby has can take the two lines apart -- a sine in one kernel and a cosine in another agree with Ruby everywhere -- and a kernel comparing itself against a Ruby loop should compare within a tolerance if it computes both.
+
+## Integer division is floored, not truncated
+
+Ruby floors integer division and gives the remainder the sign of the divisor; C truncates toward zero. `-7 / 2` is `-4` in Ruby and `-3` in C. CArray's own kernels were changed to floor and agree with Ruby, so a JIT specialized for CArray has to agree as well -- lowering `/` to C's operator would quietly produce different numbers for negative operands.
+
+The generated helper mirrors `ext/mkkernel.rb` in CArray. Dividing by a positive power of two skips the helper: an arithmetic shift already floors, and is cheaper than the truncating divide C would emit.
+
+For the same reason `%` is **not** lowered to `fmod`, which truncates. Ruby and CArray floor it. `%` is not in the subset yet.
+
+## Integer division by zero
+
+C has no exception to raise, and dividing by zero in the kernel would trap. The helper reports it through an `int32_t *error` out-parameter, which the Ruby side checks after the call and turns into `ZeroDivisionError`. The branch costs nothing measurable because the flooring correction needs a comparison anyway.
+
+That slot carries `raise` too. 1 is the divisor that was not there and 2 the subscript that ran off its array; a `raise` in the block takes a code from 3 up, and the kernel keeps the message behind each -- as does a compiled function, for the `raise`s in its own body. The code is taken from the message rather than counted off as messages are met: a kernel is cached on disk under the C it generated, and a number that meant one string when the object was built and another when it was loaded would raise the wrong message out of a cache hit, quietly. From the message, one string is one code in every process.
+
+## Reaching the array
+
+A generated kernel addresses cells itself -- it reads `a[i-1]` and writes `a[i]` -- so what it needs from CArray is not element delivery but an **addressing basis**: a pointer, an offset, and one byte stride per axis.
+
+That rules out the two surfaces that look like the obvious homes for it. The kernel iterator (`guides/devel/11`) delivers cells per slab, with mask gather and outer-axis walk, and has no N-ary form -- the Thomas algorithm touches six arrays at once. The sweep ELEMENT family (`guides/devel/13`) flattens the array and cannot recover the axis structure a stencil needs. Neither is wrong; they answer a different question.
+
+The basis comes from three public predicates, checked in order:
+
+| | Test | How the kernel reaches the array | Copy |
+| --- | --- | --- | --- |
+| 1 | `ca_is_entity` | the buffer is the basis | none |
+| 2 | `ca_is_stride_family` | `ca_stride_compose_to_root` folds the whole view chain to `root + base + strides` | none |
+| 3 | otherwise | `ca_xfer_stride` moves the box the loop touches | that box |
+
+Tier 2 is what makes a transpose, a column slice, a reversal, or a slice of a slice run **in place**, with no gather and no scatter -- a write through the folded stride lands in the parent's memory, because it *is* the parent's memory. Measured on a two-million-element recurrence:
+
+```
+entity                       tier 1  stride 8    2.17 ns/element
+contiguous row of a matrix   tier 2  stride 8    2.13 ns/element
+strided column               tier 2  stride 16   4.85 ns/element
+reversed                     tier 2  stride -8   4.86 ns/element
+```
+
+A contiguous view costs what an entity costs. A strided one costs about twice that, because the loop cannot be vectorised. Copying it out, running the contiguous loop and copying it back measured about 25% faster than folding it in place (7.4 ms against 9.8 ms) -- so folding is not chosen for speed. It is chosen because the alternative is the library allocating a second array behind the caller's back. Anyone who wants that trade writes `column.copy`, and can see what it costs.
+
+The fold has to land on an array that owns its memory. It 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 would throw the kernel's writes away, so a fold that does not reach an entity is not the stride tier at all: it goes to the box transfer, which moves only the cells the kernel asked for and puts them back.
+
+The fold is done **once**, before compiling, and its result is passed to the kernel. That matters more than it looks: composing the chain per access costs 10 ns for one hop and 37 ns for two, while a hoisted basis is flat at 3.5 ns regardless of depth.
+
+## Why tier 3 never materialises the whole view
+
+The box is computed per array and per axis: two arrays in one kernel need not be read at the same offsets, and one array need not be read at the same offsets on each of its axes.
+
+`ca_attach` on a view gathers all of it, whatever the kernel intends to touch. On a four-million-element gather view that was 2.7 ms whether the loop covered a hundred cells or a million. `ca_xfer_stride` moves only the requested box:
+
+```
+loop covers        ca_attach     ca_xfer_stride
+100 cells            2.97 ms         0.001 ms
+10,000 cells         2.69 ms         0.022 ms
+1,000,000 cells      3.86 ms         2.305 ms
+```
+
+Most kernels cover the whole array, so in practice this rarely changes the number. It changes what the library promises. A cost that does not scale with the work is one the caller cannot reason about, and a JIT that hides one has given up the thing it exists for.
+
+The same reasoning is why nothing here materialises on the caller's behalf beyond that box. CArray's own rule is that a materialised copy happens when the user writes `copy` (`guides/devel/10`, principle 3); a kernel that silently gathered 32 MB would be breaking it.
+
+## What was tried and rejected
+
+The first version of this gem read the pointer through Ruby's MemoryView C API, to stay independent of `carray.h`. It asked for `RUBY_MEMORY_VIEW_SIMPLE`, which demands a contiguous buffer, concluded that views could not be reached, and rejected every one of them. Both halves were wrong: `RUBY_MEMORY_VIEW_STRIDES` exports the whole CAStride family zero-copy, and CArray's own predicates say more than the buffer protocol can. Refusing views to keep the gem decoupled was trading away the composability that views exist for.
+
+Per-cell `ca_xfer_addrs` was measured as a tier-3 alternative and is not used. At `n = 1` it re-folds the view on every call and adds about 28 ns of fixed cost on top; batched over 1024 cells it is as fast as anything, but a recurrence cannot batch -- each write has to land before the next read.
+
+## Recovering a block's source
+
+Ruby will not hand back a Proc's source, but it does say exactly where the block sits. `RubyVM::InstructionSequence.of(block).to_a[4][:code_location]` gives `[first_line, first_column, last_line, last_column]`; the file (or `script_lines`) is parsed with Prism, and the block node at that position is the kernel.
+
+The columns are the part that matters. `Proc#source_location` reports only a line, which cannot tell two blocks on one line apart -- so it is not enough on its own.
+
+`RubyVM::AbstractSyntaxTree.of` looks like the obvious route and does not work: since Ruby 3.4 the default parser is Prism, and it refuses with "cannot get AST for ISEQ compiled by prism".
+
+Two cases fall back to `source:`. A block defined in `eval` or in a console has no file to read -- setting `RubyVM.keep_script_lines = true` before it is defined makes `script_lines` available and handles that. And a file edited since it was loaded no longer holds the same text at that position, which is reported rather than compiled.

data/docs/06_Cheatsheet.md

@@ -0,0 +1,177 @@
+# Cheatsheet
+
+Eight entry points: the seven `jit_` methods this gem puts on `CArray`, and
+`CArray.fuse`, which is CArray's own and gets the compiler from this gem being
+installed. Every example here runs as written.
+
+## Which one
+
+| What you are doing | Write |
+|---|---|
+| An expression over whole arrays | `CArray.fuse` |
+| The same, in one pass with no intermediates | `CArray.jit_each` |
+| The same, and you want the result back | `CArray.jit_map` |
+| A cell reads its neighbours, or the one computed before it | `CArray.jit_for` |
+| A cell reads a window, and the edge needs a rule | `CArray.jit_stencil` |
+| An index appears twice and is summed | `CArray.jit_contract` |
+| Call a C function someone else compiled | `CArray.jit_extern` |
+| Compile a C function of your own | `CArray.jit_function` |
+
+The dividing line among the first four is **what reaches what**. Element-wise
+work reaches no neighbour, so it names no index and needs no extent. A cell
+that reaches another cell has to say which one, which is what an index is for.
+
+---
+
+## Whole arrays
+
+```ruby
+out[] = CArray.fuse { a + b * 2 }
+```
+
+Needs no compiler. Without this gem CArray walks the expression; with it, the
+expression is compiled instead, without being asked and without changing the
+answer. An expression the compiler cannot address goes back to CArray. This is
+the only entry point here that is not `jit_`-prefixed, and the only one that
+works with no compiler on the machine.
+
+## Cell by cell
+
+```ruby
+CArray.jit_each { out = a + b * 2 }        # writes; returns the kernel
+larger = CArray.jit_map { a > b ? a : b }  # returns a new array
+```
+
+Arrays are the names the block closes over -- nothing is named twice. Every
+name is a *cell*: `out = ...` writes the cell of the array `out` names outside.
+A name that is not an array out there is an ordinary local.
+
+`jit_each` writes and hands back the kernel; `jit_map` allocates the result,
+typed from the block's last value, and hands that back. Neither takes block
+parameters.
+
+## Naming the index
+
+```ruby
+CArray.jit_for(1...6) { |i| x[i] = x[i-1] * 2 }
+```
+
+The parameters are the loop indices and the arguments are their extents, one
+each, an Integer `n` standing for `0...n`. Naming an index is what lets a cell
+reach `x[i-1]`, and reaching a cell the kernel will later write is what fixes
+the direction the axis runs -- derived from the dependencies, not chosen.
+
+`reassociate:` says whether a reduction's accumulator may be split into partial
+sums. Default is `CArray::JIT.reassociate` (`true`). Pass `false` for the
+serial order -- a compensated summation, or checking against the loop.
+
+## Windows
+
+```ruby
+smoothed = CArray.jit_stencil(image) { |a|
+  0.25 * (a[-1, 0] + a[1, 0] + a[0, -1] + a[0, 1])
+}
+```
+
+Arrays are **given**, not closed over, and the parameters are windows onto them
+in that order: `a[0, 0]` is the cell, `a[-1, 1]` a neighbour. The block's value
+is what the cell gets.
+
+| Keyword | Meaning |
+|---|---|
+| `border: :mask` | a cell whose window falls off is `UNDEF` -- not computed (default) |
+| `border: :skip` | that cell is left as it was found |
+| `type:` | the data type to collect into; without it, the block's value's |
+| `into:` | write into an array of yours, which then decides the type |
+
+`type:` and `into:` together are refused.
+
+## Contraction over a repeated index
+
+```ruby
+c = CArray.jit_contract { |i, j, k| a[i,k] * b[k,j] }   # a matrix product
+    CArray.jit_contract { |i, j, k| c[i,j] = a[i,k] * b[k,j] }
+```
+
+**An index that appears twice is summed.** One that appears once is free and
+becomes an axis of the result, in the order the block named them -- so
+`{ |j, i, k| ... }` is the transpose. No extent is given: each index's extent
+comes from the axes it addresses.
+
+Assigning into an array of yours says where to put it and in what order its
+axes lie. It does **not** decide what is summed -- so `total[i] = a[i,k]` is
+refused, because nothing in `a[i,k]` stands in for a sigma. That is `sum(axis:)`.
+
+## C functions
+
+```ruby
+j0 = CArray.jit_extern("double j0(double)", from: "libgsl")
+sq = CArray.jit_function("double (*)(double)") { |t| t * t }
+
+CArray.jit_each { out = j0.call(x) }
+```
+
+`jit_extern` compiles nothing -- Fiddle finds the address, and the kernel calls
+it directly rather than reaching it per cell through Fiddle. `from:` names the
+library; `nil` searches the process. `jit_function` compiles a body of your
+own, callable from a kernel, from Ruby, and by a C library that knows nothing
+about either.
+
+---
+
+## What comes back
+
+| Method | Returns |
+|---|---|
+| `fuse` | a lazy expression; assign it to materialise |
+| `jit_each` | `CompiledKernel` -- the value is in the arrays it wrote |
+| `jit_map` | a new `CArray`, typed from the block's value |
+| `jit_for` | `CompiledKernel` |
+| `jit_stencil` | `into:` when given, otherwise a new `CArray` |
+| `jit_contract` | a new `CArray`, or the `CompiledKernel` when the block assigns |
+| `jit_extern` | `CFunction` |
+| `jit_function` | `CFunction` |
+
+Every `CompiledKernel` answers `#c_source` with the C that ran.
+
+## Compiler required
+
+| | Without a C compiler |
+|---|---|
+| `fuse` | works -- CArray walks it, same answer |
+| the seven `jit_` methods | `CArray::JIT::Unsupported` |
+
+That is what the prefix says. A block outside the subset is refused by name and
+line rather than run as a Ruby loop: nobody reaches for a compiler except to
+make something fast, so quietly doing the slow thing would answer a question
+that was not asked.
+
+## What gets refused
+
+| | |
+|---|---|
+| `jit_for` with a block naming no index | element-wise -- that is `jit_each` |
+| `jit_each` / `jit_map` with block parameters | an index means `jit_for` |
+| `jit_stencil` with no array given | the arrays are arguments, not closures |
+| `jit_stencil` with both `type:` and `into:` | `into:` already decides the type |
+| a contraction summing an index that appears once | not the convention; `sum(axis:)` |
+| an index appearing more than twice | there is no pair to sum |
+| an index whose axes disagree in extent | the shape check a contraction exists to do |
+| an array both written and read in a contraction | a recurrence -- write it with `jit_for` |
+| a block naming a construct outside the subset | refused by name and line |
+
+## Knobs
+
+```ruby
+CArray::JIT.reassociate          #=> true, the default for jit_for reductions
+CArray::JIT.reassociate = false  # serial accumulation everywhere
+
+CArray::JIT.cache_directory      #=> ~/.cache/carray-jit/<version>
+CArray::JIT.cache_entry_count
+CArray::JIT.cache_byte_size
+CArray::JIT.clear_cache
+```
+
+A kernel is compiled once: the shared object is cached on disk, keyed by the
+generated C and the compiler that built it, so a later process finds it there.
+See [Compiling, caching and inspecting](04_Compiling.md).

data/examples/README.md

@@ -0,0 +1,56 @@
+Examples
+========
+
+Two kinds. [applications/](applications) are small programs that do something
+-- read one to see how this gets used. [features/](features) is a tour of the
+subset, one file per feature, closer to documentation with the answers checked.
+
+```
+ruby examples/applications/game_of_life.rb
+rake examples                        # all of them
+```
+
+Applications
+------------
+
+| | |
+| --- | --- |
+| [game_of_life.rb](applications/game_of_life.rb) | Conway's rules as a stencil, twice: with the indices named, and as a window on a torus |
+| [moving_average.rb](applications/moving_average.rb) | a price series: exponential smoothing, running peak, drawdown |
+| [heat_equation.rb](applications/heat_equation.rb) | implicit diffusion in a rod -- a tridiagonal solve every step |
+| [sobel_edges.rb](applications/sobel_edges.rb) | edge detection on an image, printed as ASCII |
+| [sensor_gaps.rb](applications/sensor_gaps.rb) | quality control on a record with holes in it |
+| [point_cloud.rb](applications/point_cloud.rb) | rotating points, their covariance, projecting onto a basis |
+| [mandelbrot.rb](applications/mandelbrot.rb) | escape time per cell -- a loop whose length no cell shares, and `z = z*z + c` as a Complex |
+| [relaxation.rb](applications/relaxation.rb) | steady heat on a plate: a stencil sweep with the boundary held |
+| [partial_sums.rb](applications/partial_sums.rb) | nine series in one pass, and where the order of a sum is a choice |
+| [sieve.rb](applications/sieve.rb) | Eratosthenes: an inner loop the data decides the length of |
+| [recursion.rb](applications/recursion.rb) | fib, tak, tarai and ackermann as `jit_function`s that call themselves |
+| [quicksort.rb](applications/quicksort.rb) | the textbook partition as a compiled C function, recursing through a pointer |
+| [kepler.rb](applications/kepler.rb) | Newton's method where the passes are the cell's business, not the program's |
+
+Each says what you would otherwise have written -- a Ruby loop, or an
+expression over whole arrays -- and measures against it. The numbers vary with
+the machine; the ratios are what to read.
+
+The tour
+--------
+
+| | |
+| --- | --- |
+| [01_element_wise.rb](features/01_element_wise.rb) | `jit_each { out = a + b * c }` and `jit_map` in one pass, and broadcasting |
+| [02_stencil.rb](features/02_stencil.rb) | each cell from its neighbours; extents, offsets, a step of two |
+| [03_recurrence.rb](features/03_recurrence.rb) | Legendre polynomials; upward sweeps, Ruby's division, a refused range |
+| [04_thomas.rb](features/04_thomas.rb) | a tridiagonal solver; the downward sweep and why it is `step(0, -1)` |
+| [05_reduction.rb](features/05_reduction.rb) | sum, maximum, count and a matrix multiply, all as inner loops |
+| [06_jit_contract.rb](features/06_jit_contract.rb) | Contraction over a repeated index; matmul, trace, outer product, the shape check |
+| [07_masks.rb](features/07_masks.rb) | `a[i] == UNDEF`, filling holes, and implicit propagation |
+| [08_views.rb](features/08_views.rb) | a column, a slice of a slice, a transpose, written in place |
+| [09_inspecting.rb](features/09_inspecting.rb) | the generated C, the cost of compiling, and what is refused |
+| [10_complex.rb](features/10_complex.rb) | complex arrays, the way in and out of them, and Ruby's signed zeros |
+| [11_c_functions.rb](features/11_c_functions.rb) | `jit_extern` for a C function already compiled, `jit_function` for one written in Ruby |
+| [12_sweep.rb](features/12_sweep.rb) | letting CArray drive the element-wise loop; what that bounds, and what keeps it here |
+| [13_cscalar.rb](features/13_cscalar.rb) | a `CScalar` in an expression, in a loop, and as the one cell every iteration writes |
+| [14_stencil_window.rb](features/14_stencil_window.rb) | `jit_stencil`: windows instead of indices, and the five answers `border:` gives |
+| [15_loops.rb](features/15_loops.rb) | an inner loop with a `break`, `while` where no bound is known, `next` |
+| [16_raising.rb](features/16_raising.rb) | `raise "..."` in a kernel: what comes back, and what was written before it |