carray-jit 0.1.2 → 0.1.3

data/lib/carray/jit/c_function.rb

@@ -26,6 +26,18 @@ class CArray
         pointer && !element.nil?
       end
 
+      # A C99 complex passed or returned by value.  Fiddle cannot carry one,
+      # so a call from Ruby goes through a shim; a call from a kernel is C
+      # calling C and needs nothing.
+      def complex?
+        !pointer && CDeclaration::COMPLEX_CODES.value?(fiddle)
+      end
+
+      # `CMPLX` for a double complex, `CMPLXF` for a float one.
+      def complex_build
+        fiddle == :float_complex ? "CMPLXF" : "CMPLX"
+      end
+
       # C's own declarator puts an array's length where a reader can see it,
       # so `const double coef[3]` and `const double *coef` are different
       # declarations of the same ABI.  The length is kept rather than folded
@@ -63,6 +75,20 @@ class CArray
     # flag, no library path at compile time, and a compiled kernel that does
     # not depend on which library the function came from -- so `f.call(a)`
     # compiles once and serves every function of that signature.
+    # The namespace every symbol this compiler writes sits in, and that is
+    # not tidiness.  A name the C already knows is the dangerous case, and
+    # the dangerous case is the one that does *not* fail: `double
+    # sin(double)` matches math.h's declaration, so the generated file
+    # defines libm's `sin` and the shared object exports it -- where symbols
+    # are interposable, that replaces sine for whatever loads it later.  A
+    # mismatched signature is a compile error and would have been noticed;
+    # this one would not.
+    #
+    # Here rather than beside `function_symbol`, which writes the names,
+    # because `CFunction#c_source_as` has to refuse one as well: a caller
+    # naming its own symbol may not name one in here.
+    PREFIX = "carray_jit_"
+
     class CFunction
 
       # @!attribute [r] name
@@ -72,17 +98,31 @@ class CArray
       # @!attribute [r] c_source
       #   @return [String, nil] the C compiled for a body written here, or
       #     `nil` for one found elsewhere.
-      attr_reader :name, :prototype, :return_type, :parameters, :pointer,
+      attr_reader :name, :symbol, :prototype, :return_type, :parameters, :pointer,
                   :block, :c_source, :origin, :definition, :helpers,
+                  # The compiled functions this body calls.  Whoever pastes
+                  # the definition has to paste these beside it: it reaches
+                  # them by symbol, and the symbol is only there if the
+                  # definition is.
+                  :dependencies,
                   # What `raise` in the body said, by the code it reports.
                   # The kernel that pastes it answers for these too.
                   :raise_messages
 
       def initialize (name, prototype, return_type, parameters, pointer,
+                      symbol: nil,
                       block: nil, c_source: nil, origin: nil, error: nil,
                       definition: nil, helpers: nil, takes_error: false,
-                      raise_messages: {})
+                      raise_messages: {}, dependencies: [], shim: nil)
+        # The name the declaration gave, which is what a reader wrote and
+        # what an error should say.  It is nil where the declaration gave
+        # none -- `double (*)(double)` names no function.
         @name = name && name.to_sym
+        # The name in the object, which is what a call reaches and what two
+        # functions have to differ by.  For one bound from a library they
+        # are the same; for one compiled here the symbol carries a digest of
+        # the body, so that two bodies declared alike stay apart.
+        @symbol = (symbol || name)&.to_sym
         @prototype = prototype
         @return_type = return_type
         @parameters = parameters
@@ -95,6 +135,7 @@ class CArray
         # what it wants from a preamble -- what a kernel needs to paste it.
         @definition = definition
         @helpers = helpers
+        @dependencies = dependencies
         # True when that definition ends in an `int32_t *`: the body can report
         # a failure, and pasted it reports into the caller's slot rather than
         # into the flag in its own object.
@@ -104,6 +145,10 @@ class CArray
         # Where the compiled body says a division had no divisor, or a
         # subscript ran off its array.  Nil when the body can do neither.
         @error = error
+        # The address of the entry point a call from Ruby takes where the
+        # signature carries a complex by value; nil where it does not, which
+        # is every other signature and every borrowed function.
+        @shim = shim
         @function = nil
       end
 
@@ -130,6 +175,16 @@ class CArray
         pasted? && @takes_error
       end
 
+      # The declaration under the name the block reached it by.  What a
+      # message about a call should say: the caller wrote `f`, and the symbol
+      # a body compiled here carries -- `carray_jit_two_<digest>` -- along
+      # with the file it was written in are answers to a question nobody
+      # asked there.  Those stay in `to_s`, which names the object rather
+      # than the call.
+      def declaration_as (name)
+        "#{@return_type.text} #{name}(#{@parameters.map(&:text).join(', ')})"
+      end
+
       # The signature, without the address.
       def signature
         [@return_type.text, @parameters.map(&:text)]
@@ -147,7 +202,54 @@ class CArray
       # the same way.  Splitting the cache costs a compile per body; sharing
       # it would hand back the wrong answer, and would do it quietly.
       def kernel_key
