carray-jit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 255cd246bcdd06c49b0afd2aeaaa4c3086eb8b9c84f4ad04319129f7415c182f
+  data.tar.gz: 80fedb1eb6cfcfece4009d69d26251a58a2caa9d5975d1895bb34b9a7fa18ac7
+SHA512:
+  metadata.gz: fa33123ca9012275607181b6808e2497da5e8d1908764bff23200299e9c972dd61e9b9e4d3ab58345b2fbcd5badba39ddd03b214ad9ccadde6413b37a32f3215
+  data.tar.gz: 45050b058cba426afc373e50f47797e4720968c1e4a26862322364d44a81a4610a991622b0e35d3d20519fb583e654558728a85393064978c9adfc23db5d9f06

data/.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--output-dir .yard-html
+--markup-provider redcarpet
+--no-private
+--readme README.md
+--files CHANGELOG.md
+lib/carray/jit.rb
+lib/carray/jit/errors.rb
+lib/carray/jit/kernel.rb
+lib/carray/jit/c_function.rb

data/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+Releases are recorded here from 0.1.0, which is the first.
+
+<!-- Newest first, at both levels: a new release section goes above the
+     ones below it, and a new entry goes directly under its own release
+     heading -- not at the end of the section. The kind of change is
+     carried by the `- Fix:` / `- Change:` / `- New:` that opens the
+     entry; there are no per-kind subheadings.
+
+     An entry says three things and stops: what changed, what to do about
+     it (the migration, the replacement, the condition under which nothing
+     changes), and what is excluded. It does not say how the code was
+     broken, name the internals that were fixed, break down where the
+     speed came from, or argue the design -- those belong in the commit
+     message. Two to six lines.
+
+     The version here is this gem's own and is not CArray's. Which CArray
+     a release needs is said in the gemspec, and an entry says so only
+     when the answer changes. -->
+
+## 0.1.0
+
+- New: `CArray.jit_for`, `CArray.jit_each` and `CArray.jit_map` compile their
+  block rather than running it. The block is read with Prism, translated to C
+  if it falls inside the recognized subset, compiled with the system C
+  compiler and called through Fiddle. `jit_for` takes the loop extents and
+  names the indices, so a cell may reach the ones around it -- a recurrence, a
+  stencil written out; `jit_each` writes into arrays of yours and `jit_map`
+  hands the value back, both at the cell with no index named. CArray 3.0.1
+  defines these three names and raises there; installing this gem is what
+  makes them compile.
+
+- New: a block outside the subset raises `CArray::JIT::Unsupported`, naming
+  the construct and where it is, rather than falling back to a Ruby loop.
+  Nobody calls these methods except to make a per-cell computation fast, so
+  quietly doing the slow thing would answer a question that was not asked.
+  What the subset holds is in
+  [docs/03_SupportedFeatures.md](docs/03_SupportedFeatures.md#the-recognized-subset).
+
+- New: every operation in a kernel means what Ruby means by it -- integer
+  division floors, `%` is not `fmod`, a Complex divides by Smith's method in
+  the order `complex.c` writes it. The exception is the order a reduction
+  takes its terms in: an accumulator is split into partial sums, which is
+  faster and usually the more accurate answer. `reassociate: false` on
+  `jit_for`, `CArray::JIT.reassociate = false`, or `CARRAY_JIT_REASSOCIATE=0`
+  for a whole process, asks for the serial order, and then the kernel agrees
+  with the Ruby loop bit for bit. `**` on a Complex is the one documented
+  exception.
+
+- New: `CArray.jit_stencil` runs a block over windows onto its arrays, with
+  `border:` saying what happens at the edge -- `:mask` by default, because
+  CArray can say "not computed" and a border of zeros cannot be told from
+  zeros that were computed. `CArray.jit_contract` runs a contraction over a
+  repeated index, summing over the indices that do not appear on the left.
+
+- New: `CArray.jit_extern` names a C function someone else compiled by quoting
+  its declaration, and `CArray.jit_function` compiles a body of your own. Both
+  hand back an object a kernel calls by address rather than per cell through
+  Fiddle, and either can be called from Ruby too.
+
+- New: `CArray.fuse` is compiled where this gem is installed, without asking
+  for it and without changing what it computes. The gem registers an
+  expression evaluator with CArray at load; a program that only writes
+  `CArray.fuse { ... }` gets the same answer with or without it.
+
+- New: compiled kernels are cached on disk, in `~/.cache/carray-jit` unless
+  `XDG_CACHE_HOME` or `CARRAY_JIT_CACHE` says otherwise, so a kernel is
+  compiled once rather than once per run. Entries are kept apart by this gem's
+  version, the CArray version they were built against, and the architecture:
+  a kernel is handed CArray's memory, on layouts CArray decides, so one
+  compiled against another version is rebuilt rather than reused.
+  `CARRAY_JIT_NO_CACHE` keeps the cache in a temporary directory that goes
+  away with the process, and `CARRAY_JIT_CC` names a different compiler.
+
+- New: the `carray-jit` command reports and looks after that cache --
+  `status`, `list`, `show`, `clear`. It loads the compiler and nothing else,
+  so a cache can be inspected or cleared when CArray itself will not load.
+
+- New: needs CArray 3.0.1 or later in the 3.0 series, and Ruby 3.2 or later.
+  The floor is where `ca_call_cslab_N`, the expression evaluator hook,
+  `__kernel_body__` and `BUILD_FLAGS` arrive. The ceiling is the next minor
+  because a kernel reaches CArray's C by address and pastes its kernel bodies
+  into generated C, neither of which the frozen author surface covers.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 himotoyoshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# carray-jit
+
+JIT compilation of CArray kernels written in Ruby.
+
+This library was written to make explicit, cell-by-cell work on CArray arrays fast. A subset of Ruby chosen for numerical computation is JIT-compiled and evaluated as a C-level loop over CArray arrays: a cell that reads its neighbours, a recurrence, a loop written out. The aim is to combine that with CArray's already fast vectorized arithmetic and reductions, and so speed up numerical computation with CArray as a whole.
+
+The block is read with Prism, translated to C if it falls inside that subset, compiled with the system C compiler and called through Fiddle. The compiled object is cached on disk, so a kernel is compiled once.
+
+## Status
+
+0.1.0 is the first release, and it still moves: behaviour can change between releases — see [CHANGELOG.md](CHANGELOG.md). A companion gem to CArray, it follows CArray's surface, which is not settled until CArray 3.1.
+
+## Features
+
+- **A JIT compiler for C-level loops.** A block becomes one C function over CArray's own memory, built by the system C compiler and called through Fiddle.
+- **Ordinary Ruby, and enough of it.** The source is parsed with Prism -- no DSL, no `eval` -- and every operation means what Ruby means by it, apart from the order a reduction takes its terms in. The subset is enough to state a numerical algorithm; what falls outside it is refused by name and line, not run as a Ruby loop.
+- **A method for each shape.** `jit_for` for recurrences and loops written out, `jit_stencil` for windows at any rank, `CArray.jit_contract` for contraction over a repeated index, `jit_each` and `jit_map` for a pass that reaches no neighbour.
+- **View- and mask-aware.** Columns, transposes and slices of slices are written in place without a copy, and masks propagate as CArray propagates them.
+- **Pure C functions, in and out.** `jit_extern` binds one from a library and a kernel calls it by address; `jit_function` compiles one from a block and hands back a C function pointer.
+- **The backend for `CArray.fuse`.** An array expression compiles instead of being walked a node at a time, without being asked and without changing the answer.
+- **Compiled once, across processes.** The shared object is cached on disk and reused by later runs.
+
+## Install
+
+```
+gem install carray-jit
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "carray-jit"
+```
+
+Requires:
+
+- Ruby >= 3.2
+- CArray >= 3.0.1, < 3.1
+- A C compiler
+- Prism and Fiddle (both ship with Ruby; Fiddle is a bundled gem)
+
+## Example
+
+```ruby
+# Legendre polynomials at x = 0.5, by the recurrence that defines them.
+# No array expression states this: P[i] needs P[i-1], which the same
+# loop has just written.
+
+x = 0.5
+legendre = CArray.double(24)
+legendre[0] = 1.0                     # P_0(x) = 1
+legendre[1] = x                       # P_1(x) = x
+
+CArray.jit_for(2...24) { |i|          # i is the loop index: 2, 3, ... 23
+  w  = x * legendre[i-1]              # a block local; its type is inferred
+  wy = w - legendre[i-2]              # reaching back two cells
+  legendre[i] = wy + w - wy/i         # the cell this pass writes
+}
+
+legendre[0..5].to_a
+#  => [1.0, 0.5, -0.125, -0.4375, -0.2890625, 0.08984375]
+```
+
+`CArray.jit_for`, `CArray.jit_each` and `CArray.jit_map` are CArray's own names: without this gem they raise and point at `CArray.fuse`, which computes an array expression without a compiler. This gem is the compiler. An expression over whole arrays wants `CArray.fuse` and not these, and gets compiled anyway where this gem is installed.
+
+## Documentation
+
+* [Introduction](docs/00_Introduction.md) — what carray-jit is: the gap it fills beside CArray, the subset a block is written in, and where a kernel gets its data
+* [Getting started](docs/01_GettingStarted.md) — the block, its extents, what the three methods return, and where a kernel stands beside `a + b * c` and `CArray.fuse`
+* [The shapes a kernel takes](docs/02_KernelShapes.md) — work that reaches no neighbour, extents and subscripts, stencils, reductions, and contraction over a repeated index
+* [Supported features](docs/03_SupportedFeatures.md) — locals and types, branches, raising, the types that are not just a number, calling C, and the recognized subset with what it refuses
+* [Compiling, caching and inspecting](docs/04_Compiling.md) — what the first call costs, where kernels are kept, reading the generated C, the `carray-jit` command, and what the suite checks
+* [Design notes](docs/05_DesignNotes.md) — decisions that were not obvious, and why
+* [Cheatsheet](docs/06_Cheatsheet.md) — the seven `jit_` methods and `CArray.fuse` on one page, to look up rather than to read
+
+## Contributing
+
+Bug reports and feature requests are welcome — please open an issue.
+
+**Before opening a pull request, read [CONTRIBUTING.md](CONTRIBUTING.md).** It is short, and it says which form a contribution is best sent in. A small, self-contained bug fix is fine as a pull request. Anything larger is better started as an issue: code here gets rewritten as a matter of course, so a patch for a larger change is likely to end up reimplemented rather than merged, and describing the problem gets you further than writing one.
+
+## Credits
+
+carray-jit was designed and reviewed by a human developer; the implementation was produced in collaboration with AI coding tools.
+
+## License
+
+MIT

data/bin/carray-jit

@@ -0,0 +1,194 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cache management for carray-jit.
+#
+# Loads only what it needs -- the compiler and its cache -- so that inspecting
+# or clearing the cache works without CArray or the compiled extension being
+# loadable.
+
+require "optparse"
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "carray/jit/version"
+require "carray/jit/errors"
+require "carray/jit/compiler"
+
+module CArrayJITCommand
+
+  Compiler = CArray::JIT::Compiler
+
+  BANNER = <<~TEXT
+    Usage: carray-jit <command> [options]
+
+    Commands:
+        status            where the cache is and how big it is (default)
+        list              the kernels cached for this environment
+        show <prefix>     the C source of one cached kernel
+        clear             remove this environment's kernels
+        clear --all       remove every environment's kernels
+
+    Options:
+  TEXT
+
+  class << self
+
+    def run (argv)
+      options = { :all => false }
+      parser = OptionParser.new do |option|
+        option.banner = BANNER
+        option.on("--all", "clear every version and architecture") {
+          options[:all] = true
+        }
+        option.on("-v", "--version", "print the carray-jit version") do
+          puts CArray::JIT::VERSION
+          return 0
+        end
+        option.on("-h", "--help", "print this message") do
+          puts option
+          return 0
+        end
+      end
+      arguments = parser.parse(argv)
+
+      case arguments.shift
+      when nil, "status" then status
+      when "list"        then list
+      when "show"        then show(arguments.shift)
+      when "clear"       then clear(options[:all])
+      else
+        warn(parser.to_s)
+        1
+      end
+    rescue OptionParser::ParseError => error
+      warn("carray-jit: #{error.message}")
+      1
+    rescue CArray::JIT::Error => error
+      warn("carray-jit: #{error.message}")
+      1
+    end
+
+    private
+
+    def status
+      puts "root         #{Compiler.cache_root}"
+      puts "environment  #{File.basename(Compiler.cache_directory)}"
+      puts "kernels      #{Compiler.entry_count}"
+      puts "size         #{human(Compiler.byte_size)}"
+      puts "limit        #{Compiler.entry_limit} kernels"
+
+      others = Compiler.stale_environments
+      unless others.empty?
+        puts
+        puts "other environments:"
+        others.sort.each do |path|
+          puts format("  %-32s %8s  %s",
+                      File.basename(path), human(directory_size(path)),
+                      last_used(path))
+        end
+      end
+      0
+    end
+
+    def list
+      entries = Compiler.entries.sort_by { |path| File.mtime(path) }.reverse
+      if entries.empty?
+        puts "no kernels cached for #{File.basename(Compiler.cache_directory)}"
+        return 0
+      end
+      entries.each do |path|
+        key = File.basename(path).sub(/\.[^.]+\z/, "")
+        puts format("%-12s %8s  %s  %s",
+                    key[0, 12], human(File.size(path)),
+                    File.mtime(path).strftime("%Y-%m-%d %H:%M"),
+                    origin(path))
+      end
+      0
+    end
+
+    def show (prefix)
+      unless prefix
+        warn("carray-jit: show needs the start of a kernel's key")
+        return 1
+      end
+      matches = Compiler.entries.select { |path|
+        File.basename(path).start_with?(prefix)
+      }
+      case matches.size
+      when 0
+        warn("carray-jit: no cached kernel starts with #{prefix}")
+        1
+      when 1
+        source = source_path(matches.first)
+        unless File.exist?(source)
+          warn("carray-jit: the source for #{prefix} is missing")
+          return 1
+        end
+        puts File.read(source)
+        0
+      else
+        warn("carray-jit: #{prefix} matches #{matches.size} kernels")
+        1
+      end
+    end
+
+    def clear (everything)
+      removed = Compiler.clear(:everything => everything)
+      scope = everything ? "every environment" : File.basename(Compiler.cache_directory)
+      puts "removed #{removed} kernel#{'s' unless removed == 1} from #{scope}"
+      0
+    end
+
+    # Where the kernel was written, which is what identifies it to whoever is
+    # looking: a hash names a kernel, a file and a line explain it.  The
+    # generated signature is the fallback, for a kernel compiled from a
+    # `source:` string that has no file behind it.
+    def origin (object_path)
+      source = source_path(object_path)
+      return "(source missing)" unless File.exist?(source)
+      lines = File.readlines(source).first(20)
+      found = lines.find { |text| text =~ %r{\A \*\s+(\S+:\d+)\s*\z} }
+      return Regexp.last_match(1) if found
+      # A kernel compiled from a `source:` string has no file behind it, so
+      # the first line of the block stands in for one.
+      body = lines.find { |text| text.start_with?(" *    ") }
+      return body[6..].strip[0, 60] if body
+      "(no origin recorded)"
+    rescue StandardError
+      "(unreadable)"
+    end
+
+    def source_path (object_path)
+      object_path.sub(/\.[^.]+\z/, ".c")
+    end
+
+    def directory_size (path)
+      Dir[File.join(path, "*")].sum { |entry|
+        File.file?(entry) ? File.size(entry) : 0
+      }
+    end
+
+    def last_used (path)
+      newest = Dir[File.join(path, "*")].map { |entry|
+        File.mtime(entry) rescue Time.at(0)
+      }.max
+      newest ? "last used #{newest.strftime('%Y-%m-%d')}" : "empty"
+    end
+
+    def human (bytes)
+      return "#{bytes} B" if bytes < 1024
+      units = ["KB", "MB", "GB"]
+      value = bytes.to_f
+      units.each do |unit|
+        value /= 1024
+        return format("%.1f %s", value, unit) if value < 1024
+      end
+      format("%.1f TB", value / 1024)
+    end
+
+  end
+
+end
+
+exit(CArrayJITCommand.run(ARGV))

data/carray-jit.gemspec

@@ -0,0 +1,41 @@
+Gem::Specification.new do |spec|
+  spec.name        = "carray-jit"
+  spec.version     = File.read(File.expand_path("lib/carray/jit/version.rb", __dir__))[/VERSION\s*=\s*"([^"]+)"/, 1]
+  spec.summary     = "JIT compilation of CArray kernels written in Ruby"
+  spec.description = <<~TEXT
+    Write the loop in Ruby, and it runs at the speed of C -- one to two orders
+    of magnitude faster than interpreted. It is for what a CArray expression
+    cannot say: a cell that reaches its neighbours, a recurrence, a loop
+    written out. What may be in a block is a subset of Ruby, and a C compiler
+    has to be present at run time.
+  TEXT
+  spec.authors     = ["himotoyoshi"]
+  spec.email       = ["himotoyoshi@users.noreply.github.com"]
+  spec.license     = "MIT"
+  spec.homepage    = "https://github.com/himotoyoshi/carray-jit"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "ext/**/*.{c,h,rb}",
+    "bin/*",
+    "examples/**/*.rb",
+    "examples/README.md",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "LICENSE",
+    "carray-jit.gemspec",
+    ".yardopts",
+  ]
+  spec.require_paths = ["lib"]
+  spec.bindir        = "bin"
+  spec.executables   = ["carray-jit"]
+  spec.extensions    = ["ext/carray_jit_access/extconf.rb"]
+
+  # A kernel reaches CArray's C by address, so the ceiling is the next minor.
+  spec.add_dependency "carray", ">= 3.0.1", "< 3.1"
+  # fiddle ships as a bundled gem; depend on it explicitly so Ruby 3.5+ resolves it.
+  spec.add_dependency "fiddle"
+end

