carray-jit 0.1.2 → 0.1.4

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,32 @@ 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,
-                      block: nil, c_source: nil, origin: nil, error: nil,
+                      symbol: nil,
+                      block: nil, c_source: nil, origin: nil,
                       definition: nil, helpers: nil, takes_error: false,
-                      raise_messages: {})
+                      raise_messages: {}, dependencies: [], shim: nil,
+                      error_state: 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,15 +136,21 @@ 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.
         @takes_error = takes_error
         @raise_messages = raise_messages
         @origin = origin
-        # 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
+        # What the object answers when asked where this thread's flag, hook
+        # and stand-in stand.  Nil when the body can neither divide by zero
+        # nor raise, and so has none of them.
+        @error_state = error_state
+        # 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 +177,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 +204,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 +302,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 +319,31 @@ 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)
+        hook = disarm_hook
+        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)
+          rearm_hook(hook)
         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 +354,79 @@ 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)
+        hook = disarm_hook
+        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)
+          rearm_hook(hook)
+        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 +439,284 @@ 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.
+      #
+      # `stand_in:` is the number a call answers C with once the flag stands,
+      # for a library that reads the return value as a status rather than as
+      # a value -- GSL's callbacks return `int`, and 0 is `GSL_SUCCESS`
+      # there, so a failed body reporting 0 tells GSL the step went well.  It
+      # is cast to whatever the body returns and is 0 until a window says
+      # otherwise, which is what a failed call has always answered.  Set for
+      # the length of the window, and put back afterwards.
+      def watching (stand_in: nil)
+        opened = open_window(nil, JIT.send(:window_stand_in, stand_in))
+        code = 0
+        begin
+          result = yield
+        rescue StandardError
+          # The library is complaining about what a stand-in did.  The body's
+          # own failure is the cause, so it is the one that comes out.
+          code = close_window(opened)
+          opened = nil
+          raise_for(code)
+          raise
+        ensure
+          code = close_window(opened) if opened
+        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
+
+      # A C function to call when the body fails, so that whoever holds the
+      # address can be told to stop rather than go on being handed stand-ins:
+      #
+      #   f.on_error(nlopt["nlopt_force_stop"], opt)
+      #   f.watching { nlopt_optimize.call(opt, x, minf) }
+      #
+      # `hook` is the address of a `void (*)(void *)` -- a Fiddle::Pointer,
+      # an Integer, or anything answering #to_i -- and `data` is the one
+      # argument it is called with.  It is called once, from the call whose
+      # body put the flag up, and not again until the flag has been put down
+      # and has gone up again; nothing about it reaches Ruby, so it may be
+      # called from a thread that holds no GVL. `nil` takes it away.
+      #
+      # `#call` does not call it: that is one call made from Ruby, and it
+      # answers for itself by raising, as it does inside a window. A body
+      # that cannot fail has no flag to go up, so for it this is accepted
+      # and never called.
+      #
+      # Like the flag, it belongs to the thread that set it: a body lent from
+      # two threads at once has a hook and a flag in each of them, and this
+      # sets the one belonging to the thread that calls it. So it is set on
+      # the thread that will lend the address, which is where `#watching` is
+      # written anyway.
+      #
+      # Returns self.
+      def on_error (hook, data = nil)
+        state = error_state
+        return self unless state
+        address = hook.nil? ? 0 : hook.to_i
+        state.data[0, Fiddle::SIZEOF_VOIDP] =
+          [data.nil? ? 0 : data.to_i].pack("J")
+        state.hook[0, Fiddle::SIZEOF_VOIDP] = [address].pack("J")
+        state.held = hook.nil? ? nil : [hook, data]
+        self
+      end
+
+      private
+
+      # One thread's copy of the four the compiled object carries -- the
+      # flag, the hook's address, the pointer it is handed, and what a failed
+      # call answers C with -- with the Ruby objects `#on_error` was given
+      # held beside them, so that nothing the C may still call is collected.
+      ErrorState = Struct.new(:flag, :hook, :data, :standin, :held)
+      private_constant :ErrorState
+
+      # Where those copies are kept, per thread.  A thread variable rather
+      # than a fiber-local one, because what is being tracked is the C's own
+      # storage: every fiber running on a thread reaches that thread's copy.
+      THREAD_STATES = :carray_jit_error_states
+      private_constant :THREAD_STATES
+
+      # This thread's, resolved by asking the object where they stand and
+      # kept for as long as the thread lives -- a thread's copies do not
+      # move.  Nil where the body cannot fail at all: one that neither
+      # divides nor raises is compiled without a flag, and has no failure to
+      # report rather than an unread one.
+      def error_state
+        return nil unless @error_state
+        thread = Thread.current
+        kept = thread.thread_variable_get(THREAD_STATES)
+        unless kept
+          kept = {}
+          thread.thread_variable_set(THREAD_STATES, kept)
+        end
+        # By symbol, which carries a digest of the body: two functions with
+        # the same symbol are one compiled object and one set of copies.
+        kept[@symbol] ||= resolve_error_state
+      end
+
+      def resolve_error_state
+        out = String.new("\0" * (4 * Fiddle::SIZEOF_VOIDP))
+        @error_state.call(out)
+        flag, hook, data, standin = out.unpack("J4")
+        ErrorState.new(Fiddle::Pointer.new(flag, 4),
+                       Fiddle::Pointer.new(hook, Fiddle::SIZEOF_VOIDP),
+                       Fiddle::Pointer.new(data, Fiddle::SIZEOF_VOIDP),
+                       Fiddle::Pointer.new(standin, 8),
+                       nil)
+      end
+
+      # 0 where the body cannot fail at all.
+      def error_code
+        state = error_state
+        state ? state.flag[0, 4].unpack1("l") : 0
+      end
+
+      def write_error (code)
+        state = error_state
+        state.flag[0, 4] = [code].pack("l") if state
+      end
+
+      # The hook's address, cleared for the length of one call from Ruby,
+      # and put back afterwards.
+      def disarm_hook
+        state = error_state
+        return nil unless state
+        held = state.hook[0, Fiddle::SIZEOF_VOIDP]
+        state.hook[0, Fiddle::SIZEOF_VOIDP] = "\0" * Fiddle::SIZEOF_VOIDP
+        held
+      end
+
+      def rearm_hook (held)
+        state = error_state
+        state.hook[0, Fiddle::SIZEOF_VOIDP] = held if state && held
+      end
+
+      # What a window does at its two ends.  `#watching` is these with a
+      # block between them, and `CArray::JIT.watching` is these over several
+      # functions at once -- which is why they are named rather than written
+      # inline in the one method that had them.
+      #
+      # `hook` is the `[address, data]` a window wants a hook of its own for,
+      # and `standin` what it wants a failed call to answer C with; nil for
+      # either leaves whatever is set alone.
+      def open_window (hook = nil, standin = nil)
+        outer = error_code
+        write_error(0)
+        [outer, hook && hold_hook(*hook), standin && hold_standin(standin)]
+      end
+
+      # What this window's calls reported, with the flag, the hook and the
+      # stand-in put back as they were found.
+      def close_window (opened)
+        outer, held, standin = opened
+        code = error_code
+        write_error(outer)
+        restore_hook(held)
+        restore_standin(standin)
+        code
+      end
+
+      # This window's hook set and the one it displaced handed back, so that
+      # the window can put it there again.  `#on_error` writes these two
+      # pointers; what it has no way to do is read them, and a window that
+      # brings a hook of its own has to -- otherwise it leaves with the
+      # owner's gone and nothing said about it.
+      def hold_hook (address, data)
+        state = error_state
+        return nil unless state
+        held = [state.hook[0, Fiddle::SIZEOF_VOIDP],
+                state.data[0, Fiddle::SIZEOF_VOIDP], state.held]
+        on_error(address, data)
+        held
+      end
+
+      def restore_hook (held)
+        state = error_state
+        return unless state && held
+        state.hook[0, Fiddle::SIZEOF_VOIDP] = held[0]
+        state.data[0, Fiddle::SIZEOF_VOIDP] = held[1]
+        state.held = held[2]
+      end
+
+      # This window's stand-in written, and the one it displaced handed back.
+      # Held as the eight bytes rather than as a number, so that whatever was
+      # there goes back exactly as it stood.
+      def hold_standin (value)
+        state = error_state
+        return nil unless state
+        held = state.standin[0, 8]
+        state.standin[0, 8] = [value].pack("q")
+        held
+      end
+
+      def restore_standin (held)
+        state = error_state
+        state.standin[0, 8] = held if state && held
+      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 +758,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,24 +783,51 @@ 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 words C builds its integer types from.  They may come in any
+      # order and `int` may be left out -- `unsigned`, `long unsigned int`
+      # and `int unsigned` are all C -- while Fiddle reads only some of those
+      # orders, fails on a bare `unsigned`, and reads `int unsigned` as a
+      # signed int without saying so.  So a spelling made only of these is
+      # counted here and handed to Fiddle in the one order it reads.
+      INTEGER_WORDS = %w[signed unsigned char short int long].freeze
+
       # The CArray data type a pointer parameter takes, by the code Fiddle
       # gave its element.  This is the table CGenerator::STORAGE_C_TYPES
       # 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 +848,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 +913,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/) {