-        compiled? ? [signature, @name] : signature
+        compiled? ? [signature, @symbol] : signature
+      end
+
+      # What to call this in a message: the name its declaration gave, and
+      # the symbol where it gave none.
+      def label
+        @name || @symbol
+      end
+
+      # The C this was compiled from, under a symbol of the caller's
+      # choosing.
+      #
+      # For a caller writing the C into a file of its own rather than letting
+      # this compile it: the symbol here carries a digest of the body, which
+      # is right for an object in a cache and wrong for one in a repository,
+      # where the same build has to give the same name every time.
+      #
+      # It is a rename rather than a second run of the generator, and that is
+      # exact rather than close enough: the symbol is the only thing in the
+      # generated file that the choice of symbol decides.  Two compilations
+      # of one block under two declared names differ in nothing else once
+      # both symbols are levelled, which the suite checks.
+      #
+      # The caller owns the name it picks, and with it the one hazard the
+      # generator's own prefix exists to close: a body declared `sin`
+      # emitted as `sin` defines libm's, and the object exports it.  What is
+      # refused here is a name C cannot spell, and the generator's own
+      # namespace -- an object built under `carray_jit_...` would answer to
+      # a symbol a cached kernel is entitled to.
+      def c_source_as (symbol)
+        symbol = symbol.to_s
+        unless @c_source
+          raise Unsupported,
+                "`#{label}` was bound from a library rather than compiled " \
+                "here, so there is no C of its own to write out"
+        end
+        unless symbol =~ /\A[A-Za-z_][A-Za-z0-9_]*\z/
+          raise Unsupported,
+                "`#{symbol}` is not a C identifier, so nothing could be " \
+                "defined under it"
+        end
+        if symbol.start_with?(PREFIX)
+          raise Unsupported,
+                "`#{symbol}` is in this compiler's own namespace " \
+                "(`#{PREFIX}`), where a cached kernel is entitled to the " \
+                "name; pick one of your own"
+        end
+        @c_source.gsub(@symbol.to_s, symbol)
       end
 
       # @return [Integer] how many arguments the function takes.
@@ -198,9 +300,16 @@ class CArray
                 "wrong number of arguments (given #{arguments.size}, " \
                 "expected #{@parameters.size})"
         end
+        return call_through_shim(arguments) if @shim
+        if carries_a_complex?
+          raise Unsupported,
+                "`#{self}` carries a C99 complex by value, which Fiddle has " \
+                "no type for, so it cannot be called from Ruby; a kernel " \
+                "calls it as C calls it"
+        end
         @function ||= Fiddle::Function.new(@pointer, argument_types,
                                            @return_type.fiddle,
-                                           name: @name.to_s)
+                                           name: label.to_s)
         arrays = []
         prepared = arguments.zip(@parameters).map { |argument, type|
           next argument unless type.indexable? && argument.is_a?(CArray)
@@ -208,18 +317,29 @@ class CArray
           arrays << [argument, buffer, type]
           buffer
         }
-        clear_error
-        Access.open(arrays.map { |_, buffer, _| buffer },
-                    arrays.map { |_, _, type| !type.const },
-                    arrays.map { nil }, arrays.map { nil }) do |bases|
-          slot = -1
-          prepared = prepared.map { |value|
-            next value unless arrays.any? { |_, buffer, _| buffer.equal?(value) }
-            Fiddle::Pointer.new(bases[slot += 1][:pointer])
-          }
-          @result = @function.call(*prepared)
+        # Borrowed rather than cleared, and borrowed here rather than on the
+        # way in: a call made inside a window -- someone else is holding this
+        # function's address and watching the same flag -- must answer for
+        # itself without disarming them.  The checks above never reach the C
+        # and so never touch the flag at all.
+        outer = error_code
+        write_error(0)
+        begin
+          Access.open(arrays.map { |_, buffer, _| buffer },
+                      arrays.map { |_, _, type| !type.const },
+                      arrays.map { nil }, arrays.map { nil }) do |bases|
+            slot = -1
+            prepared = prepared.map { |value|
+              next value unless arrays.any? { |_, buffer, _| buffer.equal?(value) }
+              Fiddle::Pointer.new(bases[slot += 1][:pointer])
+            }
+            @result = @function.call(*prepared)
+          end
+          code = error_code
+        ensure
+          write_error(outer)
         end
-        report_error
+        raise_for(code)
         # A view was copied to be made contiguous; a writable one is copied
         # back, because the C wrote into the copy.
         arrays.each do |array, buffer, type|
@@ -230,6 +350,77 @@ class CArray
 
       alias [] call
 
