carray-jit 0.1.2 → 0.1.3

data/lib/carray/jit.rb

@@ -7,10 +7,14 @@ require "carray/jit/analyzer"
 require "carray/jit/block_reader"
 require "carray/jit/c_function"
 require "carray/jit/type_assignment"
+require "carray/jit/sorting_networks"
 require "carray/jit/c_generator"
 require "carray/jit/compiler"
 require "carray/jit/access"
 require "carray/jit/kernel"
+# `jit_call` and the provider that may answer for it, which need no
+# compiler to be defined -- see the file for why that matters.
+require "carray/jit/call"
 
 class CArray
 
@@ -42,12 +46,10 @@ class CArray
   # to make a per-cell computation fast, so quietly doing the slow thing would
   # answer a question that was not asked.
   #
-  # The name is CArray's own: carray/lazy.rb defines jit_for to raise
-  # NotImplementedError, saying that the block is compiled and that the
-  # compiler is this gem.  Requiring carray/jit replaces it with this one.
-  # So the method is named where the subset is documented, and a program that
-  # calls it either compiles or is told why it cannot -- an expression over
-  # whole arrays that needs no compiler is CArray.fuse's.
+  # The name is this gem's: CArray defines no jit_for of its own, so the
+  # method exists once carray/jit is required, and is documented where the
+  # subset is.  An expression over whole arrays that needs no compiler is
+  # CArray.fuse's.
   #
   # `reassociate:` says whether a reduction's accumulator may be split into
   # partial sums.  It defaults to CArray::JIT.reassociate, which is true:
@@ -106,8 +108,8 @@ class CArray
   # matter, while an element-wise block has neither.  And it is jit_map's
   # sibling in the other direction: the name says whether a value comes back.
   #
-  # Like jit_for, the name is CArray's own and raises there until this gem
-  # replaces it.  Written without a compiler, the same computation is
+  # Like jit_for, the name is this gem's, and exists once carray/jit is
+  # required.  Written without a compiler, the same computation is
   # CArray.fuse's -- the expression itself, one pass per operation, with the
   # intermediates this one does without.
   #
@@ -253,14 +255,20 @@ class CArray
   # is the convention's, with a third clause: an index that repeats is summed,
   # one that appears once is free, and a named one is free however often it
   # appears -- which is what puts the diagonal and the per-point quantity
-  # inside the notation instead of outside it.  A free index needs somewhere
-  # to go, so a parameter at a single position is refused once the axes are
-  # named: it is free, and the axes are already stated.  The list is all of
-  # the result's axes rather than some of them -- name one and you have named
-  # them all -- which is what keeps the order it states complete.  Naming is allowed
+  # inside the notation instead of outside it.  The list is all of the
+  # result's axes rather than some of them -- name one and you have named them
+  # all -- so what is left out of it is summed, at however few positions it
+  # sits: `jit_contract(:i) { |k| a[i,k] }` is the row sums, which the
+  # convention alone cannot say.  (`sum(axis:)` is the faster way to write
+  # that one, being a reduction rather than a contraction.)  Naming is allowed
   # even where the convention would have reached the same answer, which is how
   # the result's axes are put in another order.
   #
+  # Where the block assigns into an array of yours, the left-hand side has the
+  # result's axes on it, and an axis there that the list left out is the list
+  # falling short rather than an index to sum -- which is refused, and is the
+  # one place a short list is caught.
+  #
   # The sum is split into partial ones, as `jit_for`'s reduction is: a
   # contraction says which indices are summed and nothing about the order, so
   # there is no order here to override.  `CArray::JIT.reassociate = false`
@@ -337,6 +345,77 @@ class CArray
     JIT.function(prototype, &block)
   end
 
+  # Gives every cell of `self` the block's value at its indices, and returns
+  # `self`.
+  #
+  # The block takes one parameter per axis, as a constructor block does, and
+  # its value is what the cell at those indices gets:
+  #
+  #   CArray.int32(1000, 1000).jit_init { |i, j| (i + j) % 2 }
+  #
+  # That is what `CArray.int32(n, n) { |i, j| ... }` says, without the Ruby
+  # call per cell: the constructor form is `map_index!`, which leaves C for
+  # every element and comes back, and this one compiles the body and runs the
+  # whole loop as C.
+  #
+  # It is the only member of the family that is an instance method, because
+  # the array being written is the receiver.  {CArray.jit_for} runs the same
+  # loop and has to be given both the index space and the array to write into
+  # -- `CArray.jit_for(n, n) { |i, j| z[i, j] = ... }` -- where here the
+  # extents are the receiver's shape and the target is the receiver, so
+  # neither is said twice.
+  #
+  # Reach for it when the values are a formula over the indices that will not
+  # go through whole-array arithmetic.  Where it will, that needs no compiler
+  # and is faster still: a checkerboard is `(i[nil, :_] + i[:_, nil]) % 2`
+  # over an index vector, and a sequence or a random fill has `seq!` and
+  # `random!` already.  What is left for this method is the formula that
+  # cannot be said that way -- a branch per cell, a value looked up, a
+  # recurrence along an axis.
+  #
+  # A block outside the compilable subset raises CArray::JIT::Unsupported, as
+  # every other entry point here does.  Nobody writes `jit_init` except to
+  # have the compiled loop, so quietly running the slow one would answer a
+  # question that was not asked -- write the constructor block when the slow
+  # one is what is wanted.
+  #
+  # The block is read and compiled, never called, so it is not yielded to.
+  #
+  # @param reassociate [Boolean, nil] as {CArray.jit_for}; `nil` defers to
+  #   {CArray::JIT.reassociate}.
+  # @return [CArray] `self`
+  # @raise [CArray::JIT::Unsupported] when the block falls outside the
+  #   recognized subset, or names a number of indices other than `ndim`.
+  def jit_init (reassociate: nil, &block)
+    unless block
+      raise JIT::Unsupported, "jit_init needs a block"
+    end
+    if block.arity.zero?
+      raise JIT::Unsupported,
+            "jit_init's block takes the indices of the cell it computes, one " \
+            "per axis, as a constructor block does; a block that names none " \
+            "computes from other arrays and belongs to jit_each"
+    end
+    # A splat or an optional parameter makes the arity negative, and the
+    # count in the message below a number nobody wrote.  The block reader
+    # refuses both a few steps later; here there is an arity to compare, and
+    # -1 is not one.
+    if block.arity.negative?
+      raise JIT::Unsupported,
+            "jit_init's block names one index per axis, and names them as " \
+            "required parameters; this one takes a splat or an optional " \
+            "parameter, which says nothing about how many axes it is for"
+    end
+    unless block.arity == ndim
+      raise JIT::Unsupported,
+            "this array has #{ndim} #{ndim == 1 ? 'axis' : 'axes'} and the " \
+            "block names #{block.arity} " \
+            "#{block.arity == 1 ? 'index' : 'indices'}; jit_init fills every " \
+            "cell, so there is one index per axis"
+    end
+    JIT.run(dim, block, reassociate, into: self)
+  end
+
   # @!endgroup
 
   # The compiler behind `CArray.jit_*`: it reads a block, generates C for it,
