carray-jit 0.1.0

data/examples/features/05_reduction.rb

@@ -0,0 +1,90 @@
+# Reductions: an inner loop per output cell.
+#
+# The caller says where the answer goes and the kernel fills that cell.  What
+# makes it expressible is `(from...to).each { |j| ... }` -- an inner loop whose
+# index addresses arrays but writes nothing -- so sum, maximum, product, count
+# and a dot product all fall out of ordinary block-locals, with no primitive
+# for any of them.  `n.times { |j| ... }` is the same loop from zero.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+rows, columns = 5, 7
+source = CArray.double(rows, columns).seq!(1.0)
+total = CArray.double(rows)
+largest = CArray.double(rows)
+positives = CArray.int32(rows)
+
+CArray.jit_for(rows) { |i|
+  accumulator = 0.0
+  (0...columns).each { |j| accumulator = accumulator + source[i, j] }
+  total[i] = accumulator
+}
+
+CArray.jit_for(rows) { |i|
+  best = source[i, 0]
+  (1...columns).each { |j|
+    if source[i, j] > best
+      best = source[i, j]
+    end
+  }
+  largest[i] = best
+}
+
+CArray.jit_for(rows) { |i|
+  count = 0
+  (0...columns).each { |j|
+    if source[i, j] > 20.0
+      count = count + 1
+    end
+  }
+  positives[i] = count
+}
+
+puts "row reductions"
+puts "  sum      #{total.to_a.inspect}"
+puts "  matches  #{total.to_a == source.to_a.map { |row| row.sum }}"
+puts "  max      #{largest.to_a.inspect}"
+puts "  count    #{positives.to_a.inspect}"
+
+# A matrix multiply is the same shape of thing: two output indices and one
+# inner loop.
+left = CArray.double(3, 4).seq!(1.0)
+right = CArray.double(4, 2).seq!(0.5, 0.5)
+product = CArray.double(3, 2)
+
+CArray.jit_for(3, 2) { |i, j|
+  accumulator = 0.0
+  (0...4).each { |t| accumulator = accumulator + left[i, t] * right[t, j] }
+  product[i, j] = accumulator
+}
+
+reference = Array.new(3) { |i| Array.new(2) { |j|
+  (0...4).sum { |t| left[i, t] * right[t, j] } } }
+
+puts "  matmul   #{product.to_a.inspect}"
+puts "  matches  #{product.to_a == reference}"
+
+# The accumulator is split into partial sums, as sum(axis:) splits its own:
+# a serial chain waits out the latency of each addition, and the split answer
+# is usually the more accurate one as well as the faster.  It is not the order
+# the same loop takes in Ruby, and `reassociate: false` is what asks for that.
+#
+# CArray's own reductions are faster than this still, their kernels being
+# written for the shape.  What this is for is the reductions that have no such
+# method -- the ones where the body is an algorithm rather than an operator.
+puts "  note     CArray#sum(axis: 1) is the faster way to write the first one"
+puts
+
+# Counting from zero is what an inner loop mostly does, and `n.times` says it
+# without naming an end.  It compiles to the loop the range spells out --
+# `(0...n).each` -- so the choice is the reader's, not the compiler's.
+counted = CArray.double(rows)
+CArray.jit_for(rows) { |i|
+  accumulator = 0.0
+  columns.times { |j| accumulator = accumulator + source[i, j] }
+  counted[i] = accumulator
+}
+puts "the same sums, written with times"
+puts "  #{counted.to_a.inspect}"
+puts "  matches the range spelling  #{counted.to_a == total.to_a}"

data/examples/features/06_jit_contract.rb