+      # Whether a call from Ruby has to go round through the shim.
+      def carries_a_complex?
+        @return_type.complex? || @parameters.any?(&:complex?)
+      end
+
+      # Fiddle carries no complex, so the shim takes each complex argument as
+      # a pair of doubles and writes a complex result back the same way.
+      # Everything else keeps the type the declaration gave it and goes
+      # through Fiddle as before -- including a pointer parameter, which is
+      # still a CArray on this side.
+      #
+      # It is the same compiled body either way: the shim calls the function,
+      # it does not reimplement it.
+      def call_through_shim (arguments)
+        returns_complex = @return_type.complex?
+        types = @parameters.map { |type|
+          type.complex? ? Fiddle::TYPE_VOIDP : type.fiddle
+        }
+        types << Fiddle::TYPE_VOIDP if returns_complex
+        @shim_function ||=
+          Fiddle::Function.new(@shim, types,
+                               returns_complex ? Fiddle::TYPE_VOID
+                                               : @return_type.fiddle)
+        result = returns_complex ? String.new("\0" * 16) : nil
+        arrays = []
+        prepared = arguments.zip(@parameters).map { |argument, type|
+          next pack_complex(argument, type) if type.complex?
+          next argument unless type.indexable? && argument.is_a?(CArray)
+          buffer = check_array(argument, type)
+          arrays << [argument, buffer, type]
+          buffer
+        }
+        outer = error_code
+        write_error(0)
+        begin
+          Access.open(arrays.map { |_, buffer, _| buffer },
+                      arrays.map { |_, _, type| !type.const },
+                      arrays.map { nil }, arrays.map { nil }) do |bases|
+            slot = -1
+            passed = prepared.map { |value|
+              next value unless arrays.any? { |_, buffer, _| buffer.equal?(value) }
+              Fiddle::Pointer.new(bases[slot += 1][:pointer])
+            }
+            passed << result if returns_complex
+            @result = @shim_function.call(*passed)
+          end
+          code = error_code
+        ensure
+          write_error(outer)
+        end
+        raise_for(code)
+        arrays.each do |array, buffer, type|
+          array[] = buffer unless type.const || array.equal?(buffer)
+        end
+        @result = Complex(*result.unpack("dd")) if returns_complex
+        @result
+      end
+
+      # A Ruby number of any kind arrives as the two doubles the shim reads.
+      # `Complex()` is what Ruby itself converts with, so an Integer and a
+      # Float are taken where a Complex is asked for, as they are in Ruby.
+      def pack_complex (value, type)
+        number = begin
+                   Complex(value)
+                 rescue TypeError, ArgumentError
+                   raise Unsupported,
+                         "`#{type.text}` takes a number, got #{value.class}"
+                 end
+        String.new([number.real.to_f, number.imaginary.to_f].pack("dd"))
+      end
+
       # @return [String] the function's name.
       def to_s
         text = "#{@return_type.text} #{@name}" \
@@ -242,40 +433,118 @@ class CArray
         "#<CArray::JIT::CFunction #{self}>"
       end
 
-      private
+      # The window a caller opens when it hands the address out.
+      #
+      # `#call` is one call, and answers for it before it returns.  A library
+      # given `#pointer` calls whenever it likes, as often as it likes, and
+      # what wants an answer is the whole of that -- so the flag is put down
+      # once, the address is lent for as long as the block runs, and what
+      # happened is asked for once at the end.  It is the arrangement a kernel
+      # already keeps with its own slot, which is cleared before a sweep and
+      # read after it, never per cell.
+      #
+      #   f.watching do
+      #     Integration.qags(f.pointer, 0.0, 1.0)
+      #   end
+      #
+      # A failure inside the block outranks whatever the library made of it.
+      # A body that fails returns a stand-in, so the library is the first to
+      # complain -- that the endpoints do not straddle, that the iteration did
+      # not converge -- and those complaints are the failure's consequences,
+      # not what happened.  So the flag is read before that exception is let
+      # through, and only where nothing stands does the library's own story
+      # get to be the story.
+      #
+      # Windows nest, and a call made inside one leaves it armed: both borrow
+      # the flag and put it back as they found it, so an inner window answers
+      # for its own block and no other.
+      def watching
+        outer = error_code
+        write_error(0)
+        code = 0
+        begin
+          result = yield
+          code = error_code
+        rescue StandardError
+          raise_for(error_code)
+          raise
+        ensure
+          write_error(outer)
+        end
+        raise_for(code)
+        result
+      end
 
-      # What a pointer parameter will accept, and what has to be true of it.
-      # The length is checked only where the declaration carried one: C's own
-      # rule is that an unsized pointer is the caller's responsibility, and
-      # writing `coef[3]` is how the caller asks to be checked.
+      # Put the flag down, before lending the address to something that will
+      # call it more than once.  `#watching` is this and #report_error with
+      # the lending in between, and is what to reach for where the window is a
+      # block; these two are here for a window that is not -- one opened in
+      # one method and closed in another, or one whose block belongs to
+      # somebody else.
       def clear_error
-        @error[0, 4] = [0].pack("l") if @error
+        write_error(0)
       end
 
       # What the kernel raises for the same code, since it is the same thing
       # that happened: `6 % 0` is a ZeroDivisionError wherever it is written,
       # and the compiled body cannot raise it itself.  A caller reaching the
-      # address from C sees the number the helper returned and the flag
+      # address from C sees the stand-in the helper returned and the flag
       # standing, which is C's own arrangement for a function that has to
       # return something whatever happened.
+      #
+      # Quiet where nothing stands, so that a caller may ask having no idea
+      # whether anything failed -- which is the position a caller is in after
+      # handing the address to a library.  Asking does not put the flag down:
+      # it reads, and the window that put it down is what picks it up.
       def report_error
