carray-jit 0.1.2 → 0.1.4

data/lib/carray/jit/node.rb

@@ -61,15 +61,24 @@ class CArray
     end
 
     class LocalRead < Node
-      # The C variable this read resolves to.  A Ruby local may hold an
-      # Integer at one point in the body and a Float at another; a C variable
-      # cannot, so each type gets its own.
-      attr_accessor :binding_name
+      # Which of the local's variables this read resolves to, counted from 1.
+      # A Ruby local may hold an Integer at one point in the body and a Float
+      # at another; a C variable cannot, so each type gets its own.
+      attr_accessor :binding
+      # Set only on a read the generator makes of one partial accumulator of
+      # a split fold: which one.
+      attr_accessor :lane
       attr_reader :name
       def initialize (name, location = nil)
         super(location)
         @name = name
       end
+      # What says two reads are of one variable: the name the block wrote and
+      # which of its bindings.  Not a spelling -- the block may itself write a
+      # local spelled like another one's second binding.
+      def local
+        [@name, @binding]
+      end
     end
 
     # A scalar the block closed over; passed in as a kernel argument.
@@ -110,6 +119,55 @@ class CArray
       end
     end
 
+    # `x.clamp(low, high)`: the value, or whichever bound it ran past.
+    #
+    # Ruby hands back the receiver or one of the bounds, so which type the
+    # answer has is decided by the value -- which is why all three have to
+    # be the same type here, and why the answer is then the receiver's.
+    class Clamp < Node
+      attr_reader :value, :low, :high
+      def initialize (value, low, high, location = nil)
+        super(location)
+        @value = value
+        @low = low
+        @high = high
+      end
+      def children
+        [@value, @low, @high]
+      end
+    end
+
+    # `x.nan?` and `x.finite?`: a question about a number, answered true or
+    # false whatever the number's width.  `infinite?` is not one of these --
+    # Ruby answers it with nil or 1 or -1, which is not a boolean and has no
+    # nil to be.
+    class NumericPredicate < Node
+      attr_reader :name, :operand
+      def initialize (name, operand, location = nil)
+        super(location)
+        @name = name
+        @operand = operand
+      end
+      def children
+        [@operand]
+      end
+    end
+
+    # Whether a pointer parameter was handed an address at all: `grad.nil?`,
+    # `grad == nil`, and `if grad` where a condition is read.  A callback's
+    # caller decides that per call -- NLopt hands a derivative-free method's
+    # objective no gradient to fill -- so it is a question the body asks,
+    # not one the declaration can settle.  `null` is true for the spelling
+    # that asks whether it is missing.
+    class PointerTest < Node
+      attr_reader :name, :null
+      def initialize (name, null, location = nil)
+        super(location)
+        @name = name
+        @null = null
+      end
+    end
+
     # Zero of whatever type another expression has.
     #
     # A sum has to start from a zero of the summand's type: start it from an
@@ -145,12 +203,21 @@ class CArray
     # Nothing is written through it: a kernel writes the cell its outer
     # indices are on, and the inner loop is what runs within that cell.
     class InnerLoop < Node
-      attr_reader :index, :from, :to, :statements
-      def initialize (index, from, to, statements, location = nil)
+      # `step` is the stride the loop counts by, and `to` is exclusive of it:
+      # a descending loop ends one below the last index it visits, as an
+      # extent written with `step` does.
+      attr_reader :index, :from, :to, :step, :statements
+      # The locals its block declares, as [name, binding, type], the arrays it
+      # declares, as [name, binding, storage, shape], and the ones that were
+      # live when the loop was entered, by name as [type, binding] -- all
+      # settled by the typing.
+      attr_accessor :declarations, :array_declarations, :entering
+      def initialize (index, from, to, statements, location = nil, step = 1)
         super(location)
         @index = index
         @from = from
         @to = to
+        @step = step
         @statements = statements
       end
       def children
@@ -333,6 +400,41 @@ class CArray
       end
     end
 
