carray-jit 0.1.3 → 0.1.5

data/lib/carray/jit/type_assignment.rb

@@ -361,6 +361,8 @@ class CArray
         when MaskTest
           walk_subscripts(node.subscripts)
           node.type = :boolean
+        when PointerTest
+          node.type = :boolean
         when NumericPredicate
           walk(node.operand)
           node.type = :boolean
@@ -430,7 +432,9 @@ class CArray
           node.alternative.each { |statement| walk(statement) }
           @bindings = merge_bindings(from_consequent, @bindings)
         when IntegerLiteral
-          node.type = :int64
+          # Above 2**63-1 a literal is a uint64, as a captured Integer is;
+          # where it then meets an int64 it is refused (#refuse_wide_literal).
+          node.type = TypeAssignment.integer_type(node.value)
         when FloatLiteral
           node.type = :double
         when ImaginaryLiteral
@@ -565,6 +569,14 @@ class CArray
           walk(node.right)
           node.type =
             if Analyzer::COMPARISON_OPERATORS.include?(node.operator)
+              # Compared in the wider of the two, which for a uint64 against a
+              # negative literal is a uint64 the literal does not fit.
+              if [node.left.type, node.right.type].include?(:uint64)
+                refuse_negative_literal(node.left, node.right)
+                refuse_negative_literal(node.right, node.left)
+                refuse_wide_literal(node.left, node.right)
+                refuse_wide_literal(node.right, node.left)
+              end
               :boolean
             elsif [:<<, :>>].include?(node.operator)
               # A shift takes its count as a number and keeps the type of the
@@ -813,6 +825,11 @@ class CArray
             "too. Store `.real`, `.imag` or `.abs`",
             location)
         end
+        if wanted == :int64 && expression.is_a?(IntegerLiteral) &&
+           expression.value > INT64_MAX
+          raise Unsupported.new(wide_literal_message(expression.value),
+                                location)
+        end
         return if !boolean?(wanted) && numeric?(given)
         if boolean?(wanted) && expression.is_a?(IntegerLiteral) &&
            [0, 1].include?(expression.value)
@@ -873,6 +890,8 @@ class CArray
         return scalar.type if KIND_RANK[scalar_kind] > KIND_RANK[typed_kind]
         if scalar_kind == typed_kind
           refuse_wide_capture(scalar, typed)
+          refuse_negative_literal(scalar, typed)
+          refuse_wide_literal(scalar, typed)
           # The scalar becomes that type rather than being widened to meet it,
           # and says so: a literal emitted as a double would take the C
           # expression back to double however this node is typed.
@@ -881,6 +900,37 @@ class CArray
         typed.type
       end
 
+      # A negative literal meeting a uint64 would take that width and compute
+      # as 2**64 minus its magnitude.  CArray refuses the same operand on a
+      # uint64 array (`RangeError: -1 is out of range for uint64`); a captured
+      # one is refused when the kernel is called, since its value is not part
+      # of the kernel.
+      def refuse_negative_literal (scalar, typed)
+        return unless scalar.is_a?(IntegerLiteral) && scalar.value.negative? &&
+                      typed.type == :uint64
+        raise Unsupported.new(
+          "#{scalar.value} is out of range for uint64: a negative Integer " \
+          "meeting a uint64 would compute as 2**64#{scalar.value}. CArray " \
+          "refuses the same operand. Convert the uint64 side first, " \
+          "`x.to_f` or a signed capture", scalar.location)
+      end
+
+      # An integer literal above 2**63-1 computed as an int64, where it would
+      # wrap to a negative number.  In Ruby it is an Integer, which has no
+      # width; meeting a uint64 or a Float it keeps its value and is accepted.
+      def refuse_wide_literal (scalar, typed)
+        return unless scalar.is_a?(IntegerLiteral) &&
+                      scalar.value > INT64_MAX && typed.type == :int64
+        raise Unsupported.new(wide_literal_message(scalar.value),
+                              scalar.location)
+      end
+
+      def wide_literal_message (value)
+        "#{value} does not fit an int64, which is what it is computed in " \
+        "here, and would wrap to a negative number. Meet it with a uint64 " \
+        "or a Float, or store it into a uint64 array"
+      end
+
       # A captured Integer above int64 meeting an integer, which absorption
       # has no answer for: the scalar is supposed to take the other side's
       # width, and this value did not come from a width -- it came from a Ruby
@@ -932,6 +982,8 @@ class CArray
           # Nothing to check: no value is computed.
         when MaskTest
           # Nothing to check: it reads a mask byte.
+        when PointerTest
+          # Nothing to check: it compares an address with NULL.
         when Clamp
           node.children.each { |child| verify(child) }
           types = node.children.map(&:type)

data/lib/carray/jit/version.rb

@@ -1,5 +1,5 @@
 class CArray
   module JIT