-        return unless @error
-        code = @error[0, 4].unpack1("l")
+        raise_for(error_code)
+      end
+
+      private
+
+      # 0 where the body cannot fail at all: one that neither divides nor
+      # raises is compiled without a flag to read, and has no failure to
+      # report rather than an unread one.
+      def error_code
+        @error ? @error[0, 4].unpack1("l") : 0
+      end
+
+      def write_error (code)
+        @error[0, 4] = [code].pack("l") if @error
+      end
+
+      def raise_for (code)
+        if (failure = CGenerator::FIXED_FAILURES[code])
+          raise failure[0], failure[1]
+        end
         case code
         when 0 then nil
         when 1 then raise ZeroDivisionError, "divided by 0"
+        when 2 then raise IndexError, "index out of range"
+        when 3 then raise ArgumentError,
+                            "min argument must be less than or equal to " \
+                            "max argument"
+        when 4 then raise ArgumentError,
+                            "comparison with a NaN failed, so `clamp` has " \
+                            "no answer"
+        when 5 then raise Math::DomainError,
+                            "Numerical argument is out of domain - gamma"
         else
           # `raise "..."` in the body.  The message did not come back through
           # the C -- it was registered when this was compiled -- so it is
           # looked up here, and a kernel that pasted the same body looks the
           # same message up under the same code.
           message = @raise_messages[code]
-          raise Error, "#{@name} reported #{code}, which is no failure it " \
+          raise Error, "#{label} reported #{code}, which is no failure it " \
                        "was compiled to report" unless message
           raise RuntimeError, message
         end
       end
 
+      # What a pointer parameter will accept, and what has to be true of it.
+      # The length is checked only where the declaration carried one: C's own
+      # rule is that an unsized pointer is the caller's responsibility, and
+      # writing `coef[3]` is how the caller asks to be checked.
       def check_array (array, type)
         wanted = CDeclaration::DATA_TYPES.fetch(type.element.fiddle)
         unless array.data_type_name == wanted.to_s
@@ -317,7 +586,7 @@ class CArray
       def computation_of (type, role)
         return type.computation unless type.opaque?
         raise Unsupported,
-              "`#{@name}` #{role} `#{type.text}`, which is a slot in the " \
+              "`#{label}` #{role} `#{type.text}`, which is a slot in the " \
               "signature rather than a value a kernel can compute with"
       end
 
@@ -342,17 +611,34 @@ class CArray
       # aliases and its floating types are `float` and `double`.
       KEYWORDS = %w[
         const unsigned signed void char short int long float double
+        _Complex complex
         int8_t int16_t int32_t int64_t
         uint8_t uint16_t uint32_t uint64_t
         size_t ssize_t ptrdiff_t intptr_t uintptr_t
       ].freeze
 
+      # Fiddle has no code for a C99 complex -- its parser does not know the
+      # word and the ABI it answers for has nowhere to put one -- so these
+      # stand where a Fiddle code stands elsewhere.  Symbols rather than
+      # numbers, so that one reaching Fiddle by mistake is a TypeError there
+      # and not a silently wrong width.
+      COMPLEX_CODES = { "double" => :double_complex,
+                        "float"  => :float_complex }.freeze
+
+      # `double complex` is `<complex.h>`'s spelling of `double _Complex`,
+      # and both are written; which words a declaration used says nothing
+      # about what it declared.
+      COMPLEX_WORDS = %w[_Complex complex].freeze
+
       # Fiddle answers `long double` with the code for `long`, silently, so it
       # is refused by name rather than trusted.
       REFUSED = {
         "long double" => "`long double` is not a type this reads: Fiddle " \
                          "reports it as `long`, which would be the wrong " \
                          "width without saying so",
+        "long double _Complex" =>
+          "`long double _Complex` is not a type this reads: there is no " \
+          "long double here to make one of",
       }.freeze
 
       # The CArray data type a pointer parameter takes, by the code Fiddle