+    # A draw from a captured CArray::Rng.
+    #
+    # The generator is not a function this kernel closed over -- nothing of
+    # it is compiled here.  Its C arrives as text from CArray, is pasted into
+    # the preamble beside the helpers this compiler writes itself, and the
+    # draw is a call to it.  So the sequence a kernel gets is the sequence
+    # `CArray#random!` gets, because it is the same code advancing the same
+    # cells and not a second implementation agreeing with the first.
+    #
+    # The state is an ordinary captured array under a name this compiler made
+    # up, handed over as an address the way any array a C function writes
+    # through is.  That is what carries the sequence across the call: the
+    # cells the kernel advanced are the cells the generator still holds when
+    # it comes back.
+    class RandomDraw < Node
+      # The name the block reached the generator by, for a message to say.
+      attr_reader :generator
+      # The made-up name of its state array.
+      attr_reader :state
+      # What this draw answers: `:rand` a double in [0.0, 1.0), `:bits` the
+      # raw word the generator produced.  Both advance the same state by one
+      # draw -- one step of the generator read two ways, not two sequences --
+      # so a kernel mixing them is still walking the one sequence.
+      attr_reader :kind
+      def initialize (generator, state, kind, location = nil)
+        super(location)
+        @generator = generator
+        @state = state
+        @kind = kind
+      end
+      def children
+        []
+      end
+    end
+
     # `p[i]` where `p` is a pointer parameter of a compiled function.
     #
     # Not an ElementRead: an array's cell is reached through a base and a
@@ -524,18 +626,49 @@ class CArray
     end
 
     class Assignment < Node
-      attr_accessor :binding_name
-      attr_reader :name, :expression
-      def initialize (name, expression, location = nil)
+      # Which of the local's variables this writes, as LocalRead#binding.
+      attr_accessor :binding
+      # Which scope the local belongs to, counted out from the kernel's block
+      # -- or a function's -- at 0, one more for each inner loop's block.
+      attr_reader :name, :expression, :scope
+      def initialize (name, expression, location = nil, scope = 0)
         super(location)
         @name = name
         @expression = expression
+        @scope = scope
+      end
+      def local
+        [@name, @binding]
       end
       def children
         [@expression]
       end
     end
 
+    # `prev, cur = cur, prev + cur`
+    #
+    # Ruby settles every value on the right before it writes any of them, so
+    # the temporaries below are the statement rather than a way of writing
+    # it: without them the line above would write `prev` and then read the
+    # new one back while working out `cur`, which is the one thing the
+    # spelling exists to prevent.
+    #
+    # Held as the statements it became -- one assignment to a name of its own
+    # per value, in the order they were written, and then the writes.  So
+    # everything downstream reads ordinary assignments and writes: the types,
+    # the masks a local carries, the C names, the order the body is swept in.
+    # Nothing here has to know that a parallel assignment is what they were.
+    class ParallelAssignment < Node
+      attr_reader :statements
+      def initialize (statements, location = nil)
+        super(location)
+        @statements = statements
+      end
+      def children
+        @statements
+      end
+    end
+
     # A cell of an array: out[i, j] = ...
     #
     # Writes are always at the cell the loop is on.  Writing elsewhere would
@@ -558,8 +691,240 @@ class CArray
       end
     end
 