@@ -0,0 +1,58 @@
+# Contractions: an index that appears twice is summed.
+#
+# An index that appears twice in the term is summed -- the repetition is what
+# stands in for the sigma.  No extents are given, because each index's extent
+# is fixed by the axes it addresses, and an index whose axes disagree is
+# refused: that shape check is what a contraction is for.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+a = CArray.double(3, 4).seq!(1.0)
+b = CArray.double(4, 2).seq!(0.5, 0.5)
+v = CArray.double(4).seq!(1.0)
+p = CArray.double(3).seq!(1.0)
+r = CArray.double(2).seq!(10.0, 10.0)
+q = CArray.double(3, 3).seq!(1.0)
+
+matmul = CArray.jit_contract { |i, j, k| a[i,k] * b[k,j] }  # k is summed
+matvec = CArray.jit_contract { |i, k|    a[i,k] * v[k]    }  # k is summed
+dot    = CArray.jit_contract { |i, k|    a[i,k] * a[i,k]  }  # both, one cell
+trace  = CArray.jit_contract { |i|       q[i,i]           }  # one array, twice
+outer  = CArray.jit_contract { |i, j|    p[i] * r[j]      }  # nothing summed
+
+puts "contractions"
+puts "  a . b     #{matmul.to_a.inspect}"
+puts "  a . v     #{matvec.to_a.inspect}"
+puts "  |a|^2     #{dot[0]}   (#{a.to_a.flatten.sum { |e| e * e }})"
+puts "  tr q      #{trace[0]}"
+puts "  p (x) r   #{outer.to_a.inspect}"
+
+# The result's axes are the free indices in the order the block named them, so
+# the parameter list is where the axis order is stated -- and swapping two
+# parameters transposes.
+transposed = CArray.jit_contract { |j, i, k| a[i,k] * b[k,j] }
+puts "  swapped   #{transposed.dim.inspect} vs #{matmul.dim.inspect}"
+
+# Assigning into an array of your own says where to put it instead.  It must
+# name exactly the free indices, and still does not decide what is summed.
+destination = CArray.double(3, 2)
+CArray.jit_contract { |i, j, k| destination[i,j] = a[i,k] * b[k,j] }
+puts "  into mine #{destination.to_a == matmul.to_a}"
+
+# A sum along an axis is not a contraction: there is nothing in a[i,k]
+# standing in for a sigma.
+begin
+  total = CArray.double(3)
+  CArray.jit_contract { |i, k| total[i] = a[i,k] }
+rescue CArray::JIT::Unsupported => error
+  puts "  refused:  #{error.message.lines.first.strip}"
+end
+
+# Nor is a shape mismatch let through.
+begin
+  wrong = CArray.double(5, 2)
+  CArray.jit_contract { |i, j, k| a[i,k] * wrong[k,j] }
+rescue CArray::JIT::Unsupported => error
+  puts "  refused:  #{error.message.lines.first.strip}"
+end

data/examples/features/07_masks.rb

@@ -0,0 +1,55 @@
+# Masks: cells that hold no value.
+#
+# `a[i] == UNDEF` is how Ruby already asks whether a cell is missing, and it
+# means the same here -- it reads the mask byte, never the value.  Asking about
+# the mask is not reading the value, so what the branch writes carries no mask,
+# which is what makes filling a hole possible.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 7
+source = CArray.double(n).seq!(1.0)
+source[2] = UNDEF
+
+# Filling the holes.  This is an ordinary Ruby loop as well, so it can be
+# checked against one.
+filled = CArray.double(n)
+CArray.jit_for(n) { |i|
+  if source[i] == UNDEF
+    filled[i] = 0.0
+  else
+    filled[i] = Math.sqrt(source[i])
+  end
+}
+
+reference = (0...n).map { |i| source[i] == UNDEF ? 0.0 : Math.sqrt(source[i]) }
+
+puts "masks"
+puts "  filled            #{filled.to_a.map { |e| e.round(4) }.inspect}"
+puts "  matches Ruby      #{filled.to_a == reference}"
+# The array that was written gets a mask because the kernel is a masked one;
+# what matters is that no cell in it is missing.
+puts "  cells missing     #{filled.count_masked} (a mask exists, but it is empty)"
+
+# Left implicit, the mask propagates as CArray's own operators propagate it:
+# any cell that fed a result masks that result, following the offsets, so each
+# output takes its mask from its own inputs rather than from everything the
+# body read.
+neighbours = CArray.double(n)
+CArray.jit_for(1...(n-1)) { |i| neighbours[i] = source[i-1] + source[i+1] }
+puts "  propagated        #{neighbours.to_a.inspect}"
+puts "  masked where      #{(0...n).select { |i| neighbours[i] == UNDEF }.inspect} (the cells reading source[2])"
+
+# Writing UNDEF marks a cell missing.  Mentioning UNDEF at all makes the kernel
+# a masked one, whatever its arrays happen to carry.
+clipped = CArray.double(n).seq!(1.0)
+CArray.jit_for(n) { |i|
+  if clipped[i] > 4.0
+    clipped[i] = UNDEF
+  end
+}
+puts "  marked missing    #{clipped.to_a.inspect}"
+
+# A branch with no else writes nothing on the path not taken, so those cells
+# keep both their value and their mask -- as the same `if` would in Ruby.