@@ -360,6 +646,8 @@ class CArray
       # already holds, read the other way round -- nothing new is decided
       # here about how a C type and a CArray type correspond.
       DATA_TYPES = {
+        :double_complex        => :cmplx128,
+        :float_complex         => :cmplx64,
         Fiddle::TYPE_DOUBLE    => :float64,
         Fiddle::TYPE_FLOAT     => :float32,
         Fiddle::TYPE_CHAR      => :int8,
@@ -380,6 +668,11 @@ class CArray
       # Absent means the type may be written down but holds no value a body
       # can compute with -- `void`, and a pointer to it.
       COMPUTATION = {
+        # A `float _Complex` computes in double complex, as a `float`
+        # computes in double: the declaration says what the signature is,
+        # and the body works in what Ruby would have worked in.
+        :double_complex         => :complex,
+        :float_complex          => :complex,
         Fiddle::TYPE_DOUBLE     => :double,
         Fiddle::TYPE_FLOAT      => :double,
         Fiddle::TYPE_CHAR       => :int64,
@@ -440,9 +733,40 @@ class CArray
         text.split(",").map(&:strip)
       end
 
+      # The names a declaration gave its parameters, in order, with `nil`
+      # where it gave none.
+      #
+      # `read_type` drops them, and for every other spelling that is right:
+      # nothing reads a parameter's name for a function bound from a library,
+      # and one compiled from a block takes its parameters from the block.
+      # `jit_call` is where they stop being decorative -- there the names are
+      # what binds the call to the locals around it -- so they are read here
+      # rather than kept on a type, where a name does not belong.
+      def parameter_names (prototype)
+        text = prototype.strip.sub(/;\z/, "")
+        _, _, parameter_text = split(text, prototype)
+        parts = split_parameters(parameter_text)
+        return [] if parts.size == 1 && parts.first.strip == "void"
+        parts.map { |part| parameter_name(part) }
+      end
+
+      # The same grammar `read_type` reads, answering the name it throws
+      # away.  Written out beside it rather than folded into it: `read_type`
+      # is asked about a return type too, and a return type has no name.
+      def parameter_name (text)
+        stripped = text.strip.sub(/\[\s*\d*\s*\]\s*\z/, "")
+        words = stripped.split(/\s+|(?=\*)|(?<=\*)/).reject(&:empty?)
+        words.shift while words.first && KEYWORDS.include?(words.first)
+        words.shift while words.first == "*"
+        last = words.first
+        # A Symbol, which is what a block's parameters are and what the rest
+        # of the compiler compares names as.
+        last.to_sym if last&.match?(/\A[A-Za-z_]\w*\z/)
+      end
+
       # `[const] <keywords> [*] [name] [[]]` is the whole grammar there is.
-      # A parameter's own name is dropped: nothing reads it for a bound
-      # function, and a compiled one uses the block's parameter names.
+      # A parameter's own name is dropped here; `parameter_names` above reads
+      # it for the one spelling that needs it.
       def read_type (text, prototype)
         array = nil
         stripped = text.strip.sub(/\[\s*(\d*)\s*\]\s*\z/) {
@@ -484,12 +808,17 @@ class CArray
                    else
                      ""
                    end
-        code = fiddle_code(pointer ? "void *" : spelling, text, prototype)
+        code = if !pointer && (complex = complex_code(spelling))
+                 complex
+               else
+                 fiddle_code(pointer ? "void *" : spelling, text, prototype)
+               end
         # What it points at, for a pointer that points at numbers.  `void *`
         # has no element, which is what keeps it a slot.
         element = nil
         if pointer && spelling != "void"
-          element_code = fiddle_code(spelling, text, prototype)
+          element_code = complex_code(spelling) ||
+                         fiddle_code(spelling, text, prototype)
           if COMPUTATION[element_code]
             element = CType.new(spelling, element_code,
                                 COMPUTATION[element_code], false, nil, nil,
@@ -500,6 +829,15 @@ class CArray
                   array, element, keywords.include?("const"))
       end
 
+      # The code for a complex spelling, or nil for anything else.  `float
+      # _Complex`, `complex float`, `float complex` -- the word may sit on
+      # either side, as C allows.
+      def complex_code (spelling)
+        words = spelling.split(/\s+/)
+        return nil unless (words & COMPLEX_WORDS).any?
+        COMPLEX_CODES[(words - COMPLEX_WORDS).join(" ")]
+      end
+
       def fiddle_code (spelling, text, prototype)
         PARSER.parse_ctype(spelling)
       rescue StandardError
@@ -560,7 +898,77 @@ class CArray
       # What comes back is the same object `jit_extern` hands out, so a kernel
       # calls either without knowing which it has; `compiled?` is where the
       # difference is still visible, along with the block, which it keeps.
-      def function (prototype, &block)
+      # `CArray.jit_call`: compile the block, read the locals the declaration
+      # named, call.
+      #
+      # Kept per call site rather than per body.  A block literal is a fresh
+      # Proc every time the line runs, but its instruction sequence is the
+      # site's and does not change -- which is the key `read_block` already
+      # caches a block's source under.
+      def call_here (prototype, block)
+        site = RubyVM::InstructionSequence.of(block) if
+          defined?(RubyVM::InstructionSequence)
+        entry = site && call_sites[site]
+        unless entry
+          names = CDeclaration.parameter_names(prototype)
+          if (missing = names.index(nil))
+            raise Unsupported,
+                  "`#{prototype}` gives parameter #{missing + 1} no name, " \
+                  "and a name is what `jit_call` binds by -- it is the local " \
+                  "the call reads"
+          end
+          # A compiled function may already exist somewhere other than this
+          # compiler's cache: built ahead of the program and shipped in a
+          # shared object, which is what carray-jit-aot does with these same call
+          # sites.  A provider is asked before anything is compiled and
+          # answers nil for a site that is not its own -- the same position
+          # `jit_extern` puts a function from a library in, said about a call
+          # rather than about a name.
+          compiled = call_provider &&
+                     call_provider.call(prototype, block, names)
+          unless compiled
+            # Nothing answered, so this one is compiled -- and the compiler
+            # is loaded here rather than beside the method, so a program
+            # whose sites were all answered never loads it.  `require` is
+            # idempotent and this runs once per site.
+            require "carray/jit"
+            compiled = function(prototype, declared_parameters: names, &block)
+          end
+          entry = [compiled, names]
+          call_sites[site] = entry if site
+        end
+        compiled, names = entry
+        scope = block.binding
+        compiled.call(*names.map { |local|
+          begin
+            scope.local_variable_get(local)
+          rescue NameError
+            raise Unsupported,
+                  "`#{prototype}` declares `#{local}`, and there is no local " \
+                  "by that name where the call stands. A declaration's " \
+                  "parameter names are what `jit_call` binds to"
+          end
+        })
+      end
+
+      def call_sites
+        @call_sites ||= {}.compare_by_identity
+      end
+
+      # Asked at a `jit_call` site before anything is compiled, and answering
+      # nil means "not mine, compile it".  What it is handed is the
+      # prototype, the block -- whose binding says which method and which
+      # module the site is in -- and the names the declaration gave.  What it
+      # answers is anything that responds to `call`.
+      #
+      # There is one client and it is carray-jit-aot, which builds these same
+      # sites into a shared object ahead of the program; a machine running
+      # that gem then reaches no compiler.  Left here rather than patched in
+      # from there, because a gem reaching into another's method to change
+      # what it does is the arrangement that breaks quietly.
+      attr_accessor :call_provider
+
+      def function (prototype, declared_parameters: nil, &block)
         unless block
           raise Unsupported,
                 "a function is compiled from a block, and none was given -- " \
@@ -568,7 +976,8 @@ class CArray
                 "`CArray.jit_extern(#{prototype.inspect})`"
         end
         name, return_type, parameters = CDeclaration.parse(prototype)
-        compile_c_function(prototype, name, return_type, parameters, block)
+        compile_c_function(prototype, name, return_type, parameters, block,
+                           declared_parameters)
       end
 
       private
@@ -592,28 +1001,80 @@ class CArray
       # see one name for all of them.  So an anonymous one carries its own
       # digest, and a named one carries the name it was given.
       #
-      # Always behind a prefix, though, and that is not tidiness.  A name the
-      # C already knows is the dangerous case, and the dangerous case is the
-      # one that does *not* fail: `double sin(double)` matches math.h's
-      # declaration, so the generated file defines libm's `sin` and the
-      # shared object exports it -- where symbols are interposable, that
-      # replaces sine for whatever loads it later.  A mismatched signature is
-      # a compile error and would have been noticed; this one would not.
-      PREFIX = "carray_jit_"
+      # Always behind `PREFIX`, though, for the reason stated where it is
+      # defined.
 
       def function_symbol (name, key)
         digest = Digest::SHA256.hexdigest(key.inspect)[0, 12]
         "#{PREFIX}#{name || "function"}_#{digest}"
       end
 
-      def compile_c_function (prototype, name, return_type, parameters, block)
+      def compile_c_function (prototype, name, return_type, parameters, block,
+                              declared_parameters = nil)
         node, source, origin = read_block(block)
-        key = [source, return_type.text, parameters.map(&:text), name]
+        # A function this body calls is pasted into it, so which one it is
+        # belongs in the key beside the body's own text.  Two blocks spelled
+        # the same that reach different functions are different functions,
+        # and without this the first compiled would be handed back for the
+        # second -- quietly, since nothing about them differs to look at.
+        # `kernel_key` is what a kernel already keys a pasted body by: the
+        # signature and the symbol, which carries the digest of the body.  A
+        # symbol rather than an address, so the key means the same thing in
+        # the next process as in this one.
+        called = called_functions(source, node, block, name)
+        key = [source, return_type.text, parameters.map(&:text), name,
+               declared_parameters, called.values.map(&:kernel_key)]
         found = function_registry[key]
         return found if found
         function_registry[key] =
           build_c_function(prototype, name, return_type, parameters,
-                      source, node, origin, block, function_symbol(name, key))
+                      source, node, origin, block, function_symbol(name, key),
+                      called, declared_parameters)
+      end
+
+      # The compiled functions the block reaches for, by the name it reaches
+      # them by.  Only these: everything else it closes over is refused, and
+      # `refuse_captures` is where that is said.  This runs before the
+      # registry is consulted, because the key cannot be built without it.
+      def called_functions (source, node, block, own_name)
+        names = capture_names(source, node) - block.parameters.map(&:last)
+        names -= [own_name.to_sym] if own_name
+        binding = binding_of(block)
+        names.each_with_object({}) do |captured, found|
+          value = captured_value(captured, binding)
+          # A function compiled here is pasted into this one; one bound from
+          # a library is declared and called by its name, which is what it
+          # has and what a linker resolves.  Both are functions this body
+          # calls, so both are here.
+          found[captured] = value if value.is_a?(CFunction)
+        end
+      end
+
+      # What a name held where the block was written, or nil for one that
+      # held nothing.  A constant is looked up as well as a local, because a
+      # method body closes over nothing: a `def` that compiles a function
+      # reaches the one it calls by a constant or not at all.
+      def captured_value (name, binding)
+        if name.to_s.start_with?(/[A-Z]/)
+          binding.eval(name.to_s)
+        elsif binding.local_variable_defined?(name)
+          binding.local_variable_get(name)
+        end
+      rescue NameError
+        nil
+      end
+
+      # Whether the name held anything at all, which `captured_value` cannot
+      # say: a name holding nil and a name that is not there both come back
+      # as nil, and only one of them is worth a different message.
+      def captured_name_defined? (name, binding)
+        if name.to_s.start_with?(/[A-Z]/)
+          binding.eval("defined?(#{name})") ? true : false
+        else
+          binding.local_variable_defined?(name)
+        end
+      rescue NameError
+        false
       end
 
       def function_registry
@@ -621,19 +1082,24 @@ class CArray
       end
 
       def build_c_function (prototype, name, return_type, parameters,
-                       source, node, origin, block, symbol)
+                       source, node, origin, block, symbol, called = {},
+                       declared_parameters = nil)
         # A function is a function of its parameters.  Whatever else the block
         # reaches for is refused, and the reason differs by what it is -- so
         # the captures are looked at before the body is walked, or the body
         # would raise first and say something less useful.
-        names = block.parameters.map(&:last)
+        # A body written for `jit_call` takes no parameters -- the
+        # declaration named them, and the same names are the locals the call
+        # reads -- so the arity is the declaration's to state.
+        names = declared_parameters || block.parameters.map(&:last)
         unless names.size == parameters.size
           raise Unsupported,
                 "`#{prototype}` names #{parameters.size} " \
                 "#{parameters.size == 1 ? 'parameter' : 'parameters'}, and " \
                 "the block takes #{names.size}"
         end
-        refuse_captures(source, node, block, names, name && name.to_sym)
+        refuse_captures(source, node, block, names + called.keys,
+                        name && name.to_sym)
 
         # `void` is a return type a body may have: a function whose work is
         # through its pointer parameters has nothing to hand back, and C says
@@ -659,6 +1125,9 @@ class CArray
                         .to_h { |name, type|
                           [name, type.indexable? ? !type.const : nil]
                         }
+        pointer_lengths = names.zip(parameters)
+                               .select { |_, type| type.indexable? && type.sized? }
+                               .to_h { |name, type| [name, type.array] }
         pointer_types = names.zip(parameters).select { |_, type| type.indexable? }
                              .to_h { |name, type| [name, type.element.computation] }
 
@@ -666,8 +1135,11 @@ class CArray
         # own body, as C does, so the body can call itself.  An anonymous one
         # has nothing to call itself by, and gets no recursion.
         analyzer = Analyzer.new(source, node: node, function: true,
+                                declared_parameters: declared_parameters,
                                 returns: !returns_nothing,
                                 pointers: pointers,
+                                pointer_lengths: pointer_lengths,
+                                c_functions: called,
                                 recursion: (name && [name.to_sym, parameters,
                                                      return_type.computation]))
         names = analyzer.parameter_names
@@ -688,32 +1160,35 @@ class CArray
                    "the signature rather than a value; the body cannot read it"
                  end)
         end