+    # `w = CArray.double(9)`, `CArray.new(:int64, [256])`, or
+    # `CArray.empty(:float64, [9])`: an array the body owns.
+    #
+    # It is declared at the head of the C block its Ruby scope stands for, as
+    # a local is, and lives on that block's stack.  The zeroed spellings are
+    # cleared where the statement stands -- in Ruby a fresh array is made
+    # there each time the line runs, and the clearing is what says the same
+    # thing in C.  `empty` says nothing there, and its cells are whatever the
+    # stack held.
+    #
+    # Not an ElementWrite or an Assignment.  Those are tied to the operand
+    # tables -- the line-up, the dispatcher, the extents, the masks, the box a
+    # view is transferred in -- and this array is in none of them: the block
+    # wrote its shape, so its strides are constants and its bounds are settled
+    # either where the block is read or at the access.  `PointerRead` stands
+    # apart for the same reason.
+    class LocalArrayDeclaration < Node
+      # Which of the name's variables this declares, as LocalRead#binding.
+      attr_accessor :binding
+      # `zeroed` is false for the `empty` spelling.
+      # `scope` is counted the way Assignment#scope is.
+      # `heap` is true where the array does not go on the stack: its shape is
+      # larger than a frame should hold, or is not known until the kernel
+      # runs.  Then it is one allocation at the kernel's entry and a free at
+      # its exit, and the name is a pointer rather than an automatic array --
+      # which changes the declaration and nothing about how a cell is
+      # reached.
+      attr_reader :name, :storage, :shape, :zeroed, :scope, :heap
+      def initialize (name, storage, shape, zeroed, location = nil, scope = 0,
+                      heap = false)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+        @zeroed = zeroed
+        @scope = scope
+        @heap = heap
+      end
+      def local
+        [@name, @binding]
+      end
+      # The shape's axes, as Nodes, for whatever has to walk them: an extent
+      # the block wrote as an expression is an expression like any other, and
+      # is typed and checked as one.
+      def children
+        @shape.filter_map { |extent|
+          extent.node if extent.is_a?(LocalArrayExtent)
+        }
+      end
+    end
+
+    # `w[k]`, `w[j + 1]`, `w[counts[i]]`.
+    #
+    # `subscripts` holds one [index, offset] pair per axis, the shape
+    # ElementRead's take: an index with a literal offset where the reach was
+    # settled as the block was read, or [nil, expression] where the position
+    # is one only the running kernel knows and is checked there.
+    class LocalArrayRead < Node
+      attr_accessor :binding
+      attr_reader :name, :storage, :shape, :subscripts
+      def initialize (name, storage, shape, subscripts, location = nil)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+        @subscripts = subscripts
+      end
+      def local
+        [@name, @binding]
+      end
+      def children
+        @subscripts.filter_map { |_index, offset| offset if offset.is_a?(Node) }
+      end
+    end
+
+    class LocalArrayWrite < Node
+      attr_accessor :binding
+      attr_reader :name, :storage, :shape, :subscripts, :expression
+      def initialize (name, storage, shape, subscripts, expression,
+                      location = nil)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+        @subscripts = subscripts
+        @expression = expression
+      end
+      def local
+        [@name, @binding]
+      end
+      def children
+        [@expression] +
+          @subscripts.filter_map { |_index, offset| offset if offset.is_a?(Node) }
+      end
+    end
+
+    # One axis of a local array whose length the block wrote as an
+    # expression over captured integers rather than as a number.
+    #
+    # Not a Node: it stands in a shape, where every other entry is an
+    # Integer, and what a shape is asked is how long an axis is -- not what
+    # type it computes in.  `text` is what the block wrote, which is what
+    # makes two of these the same extent: the expression is worked out at the
+    # kernel's entry, so two declarations that wrote the same thing are one C
+    # array, exactly as two that wrote the same number are.
+    class LocalArrayExtent
+      attr_reader :text, :node
+      def initialize (text, node)
+        @text = text
+        @node = node
+      end
+      def == (other)
+        other.is_a?(LocalArrayExtent) && other.text == @text
+      end
+      alias eql? ==
+      def hash
+        @text.hash
+      end
+      def to_s
+        @text
+      end
+    end
+
+    # `w[k] = UNDEF`: marks the cell missing and leaves its bytes alone.
+    #
+    # Beside LocalArrayWrite for the reason MaskWrite stands beside
+    # ElementWrite: UNDEF is a mark rather than a value, so there is no
+    # expression here to compute or to store.
+    class LocalArrayMaskWrite < Node
+      attr_accessor :binding
+      attr_reader :name, :storage, :shape, :subscripts
+      def initialize (name, storage, shape, subscripts, location = nil)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+        @subscripts = subscripts
+      end
+      def local
+        [@name, @binding]
+      end
+      def children
+        @subscripts.filter_map { |_index, offset| offset if offset.is_a?(Node) }
+      end
+    end
+
+    # `w[k] == UNDEF`, and `!=` with `negated`: reads the shadow byte beside
+    # the cell rather than the cell.
+    class LocalArrayMaskTest < Node
+      attr_accessor :binding
+      attr_reader :name, :storage, :shape, :subscripts, :negated
+      def initialize (name, storage, shape, subscripts, negated, location = nil)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+        @subscripts = subscripts
+        @negated = negated
+      end
+      def local
+        [@name, @binding]
+      end
+      def children
+        @subscripts.filter_map { |_index, offset| offset if offset.is_a?(Node) }
+      end
+    end
+
+    # `sum(w)`, `min(w)`, `max(w)`: a value worked out over a local array.
+    #
+    # `name` is the array's, not the function's, so that a read of the array's
+    # binding is the same question here as it is for LocalArrayRead -- the C
+    # name a helper is handed comes from the same place.  `intrinsic` is which
+    # function was written.
+    class IntrinsicCall < Node
+      attr_accessor :binding
+      attr_reader :intrinsic, :name, :storage, :shape
+      def initialize (intrinsic, name, storage, shape, location = nil)
+        super(location)
+        @intrinsic = intrinsic
+        @name = name
+        @storage = storage
+        @shape = shape
+      end
+      def local
+        [@name, @binding]
+      end
+    end
+
+    # `sort(w)`: rearranges a local array where it stands.  A statement and
+    # never a value -- what it did is in the array, which is the same bargain
+    # a call to a `void` function makes.
+    class IntrinsicStatement < Node
+      attr_accessor :binding
+      attr_reader :intrinsic, :name, :storage, :shape
+      def initialize (intrinsic, name, storage, shape, location = nil)
+        super(location)
+        @intrinsic = intrinsic
+        @name = name
+        @storage = storage
+        @shape = shape
+      end
+      def local
+        [@name, @binding]
+      end
+    end
+
+    # A local array standing where a C function wants a pointer.
+    #
+    # Not `ArrayAddress`, which is an operand's: that one is spelled by
+    # `bare_name` and is entered in `@address_arrays`, the list of arrays the
+    # caller packs and hands over through `data[]`.  This array is already
+    # here, on the stack of the block that made it, so it is spelled by the
+    # name its declaration was written under and the caller has nothing to
+    # pack.
+    class LocalArrayAddress < Node
+      attr_accessor :binding
+      attr_reader :name, :storage, :shape
+      def initialize (name, storage, shape, location = nil)
+        super(location)
+        @name = name
+        @storage = storage
+        @shape = shape
+      end
+      def local
+        [@name, @binding]
+      end
+    end
+
     class KernelBody < Node
       attr_reader :statements