data/examples/features/08_views.rb

@@ -0,0 +1,46 @@
+# Views are written in place, without a copy.
+#
+# A column of a matrix, a transpose, a slice of a slice: these are the things
+# views exist for, and a kernel that only accepted a contiguous array would
+# make the caller copy them in and out again.  Where a view folds to a stride
+# expression -- which a column, a reversal and a transpose all do -- the kernel
+# addresses the original memory and the write lands in the parent.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+# A column: its stride is the row pitch, not the element size.
+matrix = CArray.double(8, 3)
+column = matrix[nil, 1]
+column[0] = 1.0
+
+CArray.jit_for(1...8) { |i| column[i] = column[i-1] * 2.0 + 1.0 }
+
+puts "views"
+puts "  column written    #{matrix[nil, 1].to_a.inspect}"
+puts "  others untouched  #{matrix[nil, 0].to_a.all?(0.0) && matrix[nil, 2].to_a.all?(0.0)}"
+
+# A reversed view has a negative stride, and a slice of a slice folds to one
+# offset and one stride however many times it was sliced.
+array = CArray.double(20).seq!
+inner = array[4..15][2..9]
+CArray.jit_for(8) { |i| inner[i] = -inner[i] }
+puts "  slice of a slice  #{array[5..14].to_a.inspect}"
+
+# A transpose is read at its own indices; nothing is materialised.
+source = CArray.double(4, 3).seq!(1.0)
+transposed = source.transpose
+result = CArray.double(3, 4)
+CArray.jit_for(*transposed.dim) { |i, j| result[i, j] = transposed[i, j] * 2.0 }
+puts "  transposed read   #{result.to_a == (source.transpose * 2.0).to_a}"
+
+# A view with no stride expression -- a gather, say -- cannot be addressed
+# arithmetically, so the cells the kernel asked for are transferred and written
+# back.  The cost is proportional to the region, not to the view: the kernel
+# knows its extents and its offsets before it runs, so it asks for the box it
+# will touch and no more.
+whole = CArray.double(64).seq!
+gathered = whole[whole >= 0.0]
+gathered[10] = 1.0
+CArray.jit_for(11...14) { |i| gathered[i] = gathered[i-1] * 2.0 }
+puts "  gather region     #{whole[9..14].to_a.inspect} (9 and 14 outside the box)"

data/examples/features/09_inspecting.rb

