carray-jit 0.1.2 → 0.1.3

data/docs/04_Compiling.md

@@ -67,7 +67,7 @@ In `~/.cache/carray-jit` (honouring `XDG_CACHE_HOME`), one directory per version
 
 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.
+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.2, < 3.1`, so 3.0.2 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"
@@ -107,7 +107,7 @@ Because the cache is shared across processes and across time, the key covers the
 
 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.
+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. So is one that belongs to another user, whatever its mode says: its owner writes to it, and a directory of theirs at the name yours would have taken is the same thing by another route. A root that is a symlink to another volume is followed as before, the question being asked of the directory it lands on.
 
 ## Inspecting a kernel
 
@@ -144,18 +144,20 @@ carray_jit_contiguous (char **pointers, int64_t *strides, int64_t *bounds, ...)
   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 w;
+    double wy;
+    w = x * ((double *)(p_legendre))[i - 1];
+    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.
+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. A name in the block that the generated C already has a use for -- a local called `error` or `p_legendre`, say -- is written as `carray_jit_name1_error` -- a number, then the name -- and every other name is the one the block used.
 
 ### 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.
+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 itself 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
@@ -220,6 +222,31 @@ carray_jit_contiguous (char **pointers, int64_t *strides, int64_t *bounds, ...)
 | `CARRAY_JIT_CC` | C compiler (default `RbConfig::CONFIG["CC"]`) |
 | `CARRAY_JIT_REASSOCIATE` | `0` makes the serial accumulator the default for the process |
 
+## A site answered from somewhere else
+
+A `CArray.jit_call` site (see [Compiling a body where it is called](03_SupportedFeatures.md#compiling-a-body-where-it-is-called)) names a function by its declaration and takes its arguments from the locals around it. Nothing in that says the function has to be compiled here, and the first thing asked at a site is whether something else already has one:
+
+```ruby
+CArray::JIT.call_provider = ->(prototype, block, names) {
+  LIBRARY.lookup(prototype, block) # or nil
+}
+```
+
+What it is handed is the prototype, the block -- whose binding says which method and which module the site is in -- and the names the declaration gave. What it answers is anything that responds to `call`, or `nil`, which means "not mine, compile it" and is the position `jit_extern` puts a function from a library in, said about a call rather than about a name. The answer is kept for that site like any other, so a provider is asked once per site.
+
+This is what `require "carray/jit/call"` is for. It defines `CArray.jit_call` and the declaration's parser and stops there; the compiler -- the analyzer, the generator, the cache -- is required at the first site no provider answers, and not before. A program whose sites were all built ahead of it therefore never loads it. `require "carray/jit"` loads everything as it always did, and a program that knows nothing about any of this sees no difference.
+
+The other half of building ahead is getting the C out, which is `c_source_as`:
+
+```ruby
+square = CArray.jit_function("double sq(double x)") { |x| x * x }
+File.write("kernels.c", square.c_source_as(:my_square))
+```
+
+`c_source` is the source as this compiler wrote it, under the symbol it picked -- `carray_jit_sq_1c42612898e4`, a digest of the body, which is right for an object in a cache and wrong for one committed to a repository, where the name would change every time the body was touched. `c_source_as` writes the same body under a name the caller picked. A name C cannot spell is refused, and so is one in this compiler's own `carray_jit_` namespace, where a cached kernel is entitled to the name; a name the C library already has is the caller's to avoid, the prefix that closed that hazard being what is replaced. A function bound with `jit_extern` has no C of its own and says so.
+
+carray-jit-aot is the gem these were built for: it reads the call sites out of a program, compiles them into one shared object, and answers as the provider at run time. They are here rather than there because a gem reaching into another's method to change what it does is the arrangement that breaks quietly.
+
 ## Testing
 
 ```

data/docs/05_DesignNotes.md

@@ -4,7 +4,7 @@ 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 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. There a kernel agrees with CArray, because both are the same C. A shift is the exception that proves it: a kernel shifts an integer in the width it computes in, `int64_t`, and narrows on store, so on an `int32` cell a count past 31 gives the Ruby loop's answer where CArray, shifting in 32 bits, gives another.
 
 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.
 