-    VERSION = "0.1.3"
+    VERSION = "0.1.5"
   end
 end

data/lib/carray/jit.rb

@@ -37,9 +37,9 @@ class CArray
   # no extent, and is written with CArray.jit_each or CArray.jit_map instead.
   #
   # Arrays and scalars are the variables the block closes over, so nothing has
-  # to be named twice.  Which way each axis runs is derived from the kernel's
-  # own dependencies, not chosen: reading a cell the kernel will later write
-  # means that cell has to be reached in one particular order.
+  # to be named twice.  Which way each axis runs is the extent's: a Range runs
+  # up, a step of -1 runs down, and the kernel runs the order it is given
+  # without checking it against the cells the body reads.
   #
   # A block outside the compilable subset raises CArray::JIT::Unsupported
   # rather than falling back to a Ruby loop.  Nobody calls this method except
@@ -638,10 +638,10 @@ class CArray
                   "the indices of a term are symbols naming its axes, as in " \
                   "`[a, [:i, :k]]`; got #{subscripts.inspect}"
           end
-          unless subscripts.size == array.rank
+          unless subscripts.size == array.ndim
             raise Unsupported,
                   "a term names one index per axis: this array has rank " \
-                  "#{array.rank} and #{subscripts.size} " \
+                  "#{array.ndim} and #{subscripts.size} " \
                   "#{subscripts.size == 1 ? 'index' : 'indices'} were given"
           end
         end
@@ -680,9 +680,9 @@ class CArray
           raise Unsupported, "`into:` is an array to write into"
         end
         expected = free.empty? ? 1 : free.size
-        unless into.rank == expected
+        unless into.ndim == expected
           raise Unsupported,
-                "`into:` has rank #{into.rank}, and the result's axes are " \
+                "`into:` has rank #{into.ndim}, and the result's axes are " \
                 "#{free.empty? ? 'none, which is one cell' : free.map { |name| "`#{name}`" }.join(', ')}"
         end
       end
@@ -909,7 +909,7 @@ class CArray
         return false if masked
         return false if arrays.empty? || arrays.size > Sweep::MAX_ARITY
         return false unless arrays.each_value.all? { |array|
-          array.rank.zero? || array.dim == shape
+          array.ndim.zero? || array.dim == shape
         }
         walkable_in_place?(arrays.each_value)
       end
@@ -933,7 +933,7 @@ class CArray
       # 0.9 ns/cell with the driver here against 6.1 ns/cell swept, and no
       # scratch either way -- there was nothing the re-gather was buying.
       def walkable_in_place? (arrays)
-        tiers = arrays.map { |array| Access.classify(array)[:tier] }
+        tiers = arrays.map { |array| Access.tier(array) }
         return true if tiers.include?(Access::TIER_XFER)
         tiers.none? { |tier| tier == Access::TIER_STRIDE }
       end
@@ -1214,6 +1214,23 @@ class CArray
       # common case allocates nothing.
       EMPTY_ARRAYS = {}.freeze
 
+      # What an element-wise pass works out from its operands' shapes and
+      # types, and not from their data: which of them are walked and which
+      # are handed to a C function whole, the shape the pass covers, whether
+      # lining the walked ones up to it changes any of them, which loop runs
+      # it, the kernel, and what type a map's result is made as.
+      #
+      # @private
+      RunPlan = Data.define(:walked, :addressed, :stretched, :shape,
+                            :sweeping, :kernel, :result_type)
+
+      # How many plans one block keeps.  Not one: a caller alternating
+      # between two model states would miss on every call, and pay for the
+      # asking on top of what every call paid before.  Eight, as a kernel
+      # keeps of its own calls (CompiledKernel::PLAN_LIMIT), and for no
+      # better-measured reason.
+      RUN_PLAN_LIMIT = 8
+
       # @private
       def run_over_whole_arrays (block, map: false)
         node, source, origin = read_block(block)
@@ -1238,11 +1255,185 @@ class CArray
         # is before the broadcast.
         made = local_array_names(source, node)
         refuse_a_shadowed_array(made, outside)
-        arrays = arrays.merge(assigned_arrays(assigned - made, outside))
+        written = assigned_arrays(made.empty? ? assigned : assigned - made,
+                                  outside)
+        arrays = arrays.merge(written) unless written.empty?
         if arrays.empty?
           raise Unsupported, "the block reaches no array"
         end
 