@@ -379,7 +458,11 @@ class CArray
         # the block reaches for it the way it reaches for a captured value.
         # It is neither: it is an index, and it is answered here.
         names = capture_names(source, node) - (free_indices || [])
-        arrays, scalars, c_functions = split_captures(names, binding_of(block))
+        arrays, scalars, c_functions, randoms =
+          split_captures(names, binding_of(block))
+        refuse_a_generator(randoms, "a contraction", "the block is a summand " \
+          "and runs once per term, so a draw in it would be one per term " \
+          "rather than one per cell of the result")
         contract(source, arrays, free_indices, node: node, origin: origin,
                  scalars: scalars, c_functions: c_functions)
       end
@@ -423,7 +506,11 @@ class CArray
         # is not the same as naming an empty list of axes.
         free_indices = nil if free_indices.empty?
         names = capture_names(source, node) - (free_indices || [])
-        arrays, scalars, c_functions = split_captures(names, binding_of(block))
+        arrays, scalars, c_functions, randoms =
+          split_captures(names, binding_of(block))
+        refuse_a_generator(randoms, "a contraction", "the block is a summand " \
+          "and runs once per term, so a draw in it would be one per term " \
+          "rather than one per cell of the result")
         # A compiled function in the summand is not something the structure
         # carries; a captured number is, as the scale.
         return nil unless c_functions.empty?
@@ -620,7 +707,8 @@ class CArray
       # `contract_terms` reach it with a source it wrote itself.
       def contract (source, arrays, free_indices,
                     node: nil, origin: nil, scalars: {}, c_functions: {})