@@ -473,6 +977,7 @@ class CArray
         if (reason = REFUSED[spelling])
           raise Unsupported, "#{reason} (in `#{prototype}`)"
         end
+        spelling = integer_spelling(spelling, text, prototype)
         # A parameter written as an array is a pointer at the ABI, whatever
         # its declarator says.
         pointer ||= !array.nil?
@@ -484,12 +989,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 +1010,42 @@ class CArray
                   array, element, keywords.include?("const"))
       end
 
+      # `long unsigned int` as `unsigned long`, `unsigned` as `unsigned int`:
+      # the order Fiddle reads, for a spelling made only of INTEGER_WORDS.
+      # Anything else is handed back untouched.  A combination C does not
+      # have -- `signed unsigned`, `short long`, three `long`s -- is refused
+      # here rather than left to a parser that has been seen to guess.
+      def integer_spelling (spelling, text, prototype)
+        words = spelling.split(/\s+/)
+        return spelling unless words.all? { |word| INTEGER_WORDS.include?(word) }
+        count = words.tally
+        longs = count.fetch("long", 0)
+        base = count.keys & %w[char short]
+        if count.values_at("signed", "unsigned", "char", "short", "int")
+                .any? { |n| n.to_i > 1 } ||
+           (count.key?("signed") && count.key?("unsigned")) ||
+           base.size > 1 || (base.any? && longs > 0) || longs > 2 ||
+           (count.key?("char") && count.key?("int"))
+          raise Unsupported,
+                "`#{text.strip}` in `#{prototype}` is not a C integer type"
+        end
+        sign = count.key?("unsigned") ? "unsigned " : ""
+        width = base.first || { 0 => "int", 1 => "long", 2 => "long long" }.fetch(longs)
+        # `signed char` is a type of its own in C, apart from plain `char`,
+        # and Fiddle reads both as the one byte they are.
+        sign = "signed " if width == "char" && count.key?("signed")
+        "#{sign}#{width}"
+      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 +1106,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,11 +1184,131 @@ 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
+
+      # One window over several functions, for a call that is handed more
+      # than one address:
+      #
+      #   CArray::JIT.watching(objective, gradient) do
+      #     NLopt.optimize(option, x, minimum)
+      #   end
+      #
+      # Every flag is put down before the block, and every one is read after
+      # it -- because a flag nobody reads is a failure that becomes a wrong
+      # answer, and then surfaces on an unrelated later window.  Whichever
+      # failure comes first in the argument list is the one raised, and a
+      # failure raised this way outranks whatever the block raised, for the
+      # reason `CFunction#watching` gives: the library is complaining about
+      # a stand-in, and the stand-in is the consequence.
+      #
+      # `on_error:` is the `[hook, data]` pair `CFunction#on_error` takes,
+      # set on every function for the length of the window and taken off
+      # again afterwards -- with whatever hook was there before put back.
+      # That is the difference from calling `#on_error` around the block:
+      # the pair can be read back here and cannot be read back from Ruby, so
+      # a window that brings its own hook is the only way to borrow one
+      # without leaving the owner's gone.
+      #
+      # `stand_in:` is the number a failed call answers C with, as
+      # `CFunction#watching` takes it, and is set on every function watched.
+      # Which number is right belongs to the window and not to the body: the
+      # same `int (*)(...)` may be handed to a routine that stops on a
+      # non-zero status and to one that reads it as a rejected step and tries
+      # again, and the body has no way of knowing which it was given to.
+      #
+      # `nil` in the list is skipped, so an optional gradient or jacobian may
+      # be passed as it stands, and a function named twice is watched once.
+      # A body that cannot fail has no flag, no hook and no stand-in, and
+      # passing one changes nothing -- which is what lets a binding watch
+      # what it was given without asking which kind of body it is.
+      def watching (*functions, on_error: nil, stand_in: nil)
+        armed = functions.compact
+        armed.each do |function|
+          next if function.is_a?(CFunction)
+          raise TypeError,
+                "`CArray::JIT.watching` watches compiled functions, and " \
+                "#{function.class} is not one -- pass what `jit_function` " \
+                "or `jit_extern` answered"
+        end
+        armed = armed.uniq
+        hook = window_hook(on_error)
+        standin = window_stand_in(stand_in)
+        return yield if armed.empty?
+        opened = armed.map { |function|
+          function.send(:open_window, hook, standin)
+        }
+        codes = []
+        begin
+          result = yield
+        rescue StandardError
+          # Closed here rather than in the ensure below, so that the failure
+          # raised next is raised from inside this rescue and carries the
+          # library's own complaint as its cause.
+          codes = close_windows(armed, opened)
+          opened = nil
+          raise_first_failure(armed, codes)
+          raise
+        ensure
+          codes = close_windows(armed, opened) if opened
+        end
+        raise_first_failure(armed, codes)
+        result
       end
 
       private
 