+      # The locals the kernel's block, or a function's, declares, as
+      # [name, binding, type], and the arrays it declares, as
+      # [name, binding, storage, shape].
+      attr_accessor :declarations, :array_declarations
       def initialize (statements)
         super(nil)
         @statements = statements

data/lib/carray/jit/sorting_networks.rb

@@ -0,0 +1,182 @@
+class CArray
+  module JIT
+
+    # Comparator networks for the lengths a local array is sorted at without a
+    # loop: a fixed sequence of compare-exchange pairs, the same one every
+    # time, with no branch and nothing to predict.
+    #
+    # A network is a list of `[i, j]` with `i < j`, applied in order.  Each
+    # pair says "put the smaller of these two channels in i and the larger in
+    # j"; run them all and the channels come out ordered, whatever they held.
+    # That is the whole of the interface -- the generator turns each pair into
+    # one compare-exchange in C, and what decides which pair comes first is
+    # nothing but this list.
+    #
+    # ## Where these came from
+    #
+    # The sizes are the smallest known for each length, and for n <= 12 they
+    # are known to be optimal (Codish, Cruz-Filipe, Frank and Schneider-Kamp,
+    # "Twenty-Five Comparators Is Optimal When Sorting Nine Inputs (and
+    # Twenty-Nine for Ten)", 2014, for 9 and 10; the smaller ones are in
+    # Knuth, *The Art of Computer Programming*, vol. 3, section 5.3.4).  For
+    # 13 to 16 they are the best known rather than proven optimal; the
+    # 16-input network with 60 comparators is Green's, given in Knuth's
+    # section 5.3.4 and figure 51.
+    #
+    # | n | comparators | n | comparators |
+    # |---|---|---|---|
+    # | 2 | 1 | 10 | 29 |
+    # | 3 | 3 | 11 | 35 |
+    # | 4 | 5 | 12 | 39 |
+    # | 5 | 9 | 13 | 45 |
+    # | 6 | 12 | 14 | 51 |
+    # | 7 | 16 | 15 | 56 |
+    # | 8 | 19 | 16 | 60 |
+    # | 9 | 25 | | |
+    #
+    # ## Why they can be trusted
+    #
+    # A table of pairs is exactly the kind of data that is wrong in one place
+    # and silently almost-right, so none of it is taken on the word of a
+    # citation.  Every network here is checked by the **zero-one principle**:
+    # a comparator network sorts every input if and only if it sorts every
+    # sequence of zeros and ones.  For n channels that is 2**n sequences --
+    # 65536 at the largest length here -- and `test/test_sorting_networks.rb`
+    # runs all of them for all fifteen lengths, along with the comparator
+    # count and the shape of each pair.  A network that is wrong fails there
+    # rather than in somebody's median filter.
+    #
+    # ## Pruning
+    #
+    # Where one of these was derived from a longer one, it was derived by
+    # pruning: set the last input to positive infinity and every comparator
+    # touching that channel becomes a no-op on the others, so deleting them
+    # leaves a network that sorts the rest.  14 and 15 are the 16-input
+    # network pruned that way, and 9 is the 10-input one pruned.  The others
+    # are written out.
+    module SortingNetworks
+
+      # The longest length that gets a network.  Above it the generator emits
+      # an insertion sort, which is a loop: the tables would keep growing and
+      # the win over a loop shrinks as the length rises, there being more
+      # comparators than the machine has registers long before this.
+      LONGEST = 16
+
+      # Green's 16-input network, 60 comparators.  14 and 15 are pruned from
+      # it below, which is where their 51 and 56 come from.
+      GREEN_16 = [
+        [0, 1], [2, 3], [4, 5], [6, 7], [8, 9], [10, 11], [12, 13], [14, 15],
+        [0, 2], [4, 6], [8, 10], [12, 14], [1, 3], [5, 7], [9, 11], [13, 15],
+        [0, 4], [8, 12], [1, 5], [9, 13], [2, 6], [10, 14], [3, 7], [11, 15],
+        [0, 8], [1, 9], [2, 10], [3, 11], [4, 12], [5, 13], [6, 14], [7, 15],
+        [5, 10], [6, 9], [3, 12], [13, 14], [7, 11], [1, 2], [4, 8],
+        [1, 4], [7, 13], [2, 8], [11, 14],
+        [5, 6], [9, 10],
+        [2, 4], [11, 13], [3, 8], [7, 12],
+        [6, 8], [10, 12], [3, 5], [7, 9],
+        [3, 4], [5, 6], [7, 8], [9, 10], [11, 12],
+        [6, 7], [8, 9],
+      ].freeze
+
+      # The 10-input network, 29 comparators.  9 is pruned from it.
+      TEN = [
+        [0, 8], [1, 9], [2, 7], [3, 5], [4, 6],
+        [0, 2], [1, 4], [5, 8], [7, 9],
+        [0, 3], [2, 4], [5, 7], [6, 9],
+        [0, 1], [3, 6], [8, 9],
+        [1, 5], [2, 3], [4, 8], [6, 7],
+        [1, 2], [3, 5], [4, 6], [7, 8],
+        [2, 3], [4, 5], [6, 7],
+        [3, 4], [5, 6],
+      ].freeze
+
+      # Sets the channels at or above `channels` to positive infinity, which
+      # makes every comparator that touches one a no-op on the rest.
+      def self.prune (network, channels)
+        network.reject { |low, high| low >= channels || high >= channels }
+      end
+
+      NETWORKS = {
+        2  => [[0, 1]],
+
+        3  => [[0, 2], [0, 1], [1, 2]],
+
+        4  => [[0, 1], [2, 3], [0, 2], [1, 3], [1, 2]],
+
+        5  => [[0, 1], [3, 4], [2, 4], [2, 3], [1, 4],
+               [0, 3], [0, 2], [1, 3], [1, 2]],
+
+        6  => [[1, 2], [4, 5], [0, 2], [3, 5], [0, 1], [3, 4],
+               [2, 5], [0, 3], [1, 4], [2, 4], [1, 3], [2, 3]],
+
+        7  => [[1, 2], [3, 4], [5, 6], [0, 2], [3, 5], [4, 6],
+               [0, 1], [4, 5], [2, 6], [0, 4], [1, 5], [0, 3],
+               [2, 5], [1, 3], [2, 4], [2, 3]],
+
+        # Batcher's odd-even merge, which at this length is also the smallest.
+        8  => [[0, 2], [1, 3], [4, 6], [5, 7],
+               [0, 4], [1, 5], [2, 6], [3, 7],
+               [0, 1], [2, 3], [4, 5], [6, 7],
+               [2, 4], [3, 5],
+               [1, 4], [3, 6],
+               [1, 2], [3, 4], [5, 6]],
+
+        9  => prune(TEN, 9),
+
+        10 => TEN,
+
+        11 => [[0, 9], [1, 6], [2, 4], [3, 7], [5, 8],
+               [0, 1], [3, 5], [4, 10], [6, 9], [7, 8],
+               [1, 3], [2, 5], [4, 7], [8, 10],
+               [0, 4], [1, 2], [3, 7], [5, 9], [6, 8],
+               [0, 1], [2, 6], [4, 5], [7, 8], [9, 10],
+               [2, 4], [3, 6], [5, 7], [8, 9],
+               [1, 2], [3, 4], [5, 6], [7, 8],
+               [2, 3], [4, 5], [6, 7]],
+
+        12 => [[0, 8], [1, 7], [2, 6], [3, 11], [4, 10], [5, 9],
+               [0, 1], [2, 5], [3, 4], [6, 9], [7, 8], [10, 11],
+               [0, 2], [1, 6], [5, 10], [9, 11],
+               [0, 3], [1, 2], [4, 6], [5, 7], [8, 11], [9, 10],
+               [1, 4], [3, 5], [6, 8], [7, 10],
+               [1, 3], [2, 5], [6, 9], [8, 10],
+               [2, 3], [4, 5], [6, 7], [8, 9],
+               [4, 6], [5, 7],
+               [3, 4], [5, 6], [7, 8]],
+
+        13 => [[0, 12], [1, 10], [2, 9], [3, 7], [5, 11], [6, 8],
+               [1, 6], [2, 3], [4, 11], [7, 9], [8, 10],
+               [0, 4], [1, 2], [3, 6], [7, 8], [9, 10], [11, 12],
+               [4, 6], [5, 9], [8, 11], [10, 12],
+               [0, 5], [3, 8], [4, 7], [6, 11], [9, 10],
+               [0, 1], [2, 5], [6, 9], [7, 8], [10, 11],
+               [1, 3], [2, 4], [5, 6], [9, 10],
+               [1, 2], [3, 4], [5, 7], [6, 8],
+               [2, 3], [4, 5], [6, 7], [8, 9],
+               [3, 4], [5, 6]],
+
+        14 => prune(GREEN_16, 14),
+
+        15 => prune(GREEN_16, 15),
+
+        16 => GREEN_16,
+      }.each_value(&:freeze).freeze
+
+      # The comparator count per length, which the tests assert and the docs
+      # quote.  Derived rather than written down a second time.
+      SIZES = NETWORKS.transform_values(&:size).freeze
+
+      # The network for `length`, or nil where there is none -- length 1 is
+      # already sorted and needs no comparator, and anything above LONGEST
+      # gets a loop instead.
+      def self.for (length)
+        NETWORKS[length]
+      end
+
+      def self.covers? (length)
+        length == 1 || NETWORKS.key?(length)
+      end
+
+    end
+  end
+end