+        # Everything from here to the kernel answers the same for two calls
+        # whose operands agree on shape and type, so it is worked out once
+        # per such agreement rather than once per call (#plan_run).  What the
+        # plan leaves to the call is what it has to: the operands themselves,
+        # the views the broadcast makes of them, a generator's state, the
+        # map's result, and the masks.
+        key = run_key(arrays, scalars, c_functions, randoms, map)
+        plan = key && found_run_plan(source, key)
+        unless plan
+          plan = plan_run(source, node, origin, arrays, scalars, c_functions,
+                          randoms, map)
+          keep_run_plan(source, key, plan) if key
+        end
+
+        walked = plan.addressed.empty? ? arrays : arrays.slice(*plan.walked)
+        # Where no operand is stretched the broadcast hands back the operands
+        # it was given, so it is not asked.  Where one is, the views it makes
+        # are views of these arrays and are made again: a view is exactly
+        # what a plan must not keep.
+        #
+        # Unstretched, `aligned` can be `arrays` itself.  That is sound only
+        # because every write into it below puts back the array already
+        # there.
+        aligned = plan.stretched ? broadcast(walked).first : walked
+        plan.addressed.each { |name| aligned[name] = arrays.fetch(name) }
+        # 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.
+        unless randoms.empty?
+          states = random_states(randoms)
+          arrays = arrays.merge(states)
+          aligned = aligned.merge(states)
+        end
+        shape = plan.shape
+        if map
+          result = CArray.send(plan.result_type, *(shape.empty? ? [1] : shape))
+          arrays = arrays.merge(MAP_RESULT => result)
+          aligned = aligned.merge(MAP_RESULT => result)
+        end
+
+        kernel = plan.kernel
+        # The shape of each of these was checked against the pass's when the
+        # plan was made, and the key holds the shapes.
+        kernel.written_arrays.each do |name|
+          next if name == MAP_RESULT
+          aligned[name] = arrays.fetch(name)
+        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)
+            array.mask = 0 unless array.has_mask?
+          end
+        end
+
+        result.mask = 0 if map && kernel.masked && !result.has_mask?
+        drive(kernel, aligned, scalars, c_functions, shape, plan.sweeping)
+        map ? result : kernel
+      end
+
+      # What two calls of one block have to agree on for one to be run as
+      # the other was.
+      #
+      # Each operand's name, type and shape, because that is what the kernel
+      # is compiled for and the broadcast lines up; whether it is a CScalar,
+      # because the broadcast stretches one where it leaves a one-cell array
+      # standing.  Whether it has a mask, because a mask is runtime state that
+      # leaves the shape and the type alone -- one appearing makes a masked
+      # kernel, and nothing else here would notice it.  And the tier it would
+      # be opened at, because that decides whether CArray's sweep or the
+      # tiers here run the pass (#walkable_in_place?).  All of it read off
+      # the operand on this call; none of it kept from the last.
+      #
+      # Then the type of each scalar, each C function's signature and each
+      # generator's kind, which is what the kernel is compiled for of those.
+      # Not a scalar's value: a clock or a coefficient changes every step,
+      # and keying on it would miss on every call of the loop this is for.
+      #
+      # Values only, never an operand: a block's plans live as long as the
+      # process, and holding an array would hold its memory as long.  Shapes
+      # from `ndim`, `elements` and `dim0`.. rather than `dim`, which builds
+      # an Array on every call.
+      #
+      # nil where a scalar is not one a kernel takes, so that the call is
+      # refused where and as it always was rather than here.
+      def run_key (arrays, scalars, c_functions, randoms, map)
+        key = [map, arrays.size]
+        arrays.each do |name, array|
+          rank = array.ndim
+          key << name << array.data_type << rank << array.is_a?(CScalar) <<
+                 array.has_mask? << Access.tier(array)
+          case rank
+          when 1 then key << array.elements
+          when 2 then key << array.dim0 << array.dim1
+          when 3 then key << array.dim0 << array.dim1 << array.dim2
+          else        key.concat(array.dim)
+          end
+        end
+        key << scalars.size
+        scalars.each do |name, value|
+          key << name << TypeAssignment.scalar_type(value)
+        end
+        key << c_functions.size
+        c_functions.each { |name, function| key << name << function.kernel_key }
+        randoms.each { |name, generator| key << name << generator.generator }
+        key
+      rescue Unsupported
+        nil
+      end
+
+      # @private
+      def run_plans
+        @run_plans ||= {}
+      end
+
+      # The block's plan for this key, if it has one.  The list a plan sits
+      # in is never changed once it is published -- a kernel's call lets go
+      # of the GVL, so another thread may be reading it -- and bringing a
+      # plan to the front replaces the list rather than editing it.
+      def found_run_plan (source, key)
+        plans = run_plans[source]
+        return nil unless plans
+        found = plans.assoc(key)
+        return nil unless found
+        unless plans.first.equal?(found)
+          run_plans[source] =
+            [found, *plans.reject { |entry| entry.equal?(found) }].freeze
+        end
+        found[1]
+      end
+
+      # @private
+      def keep_run_plan (source, key, plan)
+        entry = [frozen_throughout(key), plan].freeze
+        run_plans[source] =
+          [entry, *run_plans[source]].first(RUN_PLAN_LIMIT).freeze
+      end
+
+      # A copy that nothing outside can change under it, and that changes
+      # nothing outside by being frozen: a C function's signature is its own
+      # strings, and freezing those in place would freeze them in the
+      # function.
+      def frozen_throughout (value)
+        case value
+        when Array  then value.map { |item| frozen_throughout(item) }.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        else value
+        end
+      end
+
+      # Works out what #run_over_whole_arrays keeps between calls, the way it
+      # always worked it out on every call.  Every refusal a pass can meet is
+      # met here, before a plan exists, so a plan is only ever of a call that
+      # ran.
+      def plan_run (source, node, origin, arrays, scalars, c_functions,
+                    randoms, map)
         # 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,