+      # Every window closed, in the order they were opened, and what each of
+      # them saw.  All of them, whatever happened in the block: a flag nobody
+      # reads is one that surfaces on an unrelated later window.
+      def close_windows (armed, opened)
+        armed.zip(opened).map { |function, state|
+          function.send(:close_window, state)
+        }
+      end
+
+      # The first failure among the flags just read, raised as the function
+      # that reported it would raise it.  A code of 0 is no failure and is
+      # passed over, so this walks the list in the order it was written and
+      # stops at the first that has something to say.
+      def raise_first_failure (armed, codes)
+        armed.zip(codes).each do |function, code|
+          function.send(:raise_for, code)
+        end
+      end
+
+      # The number a window hands the C as a failed call's answer.  An
+      # Integer because that is what the object carries it in -- one 64-bit
+      # word, cast at the return -- and because a status is a whole number
+      # wherever one is read.
+      def window_stand_in (stand_in)
+        return nil if stand_in.nil?
+        unless stand_in.is_a?(Integer)
+          raise TypeError,
+                "`stand_in:` is the number a failed call answers C with, " \
+                "and #{stand_in.class} is not one -- it is cast to whatever " \
+                "the body returns, so what is given here is an Integer"
+        end
+        unless (-(2**63)...2**63).cover?(stand_in)
+          raise RangeError,
+                "`stand_in:` is carried in one 64-bit word, and " \
+                "#{stand_in} does not fit in one"
+        end
+        stand_in
+      end
+
+      def window_hook (on_error)
+        return nil if on_error.nil?
+        unless on_error.is_a?(Array) && (1..2).cover?(on_error.size)
+          raise ArgumentError,
+                "`on_error:` takes the hook and the one pointer it is " \
+                "handed, as `CFunction#on_error` does -- " \
+                "`on_error: [handle[\"nlopt_force_stop\"], option]`"
+        end
+        [on_error[0], on_error[1]]
+      end
+
       def bind_c_function (prototype, name, return_type, parameters, from)
         handle = library_handle(from)
         begin