-        result = allocate_result(source, node, arrays, scalars, free_indices)
+        result = allocate_result(source, node, arrays, scalars, free_indices,
+                                 c_functions)
         arrays = arrays.merge(RESULT => result) if result
 
         kernel = compile(source,
@@ -670,10 +758,13 @@ class CArray
           arrays.each do |name, array|
             next if name == written
             next unless root_of(array).equal?(target)
+            same = arrays.fetch(written).equal?(array)
             raise Unsupported,
-                  "`#{written}` and `#{name}` are the same array, which this " \
-                  "both writes and reads; that is a recurrence rather than a " \
-                  "contraction, and is written with jit_for"
+                  "`#{written}` and `#{name}` are #{same ? 'the same array' : 'views of one array'}, " \
+                  "which this both writes and reads; that is a recurrence " \
+                  "rather than a contraction, and is written with jit_for. " \
+                  "Two views are refused by the storage they share rather " \
+                  "than by the cells, so two that share none are refused too"
           end
         end
       end
@@ -686,8 +777,10 @@ class CArray
       # typed before there is a kernel to ask, so the block is analyzed once
       # without being compiled.  Returns nil when the block assigns into an
       # array of its own.
-      def allocate_result (source, node, arrays, scalars, free_indices = nil)
-        probe = probe_contraction(source, node, arrays, scalars, free_indices)
+      def allocate_result (source, node, arrays, scalars, free_indices = nil,
+                           c_functions = {})
+        probe = probe_contraction(source, node, arrays, scalars, free_indices,
+                                  c_functions)
         return nil unless probe
         free, index_axes, type = probe
         shape = free.map do |index|
@@ -708,17 +801,23 @@ class CArray
       end
 
       # @private
-      def probe_contraction (source, node, arrays, scalars, free_indices = nil)
+      def probe_contraction (source, node, arrays, scalars, free_indices = nil,
+                             c_functions = {})
         key = [source, arrays.transform_values(&:data_type_name),
                scalars.transform_values { |value| TypeAssignment.scalar_type(value) },
                # The result's axes are named at the call site rather than in
                # the block, so the same source under another naming is another
                # kernel -- and another probe.
                free_indices,
+               # A compiled function the summand calls decides the type of
+               # what it hands back, which is the type the result is
+               # collected into.
+               c_functions.transform_values(&:signature),
                cell_names(arrays)]
         cached = probe_cache[key]
         return cached unless cached.nil?
-        probe_cache[key] = build_probe(source, node, arrays, scalars, free_indices)
+        probe_cache[key] = build_probe(source, node, arrays, scalars,
+                                       free_indices, c_functions)
       end
 
       # @private
@@ -727,14 +826,20 @@ class CArray
       end
 
       # @private
-      def build_probe (source, node, arrays, scalars, free_indices = nil)
+      def build_probe (source, node, arrays, scalars, free_indices = nil,
+                       c_functions = {})
         storage_types = arrays.transform_values(&:data_type_name)
+        # The functions the summand calls are given to the probe as they are
+        # to the compile below it: a body that calls one is a body the probe
+        # has to be able to read, and what the call hands back is what the
+        # result is sized and typed from.
         analyzer = Analyzer.new(source, node: node, array_names: arrays.keys,
                                 contract: :probe, free_indices: free_indices,
+                                c_functions: c_functions,
                                 cell_names: cell_names(arrays))
         return false if analyzer.body.statements.last.is_a?(ElementWrite)
 
-        TypeAssignment.new(analyzer.body, storage_types, scalars)
+        TypeAssignment.new(analyzer.body, storage_types, scalars, c_functions)
         summand = analyzer.body.statements.last
         axes = Hash.new { |hash, key| hash[key] = [] }
         analyzer.subscripts.each do |array, uses|
@@ -776,6 +881,14 @@ class CArray
       # @private
       MAP_RESULT = :__map_result
 
+      # The array `jit_init` writes into is the receiver, which the block does
+      # not close over -- it is `self` there, and `self` is not a capture.  So
+      # it joins the operands under a name this compiler made up, the way a
+      # generator's state does, and the block's value is written to it at the
+      # cell the loop is on.
+      # @private
+      INIT_TARGET = :__init_target
+
       # Whether CArray's sweep can run this pass, decided before there is a
       # kernel -- because the answer changes what is compiled.
       #
@@ -808,7 +921,7 @@ class CArray
       # but only where the tiers here would have to materialise it.  So the
       # tier each operand would be opened at is the rest of the decision:
       #
-      #   TIER_ATTACH  neither can walk it, and the sweep holds 32KB where
+      #   TIER_XFER    neither can walk it, and the sweep holds 32KB where
       #                the tiers hold the whole box: the sweep runs
       #   TIER_STRIDE  a column, a transpose, every other cell -- the tiers
       #                address it in place, and the sweep re-gathers it for
@@ -821,7 +934,7 @@ class CArray
       # scratch either way -- there was nothing the re-gather was buying.
       def walkable_in_place? (arrays)
         tiers = arrays.map { |array| Access.classify(array)[:tier] }
-        return true if tiers.include?(Access::TIER_ATTACH)
+        return true if tiers.include?(Access::TIER_XFER)
         tiers.none? { |tier| tier == Access::TIER_STRIDE }
       end
 
@@ -906,8 +1019,11 @@ class CArray
 
         windowed = windows.zip(arrays).to_h
         free, assigned = free_and_assigned_names(source, node)
-        captured, scalars, c_functions =
+        captured, scalars, c_functions, randoms =
           split_captures(free - windows, binding_of(block))
+        refuse_a_generator(randoms, "a stencil", "its border is a second loop " \
+          "over the frame, so the draws would not run in one pass over the " \
+          "cells")
         unless assigned.empty? || (assigned & captured.keys).empty?
           raise Unsupported,
                 "a stencil's value is its block's, and the cells it is over " \
@@ -967,9 +1083,13 @@ class CArray
           }
           if aliased
             raise Unsupported,
-                  "`into:` is the array `#{aliased.first}` reaches its window " \
-                  "into, and a cell written there is one a later cell reads; " \
-                  "a stencil writes into an array of its own"
+                  "`into:` and `#{aliased.first}` are views of one array, and " \
+                  "a cell written through the one could be a cell the other " \
+                  "reads through its window. Which cells two views have in " \
+                  "common is not a question asked here -- the storage is -- " \
+                  "so two slabs of one array are refused along with the " \
+                  "overlapping case. Give the stencil an array of its own, " \
+                  "or `#{aliased.first}.copy` to read from"
           end
         end
         result.mask = 0 if (kernel.masked || border == :mask) && !result.has_mask?
@@ -1067,50 +1187,118 @@ class CArray
       # The result has to be sized and typed before there is a kernel to ask,
       # so the block is analyzed once without being compiled -- the same thing
       # a returned contraction does, for the same reason.
-      def allocate_map_result (source, node, arrays, scalars, shape, c_functions)
-        type = probe_map(source, node, arrays, scalars, c_functions)
+      def allocate_map_result (source, node, arrays, scalars, shape, c_functions,
+                               randoms = {})
+        type = probe_map(source, node, arrays, scalars, c_functions, randoms)
         CArray.send(type, *(shape.empty? ? [1] : shape))
       end
 
       # @private
-      def probe_map (source, node, arrays, scalars, c_functions)
+      def probe_map (source, node, arrays, scalars, c_functions, randoms = {})
         key = [:map, source, arrays.transform_values(&:data_type_name),
                scalars.transform_values { |value| TypeAssignment.scalar_type(value) },
-               c_functions.transform_values(&:signature)]
+               c_functions.transform_values(&:signature),
+               randoms.transform_values(&:generator)]
         cached = probe_cache[key]
         return cached if cached
         analyzer = Analyzer.new(source, node: node, array_names: arrays.keys,
-                                c_functions: c_functions, rank: 1, map: :probe)
+                                c_functions: c_functions, rank: 1, map: :probe,
+                                randoms: random_state_names(randoms))
         TypeAssignment.new(analyzer.body, arrays.transform_values(&:data_type_name),
                            scalars, c_functions)
         value = analyzer.body.statements.last
         probe_cache[key] = TypeAssignment.result_storage_type(value.type)
       end
 