data/docs/00_Introduction.md

@@ -0,0 +1,40 @@
+# Introduction
+
+carray-jit compiles a Ruby block into a C kernel that runs over CArray arrays. The block is not evaluated and is not a DSL: it is ordinary Ruby, read as source, translated to C, compiled by the system C compiler and called through Fiddle. What it computes is what the same block would have computed had Ruby run it, one cell at a time, at the speed of compiled C.
+
+## What CArray leaves out
+
+CArray works on a whole array at once. Arithmetic and the mathematical functions apply to every element, reductions summarise along the axes you name, and sorts and scans walk the data in C. All of that is already fast, and nothing here replaces it.
+
+What an array expression has no form for is a computation *between* elements. A cell that reads its neighbours. A cell that depends on the one computed before it. A loop whose length is not known until it runs. These are ordinary algorithms — a tridiagonal solve, a stencil with the boundary rule your problem actually has, a sieve, a recurrence from a paper — and until now writing one in Ruby meant a Ruby loop, and paying what the interpreter charges for every element.
+
+This library is for that gap. The parts of an algorithm that have an array form stay with CArray, where they are fastest; the part that does not becomes a kernel. Together they run an algorithm end to end without dropping into a Ruby loop.
+
+## A subset, chosen rather than found
+
+Not every Ruby block can become C. What may appear in one is a subset — arithmetic and comparison, locals, `if` and `while`, inner loops, subscripts at computed positions, the bitwise operators, the `Math` family, `raise` — and it was chosen deliberately, wide enough to state a numerical algorithm and narrow enough that each construct in it means in C exactly what Ruby means by it. Integer division floors. `%` is not `fmod`. A Complex divides by Smith's method in the order `complex.c` writes it.
+
+A block that steps outside the subset is refused, by name and with a line number, rather than quietly running as a Ruby loop. Nobody reaches for a compiler except to make something fast, so falling back silently would answer a question that was not asked.
+
+## Where a kernel gets its data
+
+A kernel reads and writes CArray arrays directly, in the memory CArray already holds them in. The arrays are the ones the block closes over, so nothing is named twice. Views are cells like any other — a column, a transpose, a slice of a slice — and are written in place without a copy. Masks propagate as CArray propagates them, and a kernel can ask whether a cell is missing.
+
+A kernel can also call C. `jit_extern` binds a function from any library Fiddle can open, and the kernel calls it at its address rather than reaching it per cell through Fiddle; `jit_function` compiles one from a Ruby block of your own and hands back a pure C function pointer, which a kernel can call, Ruby can call, and a C library that knows nothing about either can be given.
+
+Compiling costs something the first time and nothing afterwards: the shared object is cached on disk, keyed by the generated C and the compiler that built it, so a kernel is compiled once and reused by every later run.
+
+## Not only the blocks you write
+
+Installing this gem also puts the compiler behind `CArray.fuse`. An array expression written there is compiled rather than walked a node at a time — without being asked for, and without changing the answer. An expression the compiler cannot address goes back to CArray, which walks it and arrives at the same result. So a program that never writes a kernel still gets something from having the gem installed.
+
+## How this guide is arranged
+
+* [Getting started](01_GettingStarted.md) — the block, its extents, what the three methods return, and where a kernel stands beside `a + b * c` and `CArray.fuse`
+* [The shapes a kernel takes](02_KernelShapes.md) — work that reaches no neighbour, extents and subscripts, stencils, reductions, and contraction over a repeated index
+* [Supported features](03_SupportedFeatures.md) — locals and types, branches, raising, the types that are not just a number, calling C, and the recognized subset with what it refuses
+* [Compiling, caching and inspecting](04_Compiling.md) — what the first call costs, where kernels are kept, reading the generated C, the `carray-jit` command, and what the suite checks
+* [Design notes](05_DesignNotes.md) — decisions that were not obvious, and why
+* [Cheatsheet](06_Cheatsheet.md) — the seven `jit_` methods and `CArray.fuse` on one page, to look up rather than to read
+
+[examples/features/](../examples/features) is a tour of the same ground, one file per feature, and [examples/applications/](../examples/applications) holds small programs that use it to do something.