@@ -0,0 +1,55 @@
+# Seeing what was compiled, and what is refused.
+#
+# The generated C is the debugging surface: `jit_for` returns the kernel, and
+# the kernel carries its source.  Running with CARRAY_JIT_DUMP=1 prints the
+# same thing for every kernel as it is compiled, and `carray-jit list` / `show`
+# report what is cached on disk between runs.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+values = CArray.double(16).seq!(1.0)
+
+def sweep (values)
+  CArray.jit_for(1...values.dim[0]) { |i| values[i] = Math.sqrt(values[i-1]) + 1.0 }
+end
+
+kernel = sweep(values)
+
+# The contiguous loop, as it was handed to the compiler.
+puts "generated C"
+puts kernel.c_source[/^static void\ncarray_jit_contiguous.*?^\}$/m].lines.map { |line| "  " + line.rstrip }
+
+# Every kernel carries two loops and decides between them once, outside the
+# loop: the contiguous form indexes a typed pointer and can be vectorised, the
+# strided form is what lets a view run without being copied first.
+puts "  both loops present  #{%w[carray_jit_contiguous carray_jit_strided].all? { |name| kernel.c_source.include?(name) }}"
+
+# Compiling happens once.  The second call finds the object already loaded, the
+# second run of the script finds it on disk.
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+sweep(values)
+again = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+puts "  second call         #{format('%.4f ms', again * 1e3)} (the same block, already loaded)"
+
+# Anything outside the subset raises rather than falling back, and says where.
+# A silent fallback would turn a typo into a performance mystery.
+puts
+puts "refused"
+[
+  proc { CArray.jit_for(16) { |i| values[i] = values.to_a.max } },
+  proc { CArray.jit_for(16) { |i| values[i] = "text" } },
+  proc { n = 0; CArray.jit_for(16) { |i| while n < 3 do n += 1 end } },
+].each do |attempt|
+  begin
+    attempt.call
+  rescue CArray::JIT::Unsupported => error
+    puts "  #{error.message.lines.first.strip}"
+  end
+end
+
+puts
+puts "the cache lives under #{CArray::JIT::Compiler.cache_directory}"
+puts "  carray-jit list          what is cached for this environment"
+puts "  carray-jit show <prefix> the C source of one cached kernel"
+puts "  carray-jit clear         remove it"

data/examples/features/10_complex.rb