@@ -1250,15 +1441,10 @@ class CArray
         # 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.
+        # already does and for the same reason.  The re-substitution in the
+        # caller 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
@@ -1274,22 +1460,13 @@ class CArray
         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)
+        stretched = aligned.any? { |name, array| !array.equal?(walked[name]) }
+        arrays = arrays.merge(random_states(randoms))
         if map
-          result = allocate_map_result(source, node, arrays, scalars, shape,
-                                       c_functions, randoms)
+          result_type = probe_map(source, node, arrays, scalars, c_functions,
+                                  randoms)
+          result = CArray.send(result_type, *(shape.empty? ? [1] : shape))
           arrays = arrays.merge(MAP_RESULT => result)
-          aligned = aligned.merge(MAP_RESULT => result)
         end
         # 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
@@ -1321,31 +1498,13 @@ class CArray
                   "expression covers #{shape.inspect}; a stretched array " \
                   "cannot be written to"
           end
-          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)
-            array.mask = 0 unless array.has_mask?
-          end
         end
 
-        result.mask = 0 if map && kernel.masked && !result.has_mask?
-        drive(kernel, aligned, scalars, c_functions, shape, sweeping)
-        map ? result : kernel
+        RunPlan.new(walked: walked.keys.freeze,
+                    addressed: addressed.keys.freeze,
+                    stretched: stretched, shape: shape.freeze,
+                    sweeping: sweeping, kernel: kernel,
+                    result_type: result_type)
       end
 
       # `a = b * 2.0` reads the whole of the right-hand side and then assigns,
@@ -1394,7 +1553,7 @@ class CArray
         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
+          next unless Access.tier(array) == 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.
@@ -1434,7 +1593,7 @@ class CArray
       def broadcast (arrays)
         values = arrays.values
         rank = values.reject { |value| value.is_a?(CScalar) }
-                     .map(&:rank).max || 1
+                     .map(&:ndim).max || 1
         values = values.map { |value|
           value.is_a?(CScalar) ? value.refer(value.data_type, [1] * rank) : value
         }
@@ -1695,6 +1854,9 @@ class CArray
         @undef_cache = {}
         @probe_cache = {}
         @local_array_name_cache = {}
+        # A plan holds the kernel it runs, so one left behind would hand the
+        # next call a kernel the registry no longer has.
+        @run_plans = {}
       end
 
       # @return [String] the directory this environment's kernels are kept in,
@@ -1837,31 +1999,13 @@ class CArray
           case value
           when CArray then arrays[name] = value
           when CFunction  then c_functions[name] = value
-          else
-            if generator_class && value.is_a?(generator_class)
-              randoms[name] = refuse_an_unpasteable(name, value)
-            else
-              scalars[name] = value
-            end
+          when CArray::Rng then randoms[name] = refuse_an_unpasteable(name, value)
+          else scalars[name] = value
           end
         end
         [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
@@ -2071,13 +2215,5 @@ end
 #  installed, and the same answer without it.
 # ---------------------------------------------------------------------------
 
-# The expression front end needs things CArray gained after 3.0.0 -- the
-# plan, the kernel bodies as text, the flags they were built with, and
-# somewhere to register.  Without them the Prism front end above is the
-# whole of this gem, exactly as before.
-if CArray.respond_to?(:expression_evaluator) &&
-   CArray.respond_to?(:__kernel_body__) &&
-   CArray.const_defined?(:BUILD_FLAGS)
-  require "carray/jit/expression"
-  CArray.expression_evaluator = CArray::JIT::Expression.new
-end
+require "carray/jit/expression"
+CArray.expression_evaluator = CArray::JIT::Expression.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carray-jit
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - himotoyoshi
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.2
+        version: 3.0.4
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.1'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.2
+        version: 3.0.4
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.1'
@@ -71,6 +71,7 @@ files:
 - docs/06_Cheatsheet.md
 - docs/07_StepByStep.ja.md
 - docs/07_StepByStep.md
+- docs/08_LanguageReference.md
 - examples/README.md
 - examples/applications/alarm.rb
 - examples/applications/collatz.rb