+      # Handed where there is nothing to take out of the line-up, so that the
+      # common case allocates nothing.
+      EMPTY_ARRAYS = {}.freeze
+
       # @private
       def run_over_whole_arrays (block, map: false)
         node, source, origin = read_block(block)
         free, assigned = free_and_assigned_names(source, node)
-        arrays, scalars, c_functions = split_captures(free, binding_of(block))
+        # One Binding for the three questions asked of it.  `Proc#binding`
+        # allocates one every time it is asked, and this method is re-entered
+        # on every call of an element-wise pass, so asking three times was
+        # three allocations a call for one answer.
+        outside = binding_of(block)
+        arrays, scalars, c_functions, randoms = split_captures(free, outside)
         # `out = a + b` writes the array named `out` where the block was
         # written.  A name the block assigns is not free in it, so it is
         # looked up here rather than by split_captures -- and a name that is
         # not an array outside stays what it looks like, a local.
-        arrays = arrays.merge(assigned_arrays(assigned, binding_of(block)))
+        #
+        # Except a name the block makes an array of its own under: there the
+        # assignment is a declaration and not a write to anybody's cell, so it
+        # is taken out before the lookup.  Left in, and with an array of that
+        # name outside, the broadcast either fails on a shape nobody wrote or
+        # -- where the shapes happen to agree -- quietly makes the local array
+        # an operand and part of the cache key.  So it is refused here, which
+        # is before the broadcast.
+        made = local_array_names(source, node)
+        refuse_a_shadowed_array(made, outside)
+        arrays = arrays.merge(assigned_arrays(assigned - made, outside))
         if arrays.empty?
           raise Unsupported, "the block reaches no array"
         end
 
-        aligned, shape = broadcast(arrays)
+        # An array the block only hands to a C function whole is not walked,
+        # so the expression's shape has nothing to say about it -- and it has
+        # a shape of its own that need not line up with anything.  Left in,
+        # one of a different length dies in the broadcast below, naming an
+        # axis rather than the call it was written for.
+        #
+        # So it joins after the broadcast, which is what a generator's state
+        # already does and for the same reason.  The re-substitution further
+        # down stays: this is a static reading, and the analyzer's answer is
+        # the final one.
+        handed_over = address_array_names(source, node, c_functions)
+        # The common case is that there are none, and it pays nothing: no
+        # hash is built and the broadcast is handed the operands it always
+        # was.  Every call comes through here -- `jit_each` is re-entered per
+        # call -- so the work that is only needed sometimes is done only
+        # then.
+        addressed = handed_over.empty? ? EMPTY_ARRAYS
+                                       : arrays.slice(*handed_over)
+        walked = addressed.empty? ? arrays
+                                  : arrays.reject { |name, _| addressed.key?(name) }
+        if walked.empty?
+          handed = addressed.keys.first
+          raise Unsupported,
+                "the block reaches no array to walk: `#{handed}` is handed " \
+                "to a C function whole rather than read by cell, so it does " \
+                "not say how many cells there are to compute. " \
+                "`CArray.jit_for` with a count says that, and so does an " \
+                "operand the block reads a cell of"
+        end
+
+        aligned, shape = broadcast(walked)
+        addressed.each { |name, array| aligned[name] = array }
+        # A generator's state joins after the broadcast, never before it.
+        # It is passed whole rather than walked, so the expression's shape
+        # has nothing to say about it -- and it has a shape of its own that
+        # would not line up anyway: four cells, against however many the
+        # expression covers.  Lining it up first is what `jit_each` did to a
+        # one-cell state before 314d6cb, and a four-cell one does not even
+        # stretch.
+        states = random_states(randoms)
+        arrays = arrays.merge(states)
+        aligned = aligned.merge(states)
         if map
           result = allocate_map_result(source, node, arrays, scalars, shape,
-                                       c_functions)
+                                       c_functions, randoms)
           arrays = arrays.merge(MAP_RESULT => result)
           aligned = aligned.merge(MAP_RESULT => result)
         end
-        masked = arrays.each_value.any? { |array| array.has_mask? } ||
+        # Both questions are about the arrays the loop walks.  An array
+        # handed over whole is not one of them: its mask is not something the
+        # C can read -- `address_buffer` refuses a masked one outright -- and
+        # it is neither one of the sweep's operands nor a shape the sweep has
+        # to agree with.
+        masked = walked.each_value.any? { |array| array.has_mask? } ||
                  mentions_undef(source, node)