@@ -592,28 +1328,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 +1409,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 +1452,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 +1462,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
@@ -682,45 +1481,59 @@ class CArray
           raise Unsupported,
                 (if type.indexable?
                    "`#{loose}` is declared `#{type.text}`, which is a pointer; " \
-                   "index it, as in `#{loose}[0]`"
+                   "index it, as in `#{loose}[0]`, or ask whether one came, " \
+                   "as in `if #{loose}` or `#{loose}.nil?`"
                  else
                    "`#{loose}` is declared `#{type.text}`, which is a slot in " \
-                   "the signature rather than a value; the body cannot read it"
+                   "the signature rather than a value; the body cannot read " \
+                   "it, only ask whether it was filled, as in `#{loose}.nil?`"
                  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
         # from Ruby raise what the same expression raises in Ruby.
-        error = if generator.uses_error_flag?
-                  Fiddle::Pointer.new(handle[CGenerator::ERROR_FLAG], 4)
-                end
+        #
+        # The place is the calling thread's, and a thread-local is not a name
+        # the loader can hand an address for, so what is taken here is the
+        # accessor beside it -- called once per thread, from that thread.  It
+        # is named after the body, the four it answers for being `static`, so
+        # that two objects generated this way can be linked side by side.
+        error_state = if generator.uses_error_flag?
+                        accessor = CGenerator.error_state_name(symbol)
+                        Fiddle::Function.new(handle[accessor],
+                                             [Fiddle::TYPE_VOIDP],
+                                             Fiddle::TYPE_VOID, name: accessor)
+                      end
         # A body that reports failures is generated a second time for pasting,
         # with the flag as a parameter.  A second generator rather than the
         # same one twice: what it emitted is what it holds, and the two forms
@@ -728,20 +1541,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,
+                  origin: origin, error_state: error_state,
                   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 +1627,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 " \