carray-jit 0.1.3 → 0.1.4

data/lib/carray/jit/c_function.rb

@@ -111,9 +111,10 @@ class CArray
 
       def initialize (name, prototype, return_type, parameters, pointer,
                       symbol: nil,
-                      block: nil, c_source: nil, origin: nil, error: nil,
+                      block: nil, c_source: nil, origin: nil,
                       definition: nil, helpers: nil, takes_error: false,
-                      raise_messages: {}, dependencies: [], shim: nil)
+                      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.
@@ -142,9 +143,10 @@ class CArray
         @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.
@@ -324,6 +326,7 @@ class CArray
         # 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 },
@@ -338,6 +341,7 @@ class CArray
           code = error_code
         ensure
           write_error(outer)
+          rearm_hook(hook)
         end
         raise_for(code)
         # A view was copied to be made contiguous; a writable one is copied
@@ -384,6 +388,7 @@ class CArray
         }
         outer = error_code
         write_error(0)
+        hook = disarm_hook
         begin
           Access.open(arrays.map { |_, buffer, _| buffer },
                       arrays.map { |_, _, type| !type.const },
@@ -399,6 +404,7 @@ class CArray
           code = error_code
         ensure
           write_error(outer)
+          rearm_hook(hook)
         end
         raise_for(code)
         arrays.each do |array, buffer, type|
@@ -458,18 +464,28 @@ class CArray
       # 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)
+      #
+      # `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
-          code = error_code
         rescue StandardError
-          raise_for(error_code)
+          # 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
-          write_error(outer)
+          code = close_window(opened) if opened
         end
         raise_for(code)
         result
@@ -500,17 +516,173 @@ class CArray
         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
 
-      # 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
+      # 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
-        @error ? @error[0, 4].unpack1("l") : 0
+        state = error_state
+        state ? state.flag[0, 4].unpack1("l") : 0
       end
 
       def write_error (code)
-        @error[0, 4] = [code].pack("l") if @error
+        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)
@@ -641,6 +813,14 @@ class CArray
           "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
@@ -797,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?
@@ -829,6 +1010,33 @@ 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.
@@ -980,8 +1188,127 @@ class CArray
                            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
@@ -1154,10 +1481,12 @@ 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 parameter of any computation type the body can work in, uint64
@@ -1193,9 +1522,18 @@ class CArray
         # 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
@@ -1214,7 +1552,7 @@ class CArray
                   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,