-        sweeping = sweepable_pass?(arrays, shape, masked)
+        sweeping = sweepable_pass?(walked, shape, masked)
         kernel = compile(source,
                          node: node,
                          origin: origin,
@@ -1118,6 +1306,7 @@ class CArray
                          storage_types: arrays.transform_values(&:data_type_name),
                          scalar_values: scalars,
                          c_functions: c_functions,
+                         randoms: randoms,
                          masked: masked,
                          rank: sweeping ? 1 : shape.size,
                          map: map,
@@ -1135,6 +1324,18 @@ class CArray
           aligned[name] = written
         end
 
+        aligned = read_once_where_the_pass_writes(aligned, kernel.written_arrays)
+
+        # An array handed to a C function by address is passed whole rather
+        # than walked, so the expression's shape has nothing to say about it.
+        # Broadcasting it would stretch a one-cell state array into a
+        # read-only `CARepeat`, which the copy-back after the call cannot
+        # write through -- and a state array is exactly the shape a caller
+        # reaches for.
+        kernel.address_arrays.each do |name|
+          aligned[name] = arrays.fetch(name)
+        end
+
         if kernel.masked
           kernel.written_arrays.each do |name|
             array = arrays.fetch(name)
@@ -1147,6 +1348,72 @@ class CArray
         map ? result : kernel
       end
 
+      # `a = b * 2.0` reads the whole of the right-hand side and then assigns,
+      # which is what the expression means in Ruby and what CArray's own
+      # operators do.  A kernel walks cell by cell instead, and that is the
+      # same thing only while no cell it reads is a cell it has written: two
+      # overlapping views of one array -- `hi = lo * 2.0` for blocks that
+      # share six cells, a transpose written over itself -- read the output
+      # back as input, cell by cell.  A gather is copied before the loop and
+      # keeps the meaning; a strided view is addressed in place, which is
+      # what makes it fast and what leaves it exposed here.
+      #
+      # So an operand that is read, and shares a root with one that is
+      # written without being that array itself, is copied once before the
+      # loop.  `a = a + 1.0` is not that case -- the cell read is the cell
+      # written, as in Ruby -- and neither is a pass whose arrays are
+      # separate, which is nearly all of them.
+      def read_once_where_the_pass_writes (aligned, written_names)
+        written = written_names.filter_map { |name| aligned[name] }
+        return aligned if written.empty?
+        roots = written.map { |array| root_of(array) }
+        aligned.to_h do |name, array|
+          next [name, array] if written_names.include?(name)
+          next [name, array] if written.any? { |other| other.equal?(array) }
+          shared = roots.any? { |root| root.equal?(root_of(array)) }
+          [name, shared ? array.copy : array]
+        end
+      end
+
+      # An operand a kernel cannot walk -- a gather, a lazy array -- is copied
+      # into a buffer before the loop and copied back after it.  For an
+      # expression over whole arrays that is what the expression means: the
+      # right-hand side is read, then assigned.  An indexed kernel means the
+      # loop instead, and a loop reads a cell when it reaches it: where the
+      # array copied is one the loop also writes, the copy is a photograph of
+      # cells that go on changing.  `y[i] = gy[i] + 1.0`, with `gy` a gather
+      # of `y`, gave the reversal of the array it started with where the Ruby
+      # loop sees its own writes; and a gather written beside a direct write
+      # put the whole buffer back at the end, dropping the direct one.
+      #
+      # Neither is a thing to fix by copying harder, so it is refused, with
+      # the loop that does mean something named: index the array itself and
+      # let the subscript do the gathering.
+      def refuse_a_transferred_alias (kernel, arrays)
+        written = kernel.written_arrays.filter_map { |name| arrays[name] }
+        return if written.empty?
+        roots = written.map { |array| root_of(array) }
+        arrays.each do |name, array|
+          next unless Access.classify(array)[:tier] == Access::TIER_XFER
+          root = root_of(array)
+          # Another operand on the same storage, and one of the two written:
+          # a copy taken before the loop cannot answer for either of them.
+          # The array alone on its root is not that case -- what it scatters
+          # back at the end, nothing in the loop was reading.
+          others = arrays.each_value.reject { |other| other.equal?(array) }
+                         .select { |other| root.equal?(root_of(other)) }
+          next if others.empty?
+          next unless written.any? { |one| one.equal?(array) } ||
+                      others.any? { |other| written.any? { |one| one.equal?(other) } }
+          raise Unsupported,
+                "`#{name}` cannot be walked as it stands, so the kernel would " \
+                "work on a copy of it taken before the loop -- and the loop " \
+                "writes the array it is a view of, which the copy would not " \
+                "see. Index that array directly and let the subscript gather: " \
+                "`a[order[i]]` rather than a view of `a`"
+        end
+      end
+
       # CArray lines the shapes up; a stretched axis comes back as a stride of
       # zero, which the kernel addresses like any other stride.
       # CArray leaves a CScalar as it is, because its own kernels know to read
@@ -1189,10 +1456,20 @@ class CArray
       end
 
       # @private
-      def run (extents, block, reassociate = nil)
+      # `into` turns the block's value into a write: with it, the last
+      # statement is what the cell of `into` gets, as jit_map's is what the
+      # cell of its own result gets.  Without it the block writes the arrays
+      # it names, which is jit_for.
+      def run (extents, block, reassociate = nil, into: nil)
         node, source, origin = read_block(block)
         names = capture_names(source, node)
-        arrays, scalars, c_functions = split_captures(names, binding_of(block))
+        arrays, scalars, c_functions, randoms =
+          split_captures(names, binding_of(block))
+        # A generator's state is an operand like any other array, under a
+        # name this compiler made up.  `jit_for` lines nothing up, so it can
+        # simply join the rest.
+        arrays = arrays.merge(random_states(randoms))
+        arrays = arrays.merge(INIT_TARGET => into) if into
 
         # A plain CArray carries no mask; one exists only once a cell has
         # actually been marked.  So masks are touched at all only when some
@@ -1217,9 +1494,12 @@ class CArray
                          storage_types: arrays.transform_values(&:data_type_name),
                          scalar_values: scalars,
                          c_functions: c_functions,
+                         randoms: randoms,
                          masked: arrays.each_value.any? { |array| array.has_mask? },
                          steps: steps,
                          cell_names: cell_names(arrays),
+                         map: into ? true : false,
+                         result: into ? INIT_TARGET : nil,
                          reassociate: reassociate.nil? ? JIT.reassociate : reassociate)
         # The kernel decides, not the caller: mentioning UNDEF makes it a
         # masked kernel even when no array carries a mask yet.
