carray-jit 0.1.0

data/examples/applications/moving_average.rb

@@ -0,0 +1,124 @@
+# Smoothing a time series, and measuring the drawdown
+#
+# These are the calculations CArray's operators cannot help with, because each
+# value depends on the one before it: an exponential moving average, a running
+# peak, the drawdown from that peak.  There is no way to write them as an
+# expression over whole arrays -- so ordinarily you write a Ruby loop and pay
+# for a block call per sample.
+#
+#   ruby examples/applications/moving_average.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 500_000
+random = Random.new(20260902)
+
+# A price series: a multiplicative random walk with a slow drift.
+price = CArray.double(n)
+value = 100.0
+n.times do |i|
+  value *= 1.0 + random.rand(-0.004..0.004) + 0.000002 * Math.sin(i / 5000.0)
+  price[i] = value
+end
+
+alpha = 0.02
+smoothed = CArray.double(n)
+peak = CArray.double(n)
+drawdown = CArray.double(n)
+
+smoothed[0] = price[0]
+peak[0] = price[0]
+
+# Exponential moving average.  One line, and the dependency on the previous
+# cell is exactly what the extent's direction records.
+CArray.jit_for(1...n) { |i|
+  smoothed[i] = alpha * price[i] + (1.0 - alpha) * smoothed[i-1]
+}
+
+# The running peak and the drawdown from it -- a branch per cell, which is
+# also why this is not an expression over arrays.
+CArray.jit_for(1...n) { |i|
+  if price[i] > peak[i-1]
+    peak[i] = price[i]
+  else
+    peak[i] = peak[i-1]
+  end
+  drawdown[i] = (price[i] - peak[i]) / peak[i]
+}
+
+worst = drawdown.min
+puts "#{n} samples"
+puts format("  last price      %.2f", price[n-1])
+puts format("  smoothed        %.2f", smoothed[n-1])
+puts format("  worst drawdown  %.2f%%  at sample %d", worst * 100, (drawdown.eq(worst)).where[0])
+
+# A rolling mean, as a cumulative sum and its own difference `window` cells
+# back.  The window is an ordinary local: an offset may be an integer the
+# block closed over, and it reaches the kernel as an argument, so changing the
+# window does not compile anything again.
+window = 200
+cumulative = CArray.double(n)
+rolling = CArray.double(n)
+cumulative[0] = price[0]
+CArray.jit_for(1...n) { |i| cumulative[i] = cumulative[i-1] + price[i] }
+CArray.jit_for(window...n) { |i|
+  rolling[i] = (cumulative[i] - cumulative[i - window]) / window
+}
+puts format("  rolling(%d)     %.2f", window, rolling[n-1])
+
+# The same three calculations as the Ruby loops they replace.
+def ruby_versions (price, alpha, n)
+  smoothed = Array.new(n, 0.0)
+  peak = Array.new(n, 0.0)
+  drawdown = Array.new(n, 0.0)
+  smoothed[0] = price[0]
+  peak[0] = price[0]
+  (1...n).each do |i|
+    smoothed[i] = alpha * price[i] + (1.0 - alpha) * smoothed[i-1]
+    peak[i] = price[i] > peak[i-1] ? price[i] : peak[i-1]
+    drawdown[i] = (price[i] - peak[i]) / peak[i]
+  end
+  [smoothed, peak, drawdown]
+end
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+reference_smoothed, _, reference_drawdown = ruby_versions(price, alpha, n)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+CArray.jit_for(1...n) { |i|
+  smoothed[i] = alpha * price[i] + (1.0 - alpha) * smoothed[i-1]
+}
+CArray.jit_for(1...n) { |i|
+  if price[i] > peak[i-1]
+    peak[i] = price[i]
+  else
+    peak[i] = peak[i-1]
+  end
+  drawdown[i] = (price[i] - peak[i]) / peak[i]
+}
+compiled = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("  %.1f ms in Ruby, %.1f ms compiled (%.0fx)",
+            interpreted * 1e3, compiled * 1e3, interpreted / compiled)
+puts "  same answers to the last bit: #{smoothed.to_a == reference_smoothed &&
+                                        drawdown.to_a == reference_drawdown}"
+
+# The series and its moving average, sampled at a hundred points.
+puts
+low, high = price.min, price.max
+levels = 14
+scale = ->(v) { ((v - low) / (high - low) * levels).round }
+raw = (0...100).map { |k| price[k * (n / 100)] }
+ema = (0...100).map { |k| smoothed[k * (n / 100)] }
+levels.downto(0) do |level|
+  row = (0...100).map { |k|
+    if scale.(ema[k]) == level then "-"
+    elsif scale.(raw[k]) == level then "."
+    else " "
+    end
+  }
+  puts "  " + row.join
+end
+puts "  price ., moving average -"