@@ -0,0 +1,107 @@
+# Complex arrays: cmplx64 and cmplx128, computed in `double _Complex`.
+#
+# The interesting part is not that it works but what it costs to make the
+# answer Ruby's rather than C's: Ruby's Complex arithmetic differs from the C
+# operators in the last bit and in the sign of a zero, so three of the four
+# operators are compiled to match Ruby rather than to match C.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 8
+# A spiral, so that the magnitude has something to say.
+signal = CArray.cmplx128(n) { |i|
+  Complex(Math.cos(i * 0.7), Math.sin(i * 0.7)) * (1.0 + 0.25 * i)
+}
+
+# Arithmetic, a captured Complex scalar, and an imaginary literal.
+rotation = Complex(0.0, 1.0)
+rotated = CArray.cmplx128(n)
+CArray.jit_for(n) { |i| rotated[i] = signal[i] * rotation + 0.5i }
+
+reference = (0...n).map { |i| signal[i] * rotation + 0.5i }
+puts "complex arithmetic"
+puts "  matches Ruby      #{(0...n).all? { |i| rotated[i] == reference[i] }}"
+
+# The way out of the complex type.  `abs`, `real`, `imag` and `arg` hand back
+# a Float, which is what lets a complex kernel write into a real array;
+# `conjugate` stays complex.
+power = CArray.double(n)
+phase = CArray.double(n)
+CArray.jit_for(n) { |i| power[i] = signal[i].abs }
+CArray.jit_for(n) { |i| phase[i] = signal[i].arg }
+puts "  power             #{power.to_a.map { |e| e.round(4) }.inspect}"
+puts "  phase             #{phase.to_a.map { |e| e.round(4) }.inspect}"
+
+# And the way in, from two real arrays.
+real = CArray.double(n).seq!(1.0)
+imaginary = CArray.double(n).seq!(0.0, 0.25)
+built = CArray.cmplx128(n)
+CArray.jit_for(n) { |i| built[i] = Complex(real[i], imaginary[i]) }
+puts "  built from parts  #{built.to_a.first(3).inspect}"
+
+# The fifteen functions a complex CArray answers compile to their C99
+# c-prefixed forms.  Which fifteen is CArray's list, not a list invented here,
+# so a formula gives the same answer whichever way it is applied.
+transformed = CArray.cmplx128(n)
+CArray.jit_for(n) { |i| transformed[i] = signal[i].tanh }
+puts "  tanh matches the array operator #{transformed.to_a == signal.tanh.to_a}"
+
+# A reduction over complex cells: the accumulator starts from a complex zero.
+total = CArray.cmplx128(1)
+CArray.jit_for(1) { |i|
+  running = Complex(0.0, 0.0)
+  (0...n).each { |j| running = running + signal[j] }
+  total[i] = running
+}
+serial = (0...n).inject(Complex(0.0, 0.0)) { |sum, j| sum + signal[j] }
+puts "  sum               #{total[0].rectangular.map { |e| e.round(6) }.inspect}"
+puts "  matches Ruby      #{total[0] == serial}"
+
+# Where Ruby and C part company.  A real operand carries an exact Integer zero
+# as its imaginary part, and Ruby's own arithmetic returns the other operand
+# untouched rather than combining with it -- so the sign of a zero survives an
+# addition that C's `+` would flatten.
+edge = CArray.cmplx128(1)
+edge[0] = Complex(1.0, -0.0)
+kept = CArray.cmplx128(1)
+CArray.jit_for(1) { |i| kept[i] = edge[i] + 2.0 }
+puts
+puts "signed zeros"
+puts "  Ruby              #{(Complex(1.0, -0.0) + 2.0)}"
+puts "  the kernel        #{kept[0]}"
+puts "  widening first    #{Complex(1.0, -0.0) + Complex(2.0, 0.0)}   <- what C's + would give"
+
+# `**` is the one operation whose answer is not the Ruby loop's to the last
+# bit: Ruby raises a Complex to a power by binary powering, cpow goes round
+# through exp and log.  A few machine epsilons apart, growing with the
+# exponent -- and `z * z` is both exact and cheaper than the library call.
+cubed = CArray.cmplx128(n)
+CArray.jit_for(n) { |i| cubed[i] = signal[i] ** 3 }
+worst = (0...n).map { |i| e = signal[i] ** 3; (cubed[i] - e).abs / e.abs }.max
+
+squared = CArray.cmplx128(n)
+CArray.jit_for(n) { |i| squared[i] = signal[i] * signal[i] }
+
+puts
+puts "the one inexact operation"
+puts "  z ** 3 worst      #{(worst / Float::EPSILON).round(1)} machine epsilons"
+puts "  z * z  matches Ruby exactly #{(0...n).all? { |i| squared[i] == signal[i] * signal[i] }}"
+
+# What is refused on a Complex is what Ruby refuses, and nothing else: the
+# ordering comparisons, `%`, the rounding methods and the bit operators.
+puts
+puts "refused, as Ruby refuses them"
+[["->(i) { power[i] = signal[i] < 1.0 ? 1.0 : 0.0 }",
+  proc { CArray.jit_for(n) { |i| power[i] = signal[i] < 1.0 ? 1.0 : 0.0 } }],
+ ["->(i) { power[i] = signal[i].floor }",
+  proc { CArray.jit_for(n) { |i| power[i] = signal[i].floor } }],
+ ["->(i) { power[i] = signal[i] }",
+  proc { CArray.jit_for(n) { |i| power[i] = signal[i] } }]].each do |written, run|
+  begin
+    run.call
+  rescue CArray::JIT::Unsupported => error
+    puts "  #{written}"
+    puts "    #{error.message.sub(/ \(at line.*/, '')}"
+  end
+end

data/examples/features/11_c_functions.rb