@@ -1236,8 +1516,9 @@ class CArray
                 "#{pairs.size} #{pairs.size == 1 ? 'extent was' : 'extents were'} " \
                 "given"
         end
+        refuse_a_transferred_alias(kernel, arrays)
         kernel.call(arrays, scalars, pairs.map(&:first), c_functions)
-        kernel
+        into || kernel
       end
 
       # Compiles for one set of array data types and one set of scalar types,
@@ -1248,7 +1529,7 @@ class CArray
                    scalar_values:, c_functions: {}, masked: false, rank: nil,
                    steps: nil, contract: false, result: nil, map: false,
                    reassociate: false, cell_names: [], windows: [], border: nil,
-                   free_indices: nil)
+                   free_indices: nil, randoms: {})
         # A kernel that mentions UNDEF is a masked one whatever its arrays
         # carry, and deciding that here means no caller has to remember it.
         masked ||= mentions_undef(source, node)
@@ -1260,6 +1541,12 @@ class CArray
                # kernel, and it is compiled once.  One written here adds its
                # symbol, which stands for its body -- see `CFunction#kernel_key`.
                c_functions.transform_values(&:kernel_key),
+               # Which generator each name is, and nothing about its state:
+               # the C pasted for a draw is decided by the kind, and the seed
+               # is data the kernel is handed at the call.  So two runs that
+               # differ only in seed are one kernel, and the same kernel
+               # serves a generator reset between calls.
+               randoms.transform_values(&:generator),
                masked, rank, steps, contract, result, map,
                # A contraction whose free indices were named is not the kernel
                # the same source is without them, nor with them in another
@@ -1285,7 +1572,8 @@ class CArray
         registry[key] = build(source, node, array_names, storage_types,
                               scalar_values, c_functions, masked, rank, steps,
                               contract, result, origin, map, reassociate,
-                              cell_names, windows, border, free_indices)
+                              cell_names, windows, border, free_indices,
+                              randoms)
       end
 
       # A kernel that mentions UNDEF is a masked kernel whatever its arrays
@@ -1318,22 +1606,76 @@ class CArray
           Analyzer.free_and_assigned_names(source, node: node)
       end
 
+      # Which names the block makes arrays of its own under.  A property of
+      # the source, so it is cached with the rest of them -- and for the
+      # reason the captured names are: an element-wise pass re-enters on
+      # every call, so a walk of the tree here is a walk per call.  It was
+      # the last of this family still being walked, at 3.3 us of a call.
+      def local_array_names (source, node = nil)
+        cached = local_array_name_cache[source]
+        return cached if cached
+        local_array_name_cache[source] =
+          Analyzer.local_array_names(source, node: node)
+      end
+
       # @private
       def registry
         @registry ||= {}
       end
 
+      # @private
+      def local_array_name_cache
+        @local_array_name_cache ||= {}
+      end
+
       # @private
       def capture_name_cache
         @capture_name_cache ||= {}
       end
 
+      # Which names the block only hands to a C function whole.  Cached for
+      # the reason the captured names are: `jit_each` is re-entered on every
+      # call, so anything read off the source here is read on every call, and
+      # walking the tree again cost the element-wise pass 1.7x before this
+      # was memoized.
+      #
+      # The answer depends on the declarations as well as the source -- a
+      # parameter that takes a pointer is what makes an argument an address
+      # pass -- so the signatures are part of the key, as they are for the
+      # map probe.  Nothing below the signature can change the answer: the
+      # scan asks `indexable?` and nothing else.
+      def address_array_names (source, node, c_functions)
+        key = [source, c_functions.transform_values(&:signature)]
+        cached = address_name_cache[key]
+        return cached if cached
+        address_name_cache[key] =
+          Analyzer.address_array_names(source, node: node,
+                                       c_functions: c_functions)
+      end
+
+      # @private
+      def address_name_cache
+        @address_name_cache ||= {}
+      end
+
       # Keyed by instruction sequence, which CRuby hands back as the same
       # object for every Proc made from one block literal.  That makes it a
       # free identity for the block, and keeps the file from being read and
       # parsed again on each call.
+      #
+      # The key is held weakly.  A block literal in a file keeps its sequence
+      # for the life of the process, but every `eval` makes a new one -- in a
+      # console, or in code that builds its kernels as text -- and a Hash kept
+      # each of them alive along with a parse of the whole script it came
+      # from, for as long as the process ran.  Before Ruby 3.3 there is no
+      # WeakKeyMap and the cache is a Hash as it was.
       def block_cache
-        @block_cache ||= {}
+        @block_cache ||= new_block_cache
+      end
+
+      # @private
+      def new_block_cache
+        defined?(ObjectSpace::WeakKeyMap) ? ObjectSpace::WeakKeyMap.new : {}
       end
 
       # @!group Kernel cache
@@ -1345,8 +1687,14 @@ class CArray
       def clear_registry
         @registry = {}
         @capture_name_cache = {}
-        @block_cache = {}
+        @address_name_cache = {}
+        @block_cache = new_block_cache
+        @function_registry = {}
+        # `jit_call`'s, keyed by the site rather than the body.
+        @call_sites = {}.compare_by_identity
         @undef_cache = {}