-        # A body is handed its values through the kernel's three scalar buses,
-        # which carry doubles, int64s and complexes.  A uint64 argument is the
-        # one numeric type none of them can carry whole -- that is what having
-        # its own computation type means -- so it is refused here, where the
-        # declaration is, rather than deeper down as a kernel that cannot be
-        # built.  A `uint64_t *` reaches an array of them, and a uint64_t
-        # value comes back out of a body unharmed.
-        names.zip(parameters).each do |parameter, type|
-          next if type.pointer || type.computation != :uint64
-          raise Unsupported,
-                "`#{parameter}` is declared `#{type.text}`, and a value is " \
-                "handed to a body as a double, an int64 or a complex -- a " \
-                "uint64 fits none of them without losing a bit. Take " \
-                "`#{type.text} *` and index it, or take an int64 where the " \
-                "values are small enough to be one"
-        end
+        # A parameter of any computation type the body can work in, uint64
+        # included.  A kernel's captures have three buses to travel in and
+        # uint64 is not one of them, but these are not captures: they are the
+        # parameters of this function's own C signature, and arrive in the
+        # type the declaration named.  So `size_t n` is a value the body can
+        # be handed, which is the point -- it is how the C that counts bytes
+        # is spelled.
         types = names.zip(parameters).reject { |_, type| type.pointer }
                      .to_h { |parameter, type| [parameter, type.computation] }
 