data/docs/01_GettingStarted.md

@@ -0,0 +1,80 @@
+# Getting started
+
+The block's parameters are the loop indices. Arrays and scalars are the variables it closes over -- `legendre` and `x` here -- so nothing is named twice, and the body reads like the Ruby loop it replaces.
+
+An extent is a `Range`, an `Integer` standing for `0...n`, or an `Enumerator::ArithmeticSequence` -- what `(high - 1).step(low, -1)` returns -- one per index. A whole array is therefore `CArray.jit_for(*array.dim) { ... }`.
+
+```ruby
+CArray.jit_for(1...(rows-1), 1...(columns-1)) { |i, j|
+  out[i, j] = 0.25 * (src[i-1, j] + src[i+1, j] + src[i, j-1] + src[i, j+1])
+}
+```
+
+`jit_for` returns the compiled kernel, whose `#c_source` is the C that ran. So does `jit_each`, the sibling method for work that reaches no neighbour and so needs neither an index nor an extent.  `jit_map` is that same method with its value asked for, and returns the array of results instead.
+
+[examples/applications/](../examples/applications) holds small programs that use this to do something -- a Game of Life, an implicit heat equation, edge detection, quality control on a sensor record -- each measured against the Ruby loop or the array expression it replaces. [examples/features/](../examples/features) is a tour of everything in these docs, one file per feature. `rake examples` runs them all.
+
+## Where the methods come from
+
+`CArray.jit_for`, `CArray.jit_each` and `CArray.jit_map` are named by CArray, which defines them to raise: they say that they compile their block, that the compiler is this gem, and that it is not installed. Installing it replaces them with the ones that compile.
+
+The name carries the rest. `jit_` says the block is read rather than run, and so has rules about what may be in it; a method called `per_cell` would not, and the subset would be something you found out about later. It also marks which methods need the compiler and which do not: an expression over whole arrays is `CArray.fuse`'s, and that one needs nothing installed.
+
+The line between these two falls where the block's names fall -- a block that names indices is `jit_for`'s, a block that names none is `jit_each`'s -- and each turns the other's block away rather than quietly doing something with it.
+
+## No fallback
+
+A block outside the compilable subset raises `CArray::JIT::Unsupported`, and so does one written with no compiler installed. Neither quietly runs the block as a Ruby loop instead.
+
+Nobody writes `jit_for` except to make a per-cell computation fast, so running it a hundred times slower would answer a question that was not asked, and would hide the difference behind a call that looks the same either way. An expression that can be written without a loop is better written as `CArray.fuse`, which is one pass with or without this gem.
+
+## Four ways to compute an expression, and what separates them
+
+CArray can evaluate `out = (a + b) * (c - a) + b * c - a` four ways now, and the line between them is not a factor -- it is what `n` gets multiplied by. `CArray.fuse` builds the expression rather than evaluating it a step at a time, and CArray walks what it built; requiring this gem registers a second evaluator (`CArray::JIT::Expression`), so an expression over an array worth compiling for is compiled instead. Where that line falls is CArray's to decide, not this gem's -- ten thousand cells today. So `fuse` is two rows here, and which one you get depends on whether the gem is installed.
+
+```
+n = 4,000,000
+                                 a + b * c      the longer expression
+  a + b * c ...                   1.30 ns/el          4.42 ns/el
+  CArray.fuse, walked             0.99 ns/el          2.13 ns/el
+  CArray.fuse, compiled here      0.74 ns/el          0.66 ns/el
+  jit_each { out = ... }          0.32 ns/el          0.30 ns/el
+```
+
+An expression of `k` operations is `k` passes over the data, and walking it rather than materialising it does not change that -- it changes what each pass costs, which is why the first two rows still grow with the expression, one more steeply than the other. Compiled, the expression is one pass however long it is, which is why the last two rows do not move at all.
+
+Memory separates them again, on a different line. Summing `(a + b*1) + (a + b*2) + ...`, peak resident over two arrays of eight million doubles, one array being 61 MB (`benchmark/footprint.rb`):
+
+```
+  terms                               1      2      3      4      6
+  a + b*k, summed                  +123   +245   +367   +488   +611
+  fuse walked, leaning left        +122   +184   +185   +183   +184
+  fuse walked, leaning right       +123   +184   +246   +306   +428
+  fuse compiled, leaning left       +62    +61    +61    +62    +61
+  fuse compiled, leaning right      +61    +62    +63    +62    +62
+  jit_each                           +0     +1     +1     +1     +1
+```
+
+**CArray** holds one array per term, exactly: each waits as an array until it is combined.
+
+**`fuse` walked** answers to the shape rather than the size, and the shape is which way the tree leans: a binary operation pulls its left operand into the buffer it was handed and takes a scratch only for its right, so leaning left descends for free and leaning right holds one buffer per level. The two rows are the same arithmetic written two ways, and they are not the same measurement. The scratch comes from an arena that keeps buffers warm rather than freeing them, so the peak is also what is still held afterwards.
+
+**`fuse` compiled** holds the result and nothing else: one array, whatever the expression says and whichever way it leans -- there is no operand to stage when every operation is in one loop.
+
+**A compiled kernel** holds nothing at all, because it was given the array to write into: a value never leaves a register between one operation and the next.
+
+Only the columns are comparable, not the rows against some other program's numbers: a peak belongs to a process, and the floor moves with whatever it loaded and allocated first.
+
+| | needs | passes | intermediates | reaches a neighbour |
+| --- | --- | --- | --- | --- |
+| `a + b * c` | -- | one per operation | one per operation | -- |
+| `CArray.fuse`, walked | -- | one per operation | one per right-spine level | -- |
+| `CArray.fuse`, compiled | a C compiler, or it walks | **one** | **none** | -- |
+| `CArray.jit_each` | a C compiler | **one** | **none** | no |
+| `CArray.jit_for` | a C compiler | **one** | **none** | **yes** |
+
+The last two need a compiler outright: without one they raise rather than run slowly, because a block written for them is written to be compiled and a Ruby loop over a million cells is not an answer.  `CArray.fuse` never raises for the want of one -- it asks whatever evaluator is registered and walks the expression itself when the answer is nobody, which is what makes it the thing to write where an expression over whole arrays is the whole of it.
+
+The last two are the same machinery and differ in what can be said, not in speed: a recurrence, a stencil and a reduction are `jit_for`'s and are not one pass in any of the others -- they are not expressible in them at all.
+
+What the table does not show is the compiling, which is about 250 ms the first time and 4 ms in a later process that finds the object on disk. For one pass over a small array the plain expression wins on wall clock and always will; see [What compiling costs](04_Compiling.md#what-compiling-costs-and-where-kernels-are-kept) for where the line falls.