+        @probe_cache = {}
+        @local_array_name_cache = {}
       end
 
       # @return [String] the directory this environment's kernels are kept in,
@@ -1413,16 +1761,20 @@ class CArray
       def build (source, node, array_names, storage_types, scalar_values, c_functions,
                  masked, rank = nil, steps = nil, contract = false, result = nil,
                  origin = nil, map = false, reassociate = false,
-                 cell_names = [], windows = [], border = nil, free_indices = nil)
+                 cell_names = [], windows = [], border = nil, free_indices = nil,
+                 randoms = {})
         analyzer = Analyzer.new(source, node: node, array_names: array_names,
                                 c_functions: c_functions,
                                 rank: rank, steps: steps, contract: contract,
                                 result: result, map: map, free_indices: free_indices,
-                                cell_names: cell_names, windows: windows)
+                                cell_names: cell_names, windows: windows,
+                                randoms: random_state_names(randoms),
+                                masked: masked)
         assignment = TypeAssignment.new(analyzer.body, storage_types,
                                         scalar_values, c_functions)
         generator = CGenerator.new(analyzer, storage_types, assignment.scalar_types,
                                    c_functions: c_functions,
+                                   randoms: randoms,
                                    masked: masked, reassociate: reassociate,
                                    steps: steps, border: border,
                                    origin: origin, block_source: source)
@@ -1448,6 +1800,25 @@ class CArray
       # Of the names the block assigns, the ones that are arrays where it was
       # written.  Anything else -- a name that holds a number, or no name at
       # all -- is a local of the block's own.
+      # A name that is both an array this block makes and an array where the
+      # block was written.  In the whole-array spelling an assignment writes
+      # the outer array's cell, so the one line says two different things
+      # depending on which reading you take -- and neither of them is what the
+      # other reader will assume.  Refused rather than chosen between.
+      def refuse_a_shadowed_array (made, binding)
+        shadowed = made.find { |name|
+          binding.local_variable_defined?(name) &&
+            binding.local_variable_get(name).is_a?(CArray)
+        }
+        return unless shadowed
+        raise Unsupported,
+              "`#{shadowed}` is made in this block with `CArray.double` or " \
+              "its kin, and the block also closes over an array named " \
+              "`#{shadowed}`; in this spelling an assignment writes that " \
+              "array's cell, so the line means one thing to a reader and " \
+              "another to this compiler. Rename one of the two"
+      end
+
       def assigned_arrays (names, binding)
         names.each_with_object({}) do |name, found|
           next unless binding.local_variable_defined?(name)
@@ -1460,15 +1831,84 @@ class CArray
         arrays = {}
         scalars = {}
         c_functions = {}
+        randoms = {}
         names.each do |name|
           value = capture_value(name, binding)
           case value
           when CArray then arrays[name] = value
           when CFunction  then c_functions[name] = value
-          else             scalars[name] = value
+          else
+            if generator_class && value.is_a?(generator_class)
+              randoms[name] = refuse_an_unpasteable(name, value)
+            else
+              scalars[name] = value
+            end
           end
         end
-        [arrays, scalars, c_functions]
+        [arrays, scalars, c_functions, randoms]
+      end
+
+      # `CArray::Rng`, or nil where the CArray in use has none.
+      #
+      # Asked of the object rather than of the version, because the version
+      # cannot answer: 3.0.2 is where the class arrived and 3.0.2 is also
+      # what the release before it called itself.  Asked once and remembered,
+      # and reached only after a capture has failed to be an array or a
+      # function -- a bare `when CArray::Rng` is evaluated for every captured
+      # number, and against a CArray without the class that is a NameError
+      # loose in a kernel that never mentions a generator.
+      def generator_class
+        return @generator_class unless @generator_class.nil?
+        @generator_class = defined?(CArray::Rng) ? CArray::Rng : false
+      end
+
+      # A generator CArray can run but cannot hand the source of.
+      #
+      # Checked here rather than where a generator is made, because a
+      # generator is made by `CArray::Rng.new` and this gem is not on that
+      # path -- it learns one is in play when a block closes over it, which
+      # is here and is every route in.  What it costs to check late is
+      # nothing: a kernel that cannot paste the text cannot be compiled
+      # either way, and the question is which of the two says so.
+      #
+      # Nothing reaches this today: CArray hands out the source of every
+      # generator it has.  It is the seam between two of its hashes, and the
+      # failure without it is a `KeyError` out of the middle of code
+      # generation.
+      def refuse_an_unpasteable (name, generator)
+        kind = generator.generator
+        return generator if CArray::Rng::SOURCE.key?(kind)
+        raise Unsupported,
+              "`#{name}` is a #{kind.inspect} generator, and this CArray " \
+              "does not hand out that generator's C " \
+              "(CArray::Rng::SOURCE has " \
+              "#{CArray::Rng::SOURCE.keys.map(&:inspect).join(', ')}), so a " \
+              "kernel has nothing to paste. Fill an array with " \
+              "`CArray#random!` and read a cell of it instead"
+      end
+
+      # The name a generator's state array is an operand under.
+      #
+      # Made up here rather than taken from the caller, because the state is
+      # not something the block named: it wrote `r.call`, and the array
+      # behind that is machinery.  The name is derived from the one the block
+      # did write, so it is the same in the next process as in this one --
+      # which is what lets a compiled kernel be found in the cache rather
+      # than built again.
+      def random_state_name (name)
+        :"__random_state_#{name}"
+      end
+
+      # Which state array each generator draws from, as operands.
+      def random_states (randoms)
+        randoms.to_h { |name, generator|
+          [random_state_name(name), generator.state]
+        }
+      end
+
+      # Which made-up name each generator's state is under, for the analyzer.
+      def random_state_names (randoms)
+        randoms.to_h { |name, _| [name, random_state_name(name)] }
       end
 
       # A constant is looked up where the block was written, so it means what