-        assignment = TypeAssignment.new(analyzer.body, {}, {}, {},
+        assignment = TypeAssignment.new(analyzer.body, {}, {}, called,
                                         scalar_types: types,
                                         pointer_types: pointer_types)
         generator = CGenerator.new(analyzer, {}, assignment.scalar_types,
-                                   origin: origin, block_source: source)
+                                   c_functions: called,
+                                   origin: origin, block_source: source,
+                                   scalar_parameters: types.keys)
         c_source = generator.generate_function(
           symbol, names, parameters, return_type.text, return_type.computation)
+        # A signature carrying a complex by value gets a second entry point
+        # for Ruby to reach it by, since Fiddle has no such type to call
+        # with.  Only such a signature: everything else is called directly,
+        # and pays nothing for a road it does not take.
+        shim_symbol = nil
+        if return_type.complex? || parameters.any?(&:complex?)
+          shim_symbol = "#{symbol}_from_ruby"
+          c_source += shim_source(shim_symbol, symbol, names, parameters,
+                                  return_type)
+        end
         handle, = Compiler.build(c_source, symbol, header: generator.provenance)
         # Where the body can divide by zero or reach outside an array, the
         # object carries a place to say so.  Reading it is what lets a call
@@ -728,20 +1203,68 @@ class CArray
         pasted = generator
         if generator.uses_error_flag?
           pasted = CGenerator.new(analyzer, {}, assignment.scalar_types,
-                                  origin: origin, block_source: source)
+                                  c_functions: called,
+                                  origin: origin, block_source: source,
+                                  scalar_parameters: types.keys)
           pasted.generate_function(symbol, names, parameters, return_type.text,
                                    return_type.computation,
                                    error_parameter: true)
         end