@@ -0,0 +1,260 @@
+# C functions in a kernel: the ones already compiled, and the ones written
+# here.
+#
+# math.h is already handled -- `Math.sqrt(x)` compiles to `sqrt(x)` and the
+# compiler can inline it.  This is for everything else: the Bessel functions
+# in libm that Ruby has no Math method for, and, the same way, anything in a
+# library you can dlopen.
+#
+# Two methods, because they do two different things.  `jit_extern` finds one
+# someone else compiled -- `extern` is C's word for a body that lives
+# elsewhere, and finding it is Fiddle's job, with no compiler involved.
+# `jit_function` compiles a body of your own.  What comes back is the same
+# kind of object either way, so a kernel calls it without knowing which it is.
+#
+# The *call* is not Fiddle's, either way: reaching a function through
+# Fiddle::Function costs a few hundred nanoseconds per cell, which is more
+# than the arithmetic it was called for.  Fiddle is asked where the function
+# is; the kernel calls it.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+require "benchmark"
+
+# The prototype is what you would copy out of the header.  With no `from:`,
+# the symbol is looked for in what the process has already loaded, which is
+# where libm's own functions are.
+j0 = CArray.jit_extern("double j0(double)")
+puts "bound: #{j0}"
+
+x = CArray.double(6).seq!(1.0)
+out = CArray.double(6)
+
+CArray.jit_each { out = j0.call(x) }
+puts "j0(x)         #{out.to_a.map { |v| v.round(6) }.inspect}"
+puts "same in Ruby  #{x.to_a.map { |v| j0.call(v).round(6) }.inspect}"
+puts
+
+# What "apply f to an array" cannot say
+# -------------------------------------
+# A stencil needs the function at two places at once.  There is no array of
+# intermediate results to hold them, so this is not expressible as a map --
+# but it is an ordinary kernel.
+
+smoothed = CArray.double(6)
+CArray.jit_for(1...6) { |i| smoothed[i] = 0.5 * (j0.call(x[i]) + j0.call(x[i-1])) }
+puts "half-sum of neighbouring j0"
+puts "  #{smoothed[1..5].to_a.map { |v| v.round(6) }.inspect}"
+puts
+
+# It mixes into an expression like anything else, and takes as many arguments
+# as the prototype says.
+atan2 = CArray.jit_extern("double atan2(double, double)")
+y = CArray.double(6).seq!(0.5, 0.5)
+mixed = CArray.double(6)
+CArray.jit_each { mixed = atan2.call(x, y) * 2.0 - j0.call(x) }
+puts "atan2(x, y) * 2 - j0(x)"
+puts "  #{mixed.to_a.map { |v| v.round(6) }.inspect}"
+puts
+
+# One kernel, every function of that shape
+# ----------------------------------------
+# The kernel is compiled for the *signature*, not the symbol: the address
+# travels in a buffer beside the captured scalars rather than being linked
+# against.  So the block below is compiled once and serves all three, and
+# nothing in the generated C says which library any of them came from.
+
+def apply (f, x, out)
+  CArray.jit_each { out = f.call(x) }
+end
+
+kernels = ["double j0(double)", "double y0(double)", "double tgamma(double)"]
+            .map { |prototype|
+  f = CArray.jit_extern(prototype)
+  kernel = apply(f, x, out)
+  puts "  %-24s -> %s" % [prototype, out[0..2].to_a.map { |v| v.round(6) }.inspect]
+  kernel
+}
+puts "compiled kernels: #{kernels.uniq.size} for #{kernels.size} functions"
+puts
+
+puts kernels.first.c_source.lines.grep(/typedef|functions\[0\]/).map(&:strip).uniq
+puts
+
+# A function of your own
+# ----------------------
+# `jit_function`: the same C declaration, written anonymously.
+# `double (*)(double)` is the spelling C already has for the type of a
+# function pointer, which is what this hands out.  There is no name because
+# nothing links by name -- the address travels in a buffer -- so a name would
+# have been invented to be looked at once.
+
+smoothstep = CArray.jit_function("double (*)(double)") { |t|
+  clamped = t < 0.0 ? 0.0 : (t > 1.0 ? 1.0 : t)
+  clamped * clamped * (3.0 - 2.0 * clamped)
+}
+puts "declared: #{smoothstep}"
+
+# It keeps its block, so what the kernel runs and what Ruby computes can be
+# put side by side.  They agree to the last bit; that is the whole claim of
+# this compiler, and here it is checkable rather than argued.
+[-0.5, 0.25, 0.5, 2.0].each do |v|
+  puts "  smoothstep(%5s)  C %.17g   Ruby %.17g" %
+       [v, smoothstep.call(v), smoothstep.block.call(v)]
+end
+puts
+
+# And it is called from a kernel like any other, which is what gives kernels
+# something they did not have: a body you can factor and name.
+w = CArray.double(6).seq!(-0.2, 0.3)
+blended = CArray.double(6)
+low = CArray.double(6) { 10.0 }
+high = CArray.double(6) { 20.0 }
+CArray.jit_each {
+  blended = low + (high - low) * smoothstep.call(w)
+}
+puts "blend across a ramp"
+puts "  #{blended.to_a.map { |v| v.round(4) }.inspect}"
+puts
+
+# Calling itself
+# --------------
+# A declaration that gives a name puts that name in scope inside its own body,
+# which is what C does, so the function can recurse.  The spelling is `.call`,
+# the one every C function takes here, and that is not a compromise: it keeps
+# the block runnable, so the compiled recursion and the Ruby one can be put
+# side by side.
+
+fact = CArray.jit_function("double fact(double)") { |n|
+  n <= 1.0 ? 1.0 : n * fact.call(n - 1.0)
+}
+puts "5! compiled C  #{fact.call(5.0)}"
+puts "   same block in Ruby  #{fact.block.call(5.0)}"
+puts fact.c_source.lines.grep(/carray_jit_fact/).map { |line| "  #{line.strip}" }
+puts "  -- `fact` in the block is a spelling; the call goes to the qualified"
+puts "     symbol, so it cannot reach anything else named fact."
+puts
+
+# A pointer parameter is handed on the way C hands one on, so a recursion can
+# walk an array.
+total = CArray.jit_function("double total(int n, const double v[8])") { |n, v|
+  n == 0 ? 0.0 : v[n - 1] + total.call(n - 1, v)
+}
+values = CArray.double(8).seq!(1.0)
+puts "sum of #{values.to_a.map(&:to_i).inspect} by recursion  #{total.call(8, values)}"
+puts "  matches Ruby  #{total.call(8, values) == total.block.call(8, values)}"
+puts
+
+# Dividing by zero
+# ----------------
+# `6 % 0` raises in Ruby, and a kernel raises it too -- it is handed somewhere
+# to report.  A compiled function has only the signature its declaration gave
+# it, so the object carries a place of its own: one exported int the division
+# helpers write into, declared only when the body can reach it.  The C still
+# returns a number and touches no Ruby value; `call` is what looks afterwards.
+
+remainder = CArray.jit_function("int r(int a, int b)") { |a, b| a % b }
+puts "7 % 3   C #{remainder.call(7, 3)}   Ruby #{remainder.block.call(7, 3)}"
+[[remainder, 7, 0]].each do |f, a, b|
+  compiled = begin; f.call(a, b); rescue => error; "#{error.class}: #{error.message}"; end
+  in_ruby  = begin; f.block.call(a, b); rescue => error; "#{error.class}: #{error.message}"; end
+  puts "7 % 0   C #{compiled}"
+  puts "        Ruby #{in_ruby}"
+end
+puts remainder.c_source.lines.grep(/carray_jit_error/).map { |line| "  #{line.strip}" }
+
+# A float division is not that case -- an infinity is the answer in Ruby, in C
+# and here -- so a body that only divides floats declares no flag.
+float_divide = CArray.jit_function("double d(double a, double b)") { |a, b| a / b }
+puts "1.0 / 0.0  #{float_divide.call(1.0, 0.0)}, and no flag: " \
+     "#{!float_divide.c_source.include?("carray_jit_error")}"
+puts
+
+# Handing one back out
+# --------------------
+# The compiled object references no Ruby symbol at all, so the address is safe
+# to call from a library that knows nothing about Ruby -- and gsl_function is
+# `double (*)(double x, void *params)`, which is written here exactly as GSL's
+# own documentation writes it.  The body may not read the pointer: it is a
+# slot the ABI requires, not a value.
+
+integrand = CArray.jit_function("double (*)(double x, void *params)") { |x, params|
+  Math.exp(-x * x)
+}
+puts "for a gsl_function slot: #{integrand}"
+puts "  pointer: 0x#{integrand.pointer.to_i.to_s(16)}"
+puts
+
+# Coefficients from outside, without capturing them
+# ------------------------------------------------
+# A compiled function reaches nothing outside its parameters, so what it needs
+# arrives as one -- which is what C does anyway, and C's declarator says the
+# rest: `const` is the read/write distinction, and a length is a length.
+
+poly = CArray.jit_function("double (*)(double x, const double coef[3])") { |x, c|
+  c[0] + c[1] * x + c[2] * x * x
+}
+coef = CArray.double(3) { |i| [1.0, 2.0, 3.0][i] }
+puts "1 + 2x + 3x^2 at x = 2"
+puts "  compiled C  #{poly.call(2.0, coef)}"
+puts "  same block in Ruby  #{poly.block.call(2.0, coef)}"
+puts "  -- `coef[0]` means the same to a CArray as to a C pointer, so the"
+puts "     body is unchanged between them."
+puts
+
+# The whole ODE signature is sayable, with no half of it invented here.
+ode = CArray.jit_function(
+  "int (*)(double t, const double y[2], double dydt[2], void *params)"
+) { |t, y, dydt, params|
+  dydt[0] = y[1]
+  dydt[1] = -y[0]
+  0
+}
+state = CArray.double(2) { |i| [1.0, 0.0][i] }
+derivative = CArray.double(2)
+ode.call(0.0, state, derivative, nil)
+puts "harmonic oscillator: y = #{state.to_a.inspect} -> dy/dt = #{derivative.to_a.inspect}"
+puts ode.c_source.lines.last(6).join
+
+# ...and a kernel can hand over one of its own arrays
+# ---------------------------------------------------
+# `x[i]` is a cell and `coef` is the whole array.  Which is meant comes from
+# the declaration rather than from the spelling.
+
+ramp = CArray.double(6).seq!(0.0, 0.5)
+fitted = CArray.double(6)
+CArray.jit_for(6) { |i| fitted[i] = poly.call(ramp[i], coef) }
+puts "1 + 2x + 3x^2 along a ramp"
+puts "  #{fitted.to_a.map { |v| v.round(4) }.inspect}"
+puts "  matches Ruby  #{fitted.to_a == ramp.to_a.map { |v| poly.block.call(v, coef) }}"
+puts
+
+# What it costs
+# -------------
+# Against the two things a Ruby user can do today: call it through Fiddle one
+# cell at a time, or find a Math method that happens to exist.
+
+n = 200_000
+big = CArray.double(n).seq!(1.0, 1e-5)
+big_out = CArray.double(n)
+gamma = CArray.jit_extern("double tgamma(double)")
+
+def timed
+  2.times { yield }
+  Benchmark.realtime { 3.times { yield } } / 3
+end
+
+compiled = timed { CArray.jit_each { big_out = gamma.call(big) } }
+values = big.to_a
+jit_for_fiddle = timed { values.map { |v| gamma.call(v) } }
+ruby_math = timed { values.map { |v| Math.gamma(v) } }
+
+puts "tgamma over #{n} cells"
+puts "  in the kernel      %7.2f ms  %7.1f ns/element" %
+     [compiled * 1e3, compiled / n * 1e9]
+puts "  Fiddle, per cell   %7.2f ms  %7.1f ns/element  %.0fx" %
+     [jit_for_fiddle * 1e3, jit_for_fiddle / n * 1e9, jit_for_fiddle / compiled]
+puts "  Math.gamma map     %7.2f ms  %7.1f ns/element  %.0fx" %
+     [ruby_math * 1e3, ruby_math / n * 1e9, ruby_math / compiled]
+puts
+puts "-- and Ruby has no Math method for j0 at all."