data/examples/applications/partial_sums.rb

@@ -0,0 +1,141 @@
+# Nine series summed in one pass -- the "partial sums" benchmark, as it is
+# written for an interpreter: one loop over d = 1..n, nine accumulators, and
+# no array anywhere in it.
+#
+# A kernel can be that program.  The accumulators are CScalars, which are the
+# one-cell arrays they subclass, and every iteration writing the one cell they
+# have is what makes an accumulator without asking for one.
+#
+# And the answers are the Ruby loop's, bit for bit, with nothing asked for:
+# the kernel's own loop over its extents is taken in the order the extents
+# say.  What may be split into partial sums -- the name of this file -- is an
+# *inner* loop, the reduction a cell does for itself, and the second half of
+# this program is the same harmonic sum written that way, where the order does
+# become a choice.
+#
+#   ruby examples/applications/partial_sums.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+N = 500_000
+
+def accumulators
+  Array.new(9) { CScalar.double() { 0.0 } }
+end
+
+def sum_series (n)
+  s0, s1, s2, s3, s4, s5, s6, s7, s8 = accumulators
+  CArray.jit_for(1..n) { |k|
+    d = k * 1.0
+    d2 = d * d
+    d3 = d2 * d
+    ds = Math.sin(d)
+    dc = Math.cos(d)
+    # The alternating sign is written from the index rather than carried in a
+    # variable: `alt = -alt` would be a chain from one iteration to the next,
+    # and this is the same sequence with no chain in it.
+    alt = k % 2 == 1 ? 1.0 : -1.0
+
+    s0[] = s0[] + (2.0 / 3.0) ** (d - 1.0)      # a geometric series
+    s1[] = s1[] + 1.0 / Math.sqrt(d)            # zeta(1/2), which diverges
+    s2[] = s2[] + 1.0 / (d * (d + 1.0))         # telescoping, to 1
+    s3[] = s3[] + 1.0 / (d3 * ds * ds)          # Flint Hills
+    s4[] = s4[] + 1.0 / (d3 * dc * dc)          # Cookson Hills
+    s5[] = s5[] + 1.0 / d                       # harmonic
+    s6[] = s6[] + 1.0 / d2                      # zeta(2)
+    s7[] = s7[] + alt / d                       # alternating harmonic
+    s8[] = s8[] + alt / (2.0 * d - 1.0)         # Gregory's series
+  }
+  [s0, s1, s2, s3, s4, s5, s6, s7, s8].map { |s| s[0] }
+end
+
+def sum_series_in_ruby (n)
+  s0 = s1 = s2 = s3 = s4 = s5 = s6 = s7 = s8 = 0.0
+  d_int = 1
+  while d_int <= n
+    d = d_int.to_f
+    d2 = d * d
+    d3 = d2 * d
+    ds = Math.sin(d)
+    dc = Math.cos(d)
+    alt = d_int % 2 == 1 ? 1.0 : -1.0
+    s0 = s0 + (2.0 / 3.0) ** (d - 1.0)
+    s1 = s1 + 1.0 / Math.sqrt(d)
+    s2 = s2 + 1.0 / (d * (d + 1.0))
+    s3 = s3 + 1.0 / (d3 * ds * ds)
+    s4 = s4 + 1.0 / (d3 * dc * dc)
+    s5 = s5 + 1.0 / d
+    s6 = s6 + 1.0 / d2
+    s7 = s7 + alt / d
+    s8 = s8 + alt / (2.0 * d - 1.0)
+    d_int = d_int + 1
+  end
+  [s0, s1, s2, s3, s4, s5, s6, s7, s8]
+end
+
+NAMES = ["(2/3)^(d-1)", "1/sqrt(d)", "1/(d(d+1))", "1/(d^3 sin^2 d)",
+         "1/(d^3 cos^2 d)", "1/d", "1/d^2", "(-1)^(d-1)/d",
+         "(-1)^(d-1)/(2d-1)"]
+
+sums = sum_series(N)
+in_ruby = sum_series_in_ruby(N)
+
+puts "nine series to d = #{N}"
+NAMES.each_with_index do |name, i|
+  puts format("  %-18s %19.13f   %s Ruby's",
+              name, sums[i], sums[i] == in_ruby[i] ? "==" : "!=")
+end
+
+# The telescoping sum has an exact answer to be judged against, which is
+# 1 - 1/(n+1).
+telescoped = 1.0 - 1.0 / (N + 1.0)
+puts
+puts format("  the telescoping sum is off by %.1e", (sums[2] - telescoped).abs)
+puts format("  every one of the nine matches the Ruby loop bit for bit: %s",
+            sums == in_ruby)
+
+# ------------------------------------------------------- where the order is a choice
+
+# The harmonic sum again, with the loop written inside the cell instead of
+# being the kernel's own.  That is a reduction, and a reduction's accumulator
+# may be split into partial sums: `reassociate: false` asks for the serial
+# order, and the default asks for the faster one, which by splitting the
+# accumulation is also what limits the cancellation.
+def harmonic (n, reassociate)
+  out = CScalar.double() { 0.0 }
+  CArray.jit_for(1, reassociate: reassociate) { |c|
+    total = 0.0
+    (1..n).each { |k| total = total + 1.0 / (k * 1.0) }
+    out[] = total
+  }
+  out[0]
+end
+
+split = harmonic(N, true)
+serial = harmonic(N, false)
+by_carray = (1.0 / CArray.double(N).seq!(1.0)).sum
+
+puts
+puts "the harmonic sum as an inner loop"
+puts format("  split into partial sums   %.15f", split)
+puts format("  the serial order          %.15f", serial)
+puts format("  serial == the outer loop above and Ruby's: %s", serial == sums[5])
+puts format("  split == CArray's own sum:                 %s", split == by_carray)
+
+# And what the pass costs each way.
+sum_series(N)                          # compiled and cached on the first call
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+3.times { sum_series(N) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 3
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+sum_series_in_ruby(N)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts
+puts format("one pass over %d terms", N)
+puts format("  compiled                       %6.1f ms", compiled * 1e3)
+puts format("  the same loop in Ruby          %6.1f ms (%.0fx)",
+            interpreted * 1e3, interpreted / compiled)

data/examples/applications/point_cloud.rb

@@ -0,0 +1,110 @@
+# Rotating a point cloud, then projecting it onto a basis
+#
+# Both are sums over an index that appears twice, which is what
+# `CArray.jit_contract` is: the repeated index is summed, so the notation is the
+# formula.
+#
+#   rotated[p,i] = sum_j R[i,j] x[p,j]           rotate every point
+#   cov[a,b]     = sum_p c[p,a] c[p,b]           the covariance of the cloud
+#   coeff[p,m]   = sum_k x[p,k] basis[m,k]       project onto a basis
+#   recon[p,k]   = sum_m coeff[p,m] basis[m,k]   and build the points back
+#
+# Written as loops these are three lines each and easy to get subtly wrong: an
+# index in the wrong place transposes the answer rather than failing.  Here the
+# parameter list states the axis order, and an index whose axes disagree is
+# refused before anything runs.
+#
+#   ruby examples/applications/point_cloud.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+count = 200_000
+random = Random.new(20260902)
+
+# A flattened, tilted blob: wide in x, narrower in y, nearly flat in z.
+points = CArray.double(count, 3) { |p, k| random.rand(-1.0..1.0) }
+points[nil, 1] = points[nil, 1] * 0.4
+points[nil, 2] = points[nil, 2] * 0.05
+
+angle = Math::PI / 6
+rotation = CArray.double(3, 3)
+rotation[0, nil] = [Math.cos(angle), -Math.sin(angle), 0.0]
+rotation[1, nil] = [Math.sin(angle),  Math.cos(angle), 0.0]
+rotation[2, nil] = [0.0, 0.0, 1.0]
+
+# j is summed because it appears twice; p and i are free, and they come out as
+# the result's axes in the order the block named them.
+rotated = CArray.jit_contract { |p, i, j| points[p, j] * rotation[i, j] }
+
+puts "#{count} points, rotated by #{(angle * 180 / Math::PI).round} degrees"
+puts "  spread per axis, before  #{points.stddev(axis: 0).to_a.map { |v| v.round(4) }.inspect}"
+puts "  after                    #{rotated.stddev(axis: 0).to_a.map { |v| v.round(4) }.inspect}"
+
+# The covariance: p is the index appearing twice, so p is what is summed --
+# the sum over points.  The same axis of the same array is read at two
+# independent positions, a and b, which is the whole shape of the thing.
+centred = rotated - rotated.mean(axis: 0).reshape(1, 3)
+covariance = CArray.jit_contract { |a, b, p| centred[p, a] * centred[p, b] } / count
+puts "  covariance"
+covariance.to_a.each { |row| puts "    " + row.map { |v| format('%9.5f', v) }.join }
+
+# Its trace does not change under a rotation, which checks both contractions
+# at once.
+original = points - points.mean(axis: 0).reshape(1, 3)
+before = CArray.jit_contract { |a, b, p| original[p, a] * original[p, b] } / count
+puts format("  trace %.8f before the rotation, %.8f after",
+            CArray.jit_contract { |a| before[a, a] }[0],
+            CArray.jit_contract { |a| covariance[a, a] }[0])
+
+# The plane the blob lies in, in the rotated frame: the two rows of the
+# rotation are an orthonormal basis for it.
+basis = rotation[0..1, nil]
+
+coefficients = CArray.jit_contract { |p, m, k| rotated[p, k] * basis[m, k] }
+reconstructed = CArray.jit_contract { |p, k, m| coefficients[p, m] * basis[m, k] }
+
+residual = ((rotated - reconstructed) ** 2).sum / count
+puts format("  dropping the third direction costs %.2e per point", residual)
+puts format("  which is the variance that was in it: %.2e",
+            rotated[nil, 2].stddev ** 2)
+
+# The distance of every point from the origin is *not* a contraction, and this
+# is the place the convention bites: in `x[p,k] * x[p,k]` the index p appears
+# twice as well, so it would be summed too and the answer would be one number.
+# A quantity per point is a per-cell loop, and says so.
+squared = CArray.double(count)
+CArray.jit_for(count) { |p|
+  total = 0.0
+  (0...3).each { |k| total = total + rotated[p, k] * rotated[p, k] }
+  squared[p] = total
+}
+puts format("  furthest point %.4f away", Math.sqrt(squared.max))
+
+# The same rotation written as a Ruby loop.
+reference = CArray.double(count, 3)
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+count.times do |p|
+  3.times do |i|
+    total = 0.0
+    3.times { |j| total += points[p, j] * rotation[i, j] }
+    reference[p, i] = total
+  end
+end
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+CArray.jit_contract { |p, i, j| points[p, j] * rotation[i, j] }
+compiled = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("  rotation: %.1f ms compiled, %.0f ms as a Ruby loop (%.0fx)",
+            compiled * 1e3, interpreted * 1e3, interpreted / compiled)
+puts "  identical: #{rotated.to_a == reference.to_a}"
+
+# An index whose axes disagree is the mistake this notation exists to catch.
+begin
+  wrong = CArray.double(4, 4).seq!(1.0)
+  CArray.jit_contract { |p, i, j| points[p, j] * wrong[i, j] }
+rescue CArray::JIT::Unsupported => error
+  puts "  refused:  #{error.message.lines.first.strip}"
+end

data/examples/applications/quicksort.rb

@@ -0,0 +1,118 @@
+# Quicksort, written in Ruby and compiled to a C function.
+#
+# CArray already sorts, and this is not a better sort -- it is the naive
+# textbook one, last element as the pivot.  What it shows is that the body of
+# a C function can be written here: it takes a pointer and two indices, walks
+# the run, swaps through the pointer, and calls itself.  The block stays
+# runnable in Ruby, so the same partition can be watched from either side.
+#
+#   ruby examples/applications/quicksort.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+# The declaration is C's own, and it is what settles everything: `double v[]`
+# is a run of numbers the function may write, `int64_t` the indices, and the
+# name in the declaration is what puts the function in scope inside its own
+# body -- an anonymous `double (*)(...)` has nothing to call itself by.
+#
+# There is no `void` here because a compiled body has to produce a value, so
+# the return is the C convention for "nothing went wrong".
+quicksort = CArray.jit_function(
+  "int quicksort(double v[], int64_t low, int64_t high)"
+) { |v, low, high|
+  if low < high
+    pivot = v[high]                        # Lomuto's partition, as written
+    smaller = low - 1
+    scan = low
+    while scan < high
+      if v[scan] <= pivot
+        smaller = smaller + 1
+        held = v[smaller]
+        v[smaller] = v[scan]
+        v[scan] = held
+      end
+      scan = scan + 1
+    end
+    held = v[smaller+1]
+    v[smaller+1] = v[high]
+    v[high] = held
+    # Called for what they do to the run; the 0 each answers goes nowhere,
+    # which is what a call standing where a statement stands means here and
+    # in C.
+    quicksort.call(v, low, smaller)
+    quicksort.call(v, smaller + 2, high)
+  end
+  0
+}
+
+n = 200_000
+random = Random.new(20260905)
+values = CArray.double(n) { |i| random.rand }
+
+sorted = values.copy                       # `to_ca` would answer this array
+quicksort.call(sorted, 0, n - 1)
+
+puts "quicksort"
+puts "  sorted                 #{(0...n-1).all? { |i| sorted[i] <= sorted[i+1] }}"
+puts "  same cells as CArray   #{sorted.to_a == values.sort.to_a}"
+
+# The block is still there, and still Ruby.  Run that way the partition is
+# interpreted and the two halves go back through the compiled function, which
+# is the same body reached by the other road.
+in_ruby = values[0...200].copy
+quicksort.block.call(in_ruby, 0, 199)
+puts "  the block agrees       #{in_ruby.to_a == values[0...200].sort.to_a}"
+
+# ------------------------------------------------------------- what it costs
+
+def timed (repeats)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  repeats.times { yield }
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / repeats
+end
+
+scratch = values.copy
+compiled = timed(5) { scratch[nil] = values; quicksort.call(scratch, 0, n - 1) }
+carray = timed(5) { values.sort }
+ruby_array = timed(5) { values.to_a.sort }
+
+def ruby_quicksort (v, low, high)
+  return if low >= high
+  pivot = v[high]
+  smaller = low - 1
+  (low...high).each do |scan|
+    if v[scan] <= pivot
+      smaller += 1
+      v[smaller], v[scan] = v[scan], v[smaller]
+    end
+  end
+  v[smaller+1], v[high] = v[high], v[smaller+1]
+  ruby_quicksort(v, low, smaller)
+  ruby_quicksort(v, smaller + 2, high)
+end
+
+interpreted_source = values.to_a
+interpreted = timed(1) { ruby_quicksort(interpreted_source.dup, 0, n - 1) }
+
+puts
+puts format("%d doubles", n)
+puts format("  this quicksort, compiled   %6.1f ms", compiled * 1e3)
+puts format("  CArray#sort                %6.1f ms", carray * 1e3)
+puts format("  Array#sort                 %6.1f ms", ruby_array * 1e3)
+puts format("  the same partition in Ruby %6.1f ms (%.0fx)",
+            interpreted * 1e3, interpreted / compiled)
+
+# The textbook partition lands beside CArray#sort, which is the honest
+# reading of it: both are C walking the same memory, and this one is measured
+# with the copy it needs included.  Beating it was never the point -- CArray
+# sorts already.  What the compiled body is worth is the case where no such
+# method exists: an order nobody wrote a sort for, a key computed as you go,
+# a run inside a structure CArray has no name for.
+#
+# Two things this naive version keeps that a library sort does not: the pivot
+# is the last element, so an already-sorted run partitions n times and the
+# recursion is n deep, and a compiled function that recurses too deep is a
+# SIGSEGV rather than a SystemStackError.  That is C's bargain, taken here
+# along with the pointer.  A median-of-three pivot is three more lines, and
+# the reason to write them.

data/examples/applications/recursion.rb

@@ -0,0 +1,121 @@
+# The classic recursive benchmarks, as compiled C functions.
+#
+# fib, tak, tarai and ackermann are what an interpreter is measured on, and
+# none of them is an array computation: no cell, no extent, nothing to be
+# element-wise about.  What they are is a scalar function calling itself,
+# which is `jit_function`'s -- a body written in Ruby, compiled to C, and
+# callable from Ruby or from a kernel.
+#
+# A declaration that gives a *name* puts that name in scope inside its own
+# body, as C does, so the function can recurse.  The spelling is `.call`, the
+# one every C function takes here, and that is what keeps the block runnable:
+# the same block is the reference the compiled function is checked against.
+#
+# The parameters are the ones these benchmarks are usually quoted at, so the
+# ratios below can be read beside anyone else's.
+#
+#   ruby examples/applications/recursion.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+fib = CArray.jit_function("int64_t fib(int64_t n)") { |n|
+  n < 2 ? n : fib.call(n - 1) + fib.call(n - 2)
+}
+
+tak = CArray.jit_function("int64_t tak(int64_t x, int64_t y, int64_t z)") { |x, y, z|
+  y < x ? tak.call(tak.call(x - 1, y, z),
+                   tak.call(y - 1, z, x),
+                   tak.call(z - 1, x, y)) : z
+}
+
+tarai = CArray.jit_function("int64_t tarai(int64_t x, int64_t y, int64_t z)") { |x, y, z|
+  x <= y ? y : tarai.call(tarai.call(x - 1, y, z),
+                          tarai.call(y - 1, z, x),
+                          tarai.call(z - 1, x, y))
+}
+
+ack = CArray.jit_function("int64_t ack(int64_t m, int64_t n)") { |m, n|
+  m == 0 ? n + 1 : (n == 0 ? ack.call(m - 1, 1) : ack.call(m - 1, ack.call(m, n - 1)))
+}
+
+# The same four in Ruby, which is both the answer to check against and the
+# time to measure against.
+def fib_rb (n) = n < 2 ? n : fib_rb(n - 1) + fib_rb(n - 2)
+def tak_rb (x, y, z) = y < x ? tak_rb(tak_rb(x - 1, y, z), tak_rb(y - 1, z, x), tak_rb(z - 1, x, y)) : z
+def tarai_rb (x, y, z) = x <= y ? y : tarai_rb(tarai_rb(x - 1, y, z), tarai_rb(y - 1, z, x), tarai_rb(z - 1, x, y))
+def ack_rb (m, n) = m == 0 ? n + 1 : (n == 0 ? ack_rb(m - 1, 1) : ack_rb(m - 1, ack_rb(m, n - 1)))
+
+def timed
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  value = yield
+  [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
+end
+
+CASES = [
+  ["fib(34)",       -> (f) { f.call(34) },        -> { fib_rb(34) }],
+  ["tak(18, 9, 0)", -> (f) { f.call(18, 9, 0) },  -> { tak_rb(18, 9, 0) }],
+  ["tarai(12, 6, 0)", -> (f) { f.call(12, 6, 0) }, -> { tarai_rb(12, 6, 0) }],
+  ["ack(3, 9)",     -> (f) { f.call(3, 9) },      -> { ack_rb(3, 9) }],
+]
+
+puts "a recursion compiled, and the same one interpreted"
+[fib, tak, tarai, ack].zip(CASES) do |function, (name, compiled_call, ruby_call)|
+  compiled_call.call(function)                      # compiled on the way in
+  answer, took = timed { compiled_call.call(function) }
+  in_ruby, ruby_took = timed { ruby_call.call }
+  puts format("  %-16s %8d  %7.1f ms compiled  %7.1f ms in Ruby  (%4.0fx)  %s",
+              name, answer, took * 1e3, ruby_took * 1e3, ruby_took / took,
+              answer == in_ruby ? "agree" : "DIFFER")
+end
+
+# What the block is for
+# ---------------------
+# The function keeps the block it was written from, so the compiled recursion
+# and the Ruby one are the same text and can be put side by side.  That is
+# what makes "it means what Ruby means by it" checkable rather than argued.
+puts
+puts "  the block is still there: fib.block.call(20) = #{fib.block.call(20)}, " \
+     "fib.call(20) = #{fib.call(20)}"
+
+# Where a kernel comes in
+# -----------------------
+# A compiled function is not only faster to run, it is reachable per cell: the
+# kernel calls the address directly, rather than crossing back into Ruby -- or
+# into Fiddle, which costs a few hundred nanoseconds a cell, more than most of
+# what it would be called for.
+inputs = CArray.int64(24).seq!(1)
+outputs = CArray.int64(24)
+
+CArray.jit_for(24) { |i| outputs[i] = fib.call(inputs[i]) }
+
+puts
+puts "fib over an array, one call per cell"
+puts "  #{outputs[0..11].to_a.inspect}"
+puts "  matches Ruby            #{outputs.to_a == inputs.to_a.map { |n| fib_rb(n) }}"
+
+_, per_cell = timed { CArray.jit_for(24) { |i| outputs[i] = fib.call(inputs[i]) } }
+_, in_ruby = timed { inputs.to_a.map { |n| fib_rb(n) } }
+puts format("  the pass: %.1f ms compiled, %.1f ms in Ruby (%.0fx)",
+            per_cell * 1e3, in_ruby * 1e3, in_ruby / per_cell)
+
+# What is not on offer
+# --------------------
+# An anonymous declaration -- the function-pointer type -- has nothing to call
+# itself by, which is C's position too: it is the name in the declaration that
+# is put in scope inside the body, and `int64_t (*)(int64_t)` has none.  The
+# `f` below is then an ordinary Ruby local seen from inside, which is a
+# capture, and a capture is what a compiled function does not get.
+begin
+  f = CArray.jit_function("int64_t (*)(int64_t)") { |n|
+    n < 2 ? n : f.call(n - 1) + f.call(n - 2)
+  }
+rescue CArray::JIT::Unsupported => error
+  puts
+  puts "an anonymous declaration"
+  puts "  #{error.message.sub(/ \(at line.*/m, "")}"
+end
+
+# And nothing here stops a recursion running out of stack: a compiled function
+# that goes too deep is a SIGSEGV, not a SystemStackError.  That is C's
+# bargain, taken knowingly -- the same one the `while` loop in a kernel takes.