-        CFunction.new(symbol, prototype, return_type, parameters, handle[symbol],
+        CFunction.new(name, prototype, return_type, parameters, handle[symbol],
+                  symbol: symbol,
+                  shim: shim_symbol && handle[shim_symbol],
                   block: block, c_source: generator.provenance + c_source,
                   origin: origin, error: error,
                   definition: pasted.function_definition,
                   helpers: pasted.helper_needs,
+                  dependencies: called.values,
                   takes_error: generator.uses_error_flag?,
                   raise_messages: generator.raise_messages)
       end
 
+      # The entry point a call from Ruby takes where the signature carries a
+      # complex by value.  Each complex argument arrives as the two doubles
+      # C99 lays one out as, and a complex result is written back the same
+      # way; every other parameter keeps its own type, so a pointer is still
+      # a pointer and an integer is still that integer.
+      #
+      # It calls the function rather than repeating it, so there is one body
+      # and both roads reach it.
+      def shim_source (shim_symbol, symbol, names, parameters, return_type)
+        declarations = names.zip(parameters).map { |name, type|
+          type.complex? ? "const double *#{name}" : type.declare(name)
+        }
+        passed = names.zip(parameters).map { |name, type|
+          next name unless type.complex?
+          "#{type.complex_build}(#{name}[0], #{name}[1])"
+        }
+        call = "#{symbol}(#{passed.join(', ')})"
+        if return_type.complex?
+          declarations << "double *carray_jit_result"
+          body = <<~C
+            #{return_type.text} carray_jit_value = #{call};
+              carray_jit_result[0] = creal(carray_jit_value);
+              carray_jit_result[1] = cimag(carray_jit_value);
+          C
+          head = "void"
+        else
+          body = "#{return_type.computation ? 'return ' : ''}#{call};\n"
+          head = return_type.text
+        end
+        <<~C
+
+          /* Fiddle has no type for a C99 complex, so a call from Ruby comes
+             through here: the complex arguments arrive as the two doubles
+             one is laid out as, and a complex result goes back the same way.
+             A kernel calls the function above directly, C to C. */
+          #{head}
+          #{shim_symbol} (#{declarations.join(', ')})
+          {
+            #{body.strip}
+          }
+        C
+      end
+
       # Nothing outside the parameter list may be reached.  A number could in
       # principle be written into the C as a literal, and another c_function's
       # address as a constant -- but both would put something in the compiled
@@ -766,16 +1289,30 @@ class CArray
         captured -= [own_name] if own_name
         return if captured.empty?
         name = captured.first
-        value = begin
-                  binding_of(block).local_variable_get(name)
-                rescue NameError
-                  nil
-                end
-        kind = case value
-               when CArray then "an array"
-               when CFunction  then "another C function"
-               else             "a value"
-               end
+        value = captured_value(name, binding_of(block))
+        # A CFunction never reaches here: `called_functions` took both
+        # kinds above -- compiled ones to paste, borrowed ones to declare and
+        # call by name -- so neither is a capture by the time this runs.
+        if value.is_a?(CArray::Rng)
+          # A generator has state, and a compiled function has nowhere to
+          # keep one -- the same reason a borrowed address is refused above.
+          # A kernel is handed its operands at every call and can be given
+          # the state among them; a function's arguments are the ones its
+          # declaration named, and adding one behind the caller's back would
+          # change the C signature it was promised.  So the state is named,
+          # and the body draws from it the way the generator's own C does.
+          raise Unsupported,
+                "this function reaches `#{name}`, which is a generator; a " \
+                "compiled function has nowhere to keep its state. Take the " \
+                "state as a parameter -- declare `int64_t state[4]` and pass " \
+                "`#{name}.state` -- or draw in the kernel that calls this, " \
+                "where `random(rng: #{name})` works"
+        end
+        unless captured_name_defined?(name, binding_of(block))
+          raise Unsupported,
+                "`#{name}` is not defined where the block was written"
+        end
+        kind = value.is_a?(CArray) ? "an array" : "a value"
         raise Unsupported,
               "this function reaches `#{name}`, which is #{kind} outside it; " \
               "a compiled function takes everything it needs through its " \