@@ -65,7 +65,7 @@ Ruby floors integer division and gives the remainder the sign of the divisor; C
 
 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.
+For the same reason `%` is **not** lowered to `fmod`, which truncates. Ruby and CArray floor it, and so does a kernel -- through a helper for an integer, and for a float through `fmod` with the sign corrected afterwards.
 
 ## Integer division by zero
 
@@ -133,4 +133,4 @@ The columns are the part that matters. `Proc#source_location` reports only a lin
 
 `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.
+Two cases fall back to the text: `CArray::JIT.compile`, which takes a kernel as a string. 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

@@ -1,6 +1,6 @@
 # Cheatsheet
 
-Eight entry points: the seven `jit_` methods this gem puts on `CArray`, and
+Nine entry points: the eight `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.
 
@@ -13,10 +13,14 @@ installed. Every example here runs as written.
 | 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` |
+| Fill an array from its own indices | `array.jit_init` |
 | An index repeats and is summed | `CArray.jit_contract` |
 | An index repeats and is *not* summed -- a point number, a batch | `CArray.jit_contract(:p)`, naming the result's axes |
 | Call a C function someone else compiled | `CArray.jit_extern` |
 | Compile a C function of your own | `CArray.jit_function` |
+| Compile a body and call it where it stands, on the locals around it | `CArray.jit_call` |
+| Draw random numbers inside a kernel | `CArray::Rng` + `r.random` |
+| Bring a scalar in from outside, or accumulate into one | `CScalar` -- `s[]` is the value |
 
 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
@@ -62,10 +66,112 @@ 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.
 
+An inner loop counts up with `(a...b).each` or `n.times`, and by a stride with
+`a.step(b, s)` -- `(n-1).step(0, -1)` for a sweep back down a row. Its index
+addresses writes as well as reads, which is a cell's own workspace:
+
+```ruby
+CArray.jit_for(rows) { |i|
+  (0...width).each { |k| work[i, k] = ... }          # fill the row
+  (width-1).step(0, -1) { |k| ... work[i, k] ... }   # and walk back down it
+}
+```
+
+`x.nan?` and `x.finite?` are the guards; `infinite?` is refused, answering
+nil or ±1 rather than a boolean. `x.clamp(low, high)` bounds a value, with the
+value and both bounds one class.
+
+An operator assignment is the assignment it stands for: `total += a[i]`,
+`work[i, k] *= 2.0`, `counts[bin[i]] += 1`.
+
+A parallel assignment settles every value before it writes anything, which is
+how a recurrence advances: `a, b = b, a + b`, `a[i], a[j] = a[j], a[i]`. One
+value per name, written out -- the readings that take a single value apart
+(`a, b = f(x)`, `a, *rest =`, `a, (b, c) =`) are each refused by name.
+
 `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.
 