@@ -1477,7 +1917,7 @@ class CArray
       # a compiled function or a table held in a constant is how a method
       # gets at one.
       def capture_value (name, binding)
-        if name.to_s.start_with?(/[A-Z]/)
+        if constant_name?(name)
           begin
             binding.eval(name.to_s)
           rescue NameError
@@ -1494,26 +1934,70 @@ class CArray
         end
       end
 
+      # A capture spelled with a capital is a constant and is looked up as one.
+      # Asked of the symbol's own name, which Ruby hands back frozen rather
+      # than building, and by the byte rather than by `/[A-Z]/`: this runs for
+      # every captured name on every call, and the String and the match it
+      # used to make were 2.7 us of an element-wise pass.  ASCII either way --
+      # that is what the pattern matched too.
+      def constant_name? (name)
+        first = name.name.getbyte(0)
+        !first.nil? && first >= 0x41 && first <= 0x5A
+      end
+
       # `rand` is Kernel's, so "not defined" would be a lie, and the reason it
       # is not here is worth saying where it is reached for.
       DRAW_NAMES = [:rand, :srand].freeze
 
       def refuse_a_draw (name)
+        # `random` with no `rng:` is not a name that was left undefined, it is
+        # a draw with its generator missing.  It reaches here rather than
+        # `random_call` because a bare name with no arguments is parsed as a
+        # name read, and only the parentheses tell the two apart.
+        if [:random, :randomn].include?(name.to_sym)
+          raise Unsupported,
+                "`#{name}` in a kernel draws from a generator and has to say " \
+                "which: `#{name}(rng: r)`, where `r` is a `CArray::Rng` -- " \
+                "`CArray::Rng.new(seed: 4)` makes one"
+        end
         return unless DRAW_NAMES.include?(name.to_sym)
         raise Unsupported, draw_message("`#{name}`")
       end
 
-      # A generator has one state and hands out its numbers in the order it
-      # was asked in, and a kernel does not fix that order: a stencil's border
-      # is a second loop over the frame, a reduction may split its
-      # accumulator, and the loop runs with the GVL released, which is not
-      # where Ruby's Random -- the one `CArray#random!` draws through -- may
-      # be reached at all. An array filled before the call has none of those
-      # questions in it.
+      # A generator reaches `jit_for`, `jit_each` and `jit_map`, and stops
+      # there.  The two that are left are not refused because a draw is
+      # meaningless in them but because it would not mean what it looks like,
+      # so the reason is given rather than the fact.
+      def refuse_a_generator (randoms, what, because)
+        return if randoms.empty?
+        name = randoms.keys.first
+        raise Unsupported,
+              "`#{name}` is a generator, and #{what} does not draw from one: " \
+              "#{because}. Fill an array with `CArray#random!` and read a " \
+              "cell of it, or draw in a `jit_for` / `jit_each` / `jit_map` " \
+              "block, where `random(rng: #{name})` works"
+      end
+
+      # `rand` is Ruby's, and Ruby's generator is reached through the VM: the
+      # loop runs with the GVL released, which is not where it may be reached
+      # at all.  That is why this one is refused, and it is the only reason --
+      # a kernel *can* draw, from a generator whose C it can paste, which is
+      # what `CArray::Rng` is.
+      #
+      # Both ways out are named because they are different answers.  A
+      # generator draws in the order it is asked, and a kernel does not fix
+      # that order: a stencil's border is a second loop over the frame, and a
+      # reduction may split its accumulator.  Where which draw lands in which
+      # cell has to be settled -- common random numbers, antithetic variates
+      # -- an array filled before the call is the answer, and a draw in the
+      # loop is not.  Where it does not, drawing in the kernel saves the
+      # array.
       def draw_message (what)
-        "#{what} draws from a generator, and a kernel does not fix the order " \
-        "it would draw in; fill an array with `CArray#random!` and read a " \
-        "cell of it, as the kernel reads any other array"
+        "#{what} draws from a generator this compiler cannot reach: it is " \
+        "Ruby's, and the loop runs without the GVL. Draw from " \
+        "`CArray::Rng`, which a kernel can; or, where which draw lands " \
+        "in which cell matters, fill an array with `CArray#random!` and read " \
+        "a cell of it as the kernel reads any other array"
       end
 
       # An extent is a Range, an Integer standing for `0...n`, or an
@@ -1532,6 +2016,18 @@ class CArray
           low = extent.begin || 0
           high = extent.end
           raise Unsupported, "an endless range has no extent" unless high
+          # `(n-2)..0` reads like a downward sweep and is not one: Ruby gives
+          # that Range no elements, so the loop it looks like would run no
+          # passes and say nothing.  A kernel handed one ran no passes too.
+          # An empty range whose ends agree -- `0...0`, a slice that came out
+          # empty -- is a count of zero and is taken as one.
+          if low > high
+            raise Unsupported,
+                  "`#{extent.inspect}` counts down and Ruby gives it no " \
+                  "elements, so this would run no passes at all. A downward " \
+                  "sweep is `#{low}.step(#{high}, -1)`, which is how Ruby " \
+                  "iterates backwards"
+          end
           [[low, extent.exclude_end? ? high : high + 1, 1], nil]
         when Integer
           [[0, extent, 1], nil]