+A `CArray` the block makes is a C array of the block's own -- in any block
+but a contraction's, of any number of axes, cleared at the line each pass
+unless it is `CArray.empty(:type, [n])`. Note `CArray.float` is float32 and
+`CArray.complex` is cmplx64. Up to 4 KiB it stands in the frame; past that,
+or where the shape is written over an integer the block captured
+(`CArray.double(n)`), the kernel allocates it at its entry and frees it at
+its exit -- and then every subscript is checked where the cell is reached,
+and a C function takes it only through a pointer with no length. Where the kernel carries masks
+each cell gets a mask byte beside it, so `w[k] = UNDEF` and `w[k] == UNDEF`
+are written as a captured array's are -- but `sum`, `min`, `max`, `sort` and
+a C function take no such array.
+
+```ruby
+CArray.jit_for(rows) { |i|
+  counts = CArray.int64(256)                # int64_t counts[256]; + memset
+  (0...cols).each { |j| counts[labels[i, j]] += 1 }
+  ...
+}
+```
+
+Four functions come with the compiler, over a local array of one axis. Bare
+calls, not methods on the array -- `w.sum` is refused.
+
+| Written | Is | Notes |
+|---|---|---|
+| `sum(w)` | a value | in index order from cell 0; no partial sums. Boolean refused |
+| `min(w)` | a value | a NaN is skipped wherever it stands; all NaN gives `NaN` |
+| `max(w)` | a value | the same. Complex and boolean refused |
+| `sort(w)` | a **statement** | ascending, in place, NaN last. A network up to 16 cells, an insertion sort above |
+
+```ruby
+median = CArray.jit_for(rows) { |i|
+  w = CArray.double(9)
+  (0...9).each { |k| w[k] = a[i, k] }
+  sort(w)
+  out[i] = w[4]
+}
+```
+
+## Filling from the indices
+
+```ruby
+CArray.double(3, 4).jit_init { |i, j| i * 10.0 + j }
+grid = CArray.double(n)
+grid.jit_init { |i| Math.sin(i * step) }                # fills in place
+```
+
+`jit_init` fills every cell of the receiver from the indices of that cell, one
+block parameter per axis, as a constructor block does -- and hands the receiver
+back. What is compiled is the whole fill, so the block reaches the same subset
+every other kernel does and closes over arrays the same way. A block that names
+no index is `jit_each`'s work, and is refused here saying so.
+
+## A scalar from outside
+
+```ruby
+gain  = CScalar.double() { 2.0 }
+total = CScalar.int()
+
+CArray.jit_each { out = signal * gain }         # read at every cell
+CArray.jit_for(a.size) { |i| total[] += a[i] }  # and written like any cell
+```
+
+A captured Numeric has no data type of its own, so a local seeded from one has
+none either; a `CScalar` is a value with a type, which is what makes it the way
+to hand a kernel a scalar and the way to take one back out. `s[]` is the value
+and `s[] = ...` puts one back.  A bare `s` reads the value too, there being no
+axis to walk; written to, a bare name is a local of the block's own, so an
+accumulator is `s[] = s[] + ...` and not `s = s + ...`.
+
+Every iteration writing the one cell it has is what makes it an accumulator,
+and what is left is what the same Ruby loop leaves. `CScalar.int()` is that one
+cell zero-filled, as `CArray.int(1)` is; write `CScalar.int() { 0 }` where the
+starting value is part of what the code says.
+
+See [CScalar](02_KernelShapes.md#a-cscalar-is-a-value-with-a-home) for how the
+two routes reach it -- `jit_each` stretches it at a stride of zero, `jit_for`
+reads it where it lies.
+
 ## Windows
 
 ```ruby
@@ -82,6 +188,9 @@ is what the cell gets.
 |---|---|
 | `border: :mask` | a cell whose window falls off is `UNDEF` -- not computed (default) |
 | `border: :skip` | that cell is left as it was found |
+| `border: :zero` | a read that falls off gives 0, and the cell is computed |
+| `border: :clamp` | such a read gives the nearest cell inside |
+| `border: :wrap` | such a read comes back the other side |
 | `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 |
 
@@ -126,7 +235,88 @@ CArray.jit_each { out = j0.call(x) }
 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.
+about either -- and from another `jit_function` body. That and a function
+borrowed with `jit_extern`, which the generated file declares and calls by
+name, are the two things such a body may reach outside its parameters.
+
+```ruby
+values = CArray.double(8) { |i| i }
+out    = CArray.double(8)
+n      = values.elements
+
+CArray.jit_call("void (*)(double *out, const double *values, size_t n)") {
+  n.times { |i| out[i] = values[i] * 2.0 }
+}
+```
+
+`jit_call` compiles the block and calls it there and then. The declaration's
+parameter names are the binding: `out`, `values` and `n` are the body's
+parameters and the locals around the call, so there is no argument list to keep
+in step. Compiled once per call site.
+
+A signature is written in C's own spellings: `float` and `double`, the
+exact-width integers `int8_t`..`int64_t` and `uint8_t`..`uint64_t`, and the
+platform's own words `size_t`, `ssize_t`, `ptrdiff_t`, `intptr_t` and
+`uintptr_t`. A word is whatever the platform made it, so `size_t` computes as
+a `uint64` and `size_t counts[]` takes a `uint64` array where that word is 64
+bits; `uint64_t` is the spelling that says the width itself.
+
+---
+
+## Random numbers
+
+```ruby
+rand = CArray::Rng.new(seed: 4)
+
+CArray.jit_for(n) { |i| out[i] = rand.random }  # one draw per cell, [0.0, 1.0)
+```
+
+The generator is CArray's, not this gem's, and there is no entry point of
+this gem's own: `CArray::Rng.new` makes one and a kernel draws from it.
+Five spellings, three meanings:
+
+| | |
+|---|---|
+| `r.random` | a double in `[0.0, 1.0)` |
+| `r.randomn` | a standard normal, which costs two draws |
+| `r.bits` | the raw word a draw came from, as a `uint64` |
+| `random(rng: r)`, `randomn(rng: r)` | the first two, as `a.random!(rng: r)` spells them |
+
+The keyword forms are the only keyword arguments in the subset and the only
+bare names in it that Ruby itself does not have; both are paid for reading
+like the array language. All of these read one generator, so mixing them in
+a kernel walks one sequence rather than several.
+
+A normal is two draws and keeps no spare. Box-Muller classically gives two
+normals for two uniforms; the second would have to live in the generator's
+state between calls, and a spare held across the boundary between an array
+and a kernel is a second kind of state to keep in step. Two draws apiece
+costs about a nanosecond against the ten the transform itself takes, and
+buys a rule with nothing behind it.
+
+Each generator has its own state, so two in one kernel are two sequences,
+and the state survives the call -- a second kernel carries on rather than
+starting again. `seed:` is data the kernel is handed and not part of it, so
+every seed shares one compiled kernel.
+
+A generator is one on both sides of the compiler, so a sequence can begin in
+an array and continue in a kernel:
+
+```ruby
+a.random!(rng: rand)                            # CArray fills, advancing rand
+CArray.jit_for(n) { |i| b[i] = rand.random }    # the kernel takes the next draws
+```
+
+and those are the numbers one `random!` over both would have laid down.
+CArray compiles the generator and hands the same text out for the kernel to
+paste, so the two sides are one implementation rather than two that agree.
+
+Which draw lands in which cell is the loop's order, which this compiler does
+not fix. Where that matters -- common random numbers, antithetic variates --
+fill an array with `CArray#random!` before the call and read a cell of it.
+`jit_function` is the one place a draw will not go: a compiled function
+takes everything through its parameters and has nowhere to keep a state, so
+declare `int64_t state[4]` there and pass `rand.state`.
 
 ---
 
@@ -142,6 +332,7 @@ about either.
 | `jit_contract` | a new `CArray`, or the `CompiledKernel` when the block assigns |
 | `jit_extern` | `CFunction` |
 | `jit_function` | `CFunction` |
+| `jit_call` | what the function answered, or `nil` where it returns `void` |
 
 Every `CompiledKernel` answers `#c_source` with the C that ran.
 
@@ -150,7 +341,9 @@ Every `CompiledKernel` answers `#c_source` with the C that ran.
 | | Without a C compiler |
 |---|---|
 | `fuse` | works -- CArray walks it, same answer |
-| the seven `jit_` methods | `CArray::JIT::Unsupported` |
+| the six kernel forms and `jit_function` | `CArray::JIT::Unsupported` |
+| `jit_call` | the same, unless a provider answers the site |
+| `jit_extern` | works -- it compiles nothing |
 
 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
@@ -165,8 +358,8 @@ that was not asked.
 | `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:)` |
-| a parameter at one position once the axes are named | it is free, and the axes are already stated |
+| a contraction summing an index that appears once | name the axes; with nothing named it is free |
+| a left-hand axis the argument list leaves out | the list is all of the result's axes |
 | 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 |