statifier 0.0.1 → 0.1.0

data/lib/statifier/driver/calls.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # The bodies of the driver's calls, which {Statifier.start},
+    # {Statifier.step}, {Statifier.advance}, {Statifier.report_send_failed},
+    # {Statifier.configuration} and {Statifier.done?} answer through, and
+    # the checks on what a host passes them.
+    #
+    # @api private
+    module Calls
+      module_function
+
+      # {Statifier.start}'s body.
+      #
+      # @return [Result]
+      def start(machine, options)
+        options = Checks.start_options(options)
+        types, session_id = options.values_at(:types, :session_id)
+        started = Interpreter::Loop.initialize(machine, **options.slice(:session_id, :clock, :datamodel, :trace,
+                                                                        :max_macrostep_rounds), **seams(options))
+        work = Run.begin_call(fresh(started.state, session_id, types), options[:processors], options[:clock])
+        ok(Run.drain(Run.perform(work, started.effects)).moved)
+      end
+
+      # What the driver declares to the interpreter as the chart starts: the
+      # registered types, their `_ioprocessors` entries and the routes.
+      def seams(options)
+        types, session_id = options.values_at(:types, :session_id)
+        { send_types: (types unless types.empty?), ioprocessors: entries(options[:processors], types, session_id),
+          routes: own_routes(session_id) }
+      end
+
+      # The driver's state over a machine state that has just started.
+      def fresh(machine_state, session_id, types)
+        State.new(machine_state:, session_id:, now_ms: 0, timers: [].freeze, timer_sequence: 0,
+                  external_queue: [].freeze, held_sends: {}.freeze, halted: nil, done: nil, send_types: types,
+                  invocations: {}.freeze, mailbox: [].freeze, invoked_as: nil, cancelled: false)
+      end
+
+      # {Statifier.step}'s body.
+      #
+      # @return [Result]
+      def step(state, name, data:, processors:, clock:)
+        work = Run.begin_call(Checks.state(state, processors), processors, clock)
+        raise TypeError, "an event name is a String, got #{name.class}" unless name.is_a?(String)
+        return refused(:not_running) unless state.machine_state.running
+
+        ok(Run.drain(Routing.enqueue(work, Event.external(name, data:), counted: false).stamped).moved)
+      end
+
+      # {Statifier.report_send_failed}'s body: the failed send's
+      # `error.communication` delivered onto the internal queue and the chart
+      # run to a stable configuration, then the external queue taken, as a
+      # step takes it. Refused once the chart has stopped, and while a
+      # macrostep's round budget has halted it, as the reference's session
+      # drops a report then.
+      #
+      # @return [Result]
+      def report_send_failed(machine, state, send, options)
+        processors, clock = Checks.report(machine, state, send, options).values_at(:processors, :clock)
+        work = Run.begin_call(Checks.state(state, processors), processors, clock)
+        return refused(:not_running) unless state.machine_state.running
+        return refused(:halted) unless state.halted.nil?
+
+        work, deferred = Delivery.failed(work.stamped, send)
+        ok(Run.drain(Run.perform(work, deferred)).moved)
+      end
+
+      # {Statifier.advance}'s body: the clock moved `milliseconds` forward, every
+      # timer due by then, anywhere in the tree of sessions, fired in
+      # due-then-scheduled order, each run to completion before the next: the
+      # session it fired in, then each session above it.
+      #
+      # @return [Result]
+      def advance(state, milliseconds, processors:, clock:)
+        work = Run.begin_call(Checks.state(state, processors), processors, clock)
+        return refused(:invalid_duration) unless duration?(milliseconds)
+
+        until_ms = state.now_ms + milliseconds
+        while (found = next_due(work.state, until_ms))
+          path, timer = found
+          work = fire_at(work.with_state(now_ms: timer.due_ms), path, timer)
+        end
+        ok(work.with_state(now_ms: until_ms).moved)
+      end
+
+      # The timer fired in the session `path` (the invoke ids from this
+      # session down) names, each session on the way drained after it.
+      def fire_at(work, path, timer)
+        return fire(due(work, timer), timer.delayed) if path.empty?
+
+        Run.drain(Mailbox.within(work, path.first) { fire_at(_1, path.drop(1), timer) })
+      end
+
+      # Whether `value` is a duration the clock can move by: a real number,
+      # finite and not negative.
+      def duration?(value) = value.is_a?(Numeric) && value.real? && value.finite? && value >= 0
+
+      # The work with `timer` taken off the pending timers and the clock at
+      # its due time.
+      def due(work, timer)
+        work.with_state(timers: work.state.timers.reject { _1.equal?(timer) }.freeze, now_ms: timer.due_ms)
+      end
+
+      # The earliest pending timer due by `until_ms` in the tree, the first
+      # scheduled among equals, as `[path, timer]`, or nil.
+      def next_due(state, until_ms)
+        pending(state, []).select { _2.due_ms <= until_ms }.min_by { [_2.due_ms, _2.sequence] }
+      end
+
+      # Every pending timer of the tree under `state`, each with the path to
+      # its session.
+      def pending(state, path)
+        state.timers.map { [path, _1] } +
+          state.invocations.flat_map { |id, invocation| pending(invocation.child, path + [id]) }
+      end
+
+      # A fired timer's send, routed as an immediate one is but never
+      # counted, then the external queue taken. While a macrostep's budget
+      # has halted the session, a send to the session itself still joins
+      # its external queue, and any other is dropped, as the reference drops
+      # it.
+      def fire(work, send)
+        unless work.state.halted.nil?
+          return work unless Routing.destination(work, send) == :external
+
+          return Routing.enqueue(work, Routing.delivered_event(send, work.state.session_id), counted: false)
+        end
+
+        work, deferred = Routing.route(work.stamped, send, undelayed: false)
+        Run.drain(Run.perform(work, deferred))
+      end
+
+      # {Statifier.configuration}'s body: the active states' ids, the root
+      # left out, sorted. A state the document gave no id is named `#` and
+      # its index, a spelling no XML id can take.
+      #
+      # @return [Result]
+      def configuration(state)
+        Checks.state(state, nil)
+        ok(names(state.machine_state.machine, state.machine_state.configuration - [0]))
+      end
+
+      # {Statifier.done?}'s body.
+      #
+      # @return [Result]
+      def done?(state)
+        Checks.state(state, nil)
+        done = state.done
+        return ok(DoneStatus.new(done: false, donedata: nil, configuration: nil)) if done.nil?
+
+        ok(DoneStatus.new(done: true, donedata: done.donedata,
+                          configuration: names(state.machine_state.machine, done.configuration - [0])))
+      end
+
+      # The states at `indexes` by name, sorted, a frozen list.
+      def names(machine, indexes) = indexes.map { machine.state(_1).id || "##{_1}" }.sort.freeze
+
+      # A successful result.
+      def ok(value) = Result.new(value:, error: nil)
+
+      # A refused call.
+      def refused(reason) = Result.new(value: nil, error: reason)
+
+      # The routes a session the driver runs can reach: itself, its parent
+      # when it has one, and its live invocations, by id.
+      def own_routes(session_id, parent: false, invokes: [].freeze)
+        Interpreter::Targets::Routes.new(sessions: [session_id].freeze, parent?: parent, invokes: invokes.freeze)
+      end
+
+      # Each registered type's `_ioprocessors` entry, asked of its processor
+      # once as the chart starts; empty when it answers none.
+      def entries(processors, types, session_id)
+        context = Context.new(session_id:)
+        types.to_h do |type|
+          processor = processors[type]
+          [type, processor.respond_to?(:ioprocessors_entry) ? processor.ioprocessors_entry(type, context) : {}]
+        end
+      end
+    end
+  end
+end

data/lib/statifier/driver/checks.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # The checks on what a host passes the driver's calls.
+    #
+    # @api private
+    module Checks
+      module_function
+
+      # The options {Statifier.start} takes, as they stand when the host
+      # names none.
+      START_OPTIONS = {
+        session_id: nil, datamodel: {}.freeze, processors: {}.freeze, max_macrostep_rounds: MAX_MACROSTEP_ROUNDS,
+        trace: false, clock: nil
+      }.freeze
+
+      # {Statifier.start}'s options, after checking them, with the
+      # registered `types` and the `session_id`, minted when the host named
+      # none.
+      #
+      # @raise [ArgumentError] for an option {START_OPTIONS} does not name,
+      #   or a round budget that is neither a positive Integer nor
+      #   `:infinity`
+      def start_options(options)
+        options = known(options, START_OPTIONS)
+        budget(options[:max_macrostep_rounds])
+        options.merge(types: registered_types(options[:processors]), session_id: session_id(options[:session_id]))
+      end
+
+      # The registered types, sorted, after checking the processors.
+      #
+      # @raise [TypeError] when `processors` is not a Hash of String types to
+      #   objects answering `deliver`
+      def registered_types(processors)
+        raise TypeError, "processors is a Hash of send types to processors" unless processors.is_a?(Hash)
+
+        processors.each do |type, processor|
+          raise TypeError, "a send type is a String, got #{type.inspect}" unless type.is_a?(String)
+          raise TypeError, "the processor for #{type.inspect} does not answer deliver" \
+            unless processor.respond_to?(:deliver)
+        end
+        processors.keys.sort.freeze
+      end
+
+      # `state`, after checking it, and, unless `processors` is nil, that
+      # they register the types the chart was started with.
+      #
+      # @raise [TypeError] when `state` is not a driver state
+      # @raise [ArgumentError] when the processors name other types
+      def state(state, processors)
+        raise TypeError, "expected a driver state a call answered, got #{state.class}" unless state.is_a?(State)
+        return state if processors.nil? || registered_types(processors) == state.send_types
+
+        raise ArgumentError, "processors must register the types the chart started with: #{state.send_types}"
+      end
+
+      # The options {Statifier.report_send_failed} takes, as they stand when
+      # the host names none.
+      REPORT_OPTIONS = { reason: nil, processors: {}.freeze, clock: nil }.freeze
+
+      # A failed-send report's options, after checking them and the chart and
+      # the send it names against `state`.
+      #
+      # @raise [TypeError] when `state` is not a driver state, `machine` is
+      #   not a compiled machine or `send` is not a send a processor is handed
+      # @raise [ArgumentError] for an option {REPORT_OPTIONS} does not name, or
+      #   when `state` is not an execution of `machine`
+      def report(machine, state, send, options)
+        options = known(options, REPORT_OPTIONS)
+        raise TypeError, "expected a compiled machine, got #{machine.class}" unless machine.is_a?(Machine)
+        raise TypeError, "expected a Statifier::Effect::Send or SendDelayed, got #{send.class}" \
+          unless send.is_a?(Effect::Send) || send.is_a?(Effect::SendDelayed)
+        return options if state(state, nil).machine_state.machine == machine
+
+        raise ArgumentError, "the state is not an execution of the machine named"
+      end
+
+      # `options` over `defaults`, after checking that `defaults` names
+      # every one.
+      #
+      # @raise [ArgumentError] for an option `defaults` does not name
+      def known(options, defaults)
+        unknown = options.keys - defaults.keys
+        raise ArgumentError, "unknown options: #{unknown.inspect}" unless unknown.empty?
+
+        defaults.merge(options)
+      end
+
+      # The session id the host named, or a fresh one, frozen: a host's
+      # string is copied first, so the state holds nothing the host can
+      # change and the host's string is never frozen in place.
+      #
+      # @raise [TypeError] when it is neither nil nor a String
+      def session_id(session_id)
+        return -SessionId.mint if session_id.nil?
+        return -session_id if session_id.is_a?(String)
+
+        raise TypeError, "a session id is a String, got #{session_id.class}"
+      end
+
+      # The round budget, after checking it.
+      def budget(budget)
+        return budget if budget == :infinity || (budget.is_a?(Integer) && budget.positive?)
+
+        raise ArgumentError, "max_macrostep_rounds is a positive Integer or :infinity, got #{budget.inspect}"
+      end
+    end
+  end
+end

data/lib/statifier/driver/delivery.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # A send of a registered type handed to the host's processor, and a send
+    # that processor could not deliver, as the reference's session hands a
+    # send to its processor's `deliver/3` and writes a failed send in
+    # `Statifier.Session.failed_send/3`. Each function answers
+    # `[work, deferred effects]`, as {Routing}'s do.
+    #
+    # @api private
+    module Delivery
+      module_function
+
+      # A registered type's send handed to its processor with the event a
+      # delivery would carry; a delayed one is held under its send id, so a
+      # `<cancel>` of that id reaches the processor. A {DeliveryFailure} the
+      # processor answers fails the send here, at its place in the call, as
+      # the reference raises the failure its processor plans in `deliver/3`.
+      # The failure counts against the call's budget as an undelayed send
+      # onto the internal queue does, so a chart that sends again on every
+      # failure halts rather than running on within the call.
+      def hand_off(work, send)
+        work = hold(work, send) if send.is_a?(Effect::SendDelayed)
+        event = Routing.delivered_event(send, work.state.session_id)
+        answered = work.processors.fetch(send.type).deliver(send, event, work.context)
+        return [work, []] unless answered.is_a?(DeliveryFailure)
+
+        Routing.counted(work) { failed(_1, send) }
+      end
+
+      # The work with the send's type holding a delayed send under its id.
+      def hold(work, send)
+        types = (work.state.held_sends.fetch(send.send_id, []) | [send.type]).sort.freeze
+        work.with_state(held_sends: work.state.held_sends.merge(send.send_id => types).freeze)
+      end
+
+      # A send its processor could not deliver, as the reference's
+      # `Statifier.Session.failed_send/3` writes it: `error.communication`
+      # on the internal queue, its origin the send's content and its
+      # `sendid` the send's id whether or not its author named it.
+      def failed(work, send) = Routing.communication_error(work, send, sendid: send.send_id)
+    end
+  end
+end

data/lib/statifier/driver/invocations.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # The invocations a session holds and the child sessions behind them, as
+    # the reference's session runs a built-in `scxml` invocation
+    # (`Statifier.Session`, `Statifier.Session.Invocations` and
+    # `Statifier.Invoke.Source` in statifier-ex), with a child's {State}
+    # held in its parent's {Invocation} in place of a process. {Driver} says
+    # what each does; what passes between a parent and its child is
+    # {Mailbox}'s.
+    #
+    # A child runs as a work of its own ({Mailbox.within}): it starts on its
+    # parent's clock and timer sequence, and its state, the timer sequence
+    # it leaves, its effects and what it sent its parent go back to the
+    # parent once it has run.
+    #
+    # @api private
+    module Invocations
+      # The fields of an error an invocation raises: no data and no send id.
+      NO_FIELDS = { data: Predicator::UNDEFINED, sendid: nil }.freeze
+
+      module_function
+
+      # One invocation effect acted on: `[work, deferred effects]`.
+      def perform(work, effect)
+        case effect
+        when Effect::Invoke then start(work, effect)
+        when Effect::CancelInvoke then [cancel(work, effect.invoke_id), []]
+        when Effect::Autoforward then [Mailbox.deliver(work, effect.invoke_id, effect.event), []]
+        else [work, []]
+        end
+      end
+
+      # An {Effect::Invoke}: a type other than the SCXML type raises
+      # `error.execution`; content that is not markup, or does not compile,
+      # raises `error.communication`; otherwise the child is started.
+      # `[work, deferred effects]`.
+      def start(work, effect)
+        origin = { kind: :invoke, state_index: effect.state_index, invoke_index: effect.invoke_index }
+        unless Interpreter::Invoke.built_in_type?(effect.type)
+          return Routing.deliver_internal(work, :platform, "error.execution", origin, NO_FIELDS)
+        end
+
+        machine = effect.content.is_a?(String) ? compile(effect.content) : nil
+        return Routing.deliver_internal(work, :platform, "error.communication", origin, NO_FIELDS) if machine.nil?
+
+        [launch(work, effect, machine), []]
+      end
+
+      # Inline content markup compiled as the reference's
+      # `Statifier.Invoke.Source` compiles it, a root with no namespace
+      # accepted; nil when any stage refuses it.
+      def compile(source)
+        parsed = XML.parse(source)
+        return nil unless parsed.ok?
+
+        lowered = Lowering.lower(parsed.value, source)
+        return nil unless lowered.ok?
+
+        validated = Validator.validate(lowered.value, source, invoke_content_markup: true)
+        return nil unless validated.ok?
+
+        compiled = Compiler.compile(validated.value, warnings: validated.warnings)
+        compiled.ok? ? compiled.value : nil
+      end
+
+      # The child started, recorded live under its invoke id, and run to a
+      # stable configuration.
+      def launch(work, effect, machine)
+        child = child_start(work, effect, machine)
+        work = work.put_invocation(Invocation.new(invoke_id: effect.invoke_id, autoforward: effect.autoforward == true,
+                                                  completed: false, caller_context: effect.caller_context,
+                                                  child: child.state))
+        Mailbox.within(work, effect.invoke_id) { Run.drain(Run.perform(_1, child.effects)) }
+      end
+
+      # The child's start: its {State} and the effects its start answered,
+      # as a {Interpreter::Stepped}. Its session id is its parent's, a dot
+      # and the invoke id.
+      def child_start(work, effect, machine)
+        session_id = -"#{work.state.session_id}.#{effect.invoke_id}"
+        started = Interpreter::Loop.initialize(machine, **start_options(work, session_id, effect.params, machine))
+        state = Calls.fresh(started.state, session_id, work.state.send_types).with(invoked_as: effect.invoke_id)
+        Interpreter::Stepped.new(state:, effects: started.effects)
+      end
+
+      # What the child starts with: its parent's registered types, their
+      # `_ioprocessors` entries asked for its own session id, its parent's
+      # trace flag, and its datamodel seeded ({seed}).
+      def start_options(work, session_id, params, machine)
+        types = work.state.send_types
+        { session_id:, clock: work.clock, datamodel: seed(params, machine), trace: work.machine_state.trace,
+          send_types: (types unless types.empty?), ioprocessors: Calls.entries(work.processors, types, session_id),
+          routes: Calls.own_routes(session_id, parent: true) }
+      end
+
+      # The reference's `Invocations.seed_datamodel/2`: the params a root
+      # `<data>` of the child names, the rest dropped.
+      def seed(params, machine)
+        return {} unless params.is_a?(Hash)
+
+        params.slice(*machine.state(0).data.map { machine.data_elements.fetch(_1).id })
+      end
+
+      # An {Effect::CancelInvoke}: the invocation retired, then its child
+      # stopped, its active states' `<onexit>` handlers run, its effects
+      # reported and what it sent its parent discarded. An invocation whose
+      # child already said it completed is left for its done event, and an
+      # id that names nothing live is a no-op.
+      def cancel(work, invoke_id)
+        invocation = work.state.invocations[invoke_id]
+        return work if invocation.nil? || invocation.completed
+
+        work = work.drop_invocation(invoke_id)
+        return work unless invocation.child.machine_state.running
+
+        Mailbox.absorb(work, stop(work, work.synced(invocation.child).with(cancelled: true)))
+      end
+
+      # The cancelled child's run: the reference's `Interpreter.cancel/1`
+      # and the effects it answered acted on.
+      def stop(work, child)
+        handled = Interpreter::Loop.cancel(child.machine_state)
+        Run.perform(Run.begin_call(child, work.processors, work.clock).with_machine(handled.state), handled.effects)
+      end
+    end
+  end
+end

data/lib/statifier/driver/mailbox.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Driver
+    # What passes between a session and its invoked children, as the
+    # reference's session passes it (`Statifier.Session`, its
+    # `Statifier.Session.Invocations` table and `Statifier.Invoke.Answer` in
+    # statifier-ex): a child run inside its parent's work ({within}), an
+    # event delivered to a child, and what a child sends its parent - an
+    # event to `#_parent`, the notice that it completed and its donedata -
+    # waiting in the parent's mailbox until the parent takes it.
+    #
+    # @api private
+    module Mailbox
+      module_function
+
+      # The child under `invoke_id` run by the block, which takes and
+      # answers the child's work, then its state, timer sequence, effects
+      # and mail taken back.
+      #
+      # @return [Work]
+      def within(work, invoke_id)
+        invocation = work.state.invocations.fetch(invoke_id)
+        ran = yield Run.begin_call(work.synced(invocation.child), work.processors, work.clock)
+        receive(absorb(work.put_invocation(invocation.with(child: ran.state)), ran), ran.outbox)
+      end
+
+      # The work with what a child's run left it: the timer sequence and the
+      # effects.
+      def absorb(work, ran) = work.with_state(timer_sequence: ran.state.timer_sequence).report_all(ran.effects)
+
+      # The work with a child's mail in its mailbox, an undelayed send's
+      # counted.
+      def receive(work, outbox)
+        outbox.reduce(work) do |acc, (mail, counted)|
+          acc = acc.with_state(mailbox: (acc.state.mailbox + [mail]).freeze)
+          counted ? acc.with(counted: (acc.counted + [mail]).freeze) : acc
+        end
+      end
+
+      # A send to `#_parent`: the event, stamped with the invoke id, into
+      # the parent's mailbox.
+      def to_parent(work, event, counted:)
+        event = Frozen.copy(event.with(invokeid: work.state.invoked_as))
+        work.post(Mail.new(kind: :event, invoke_id: work.state.invoked_as, payload: event), counted:)
+      end
+
+      # An event for the live child under `invoke_id`: it joins the child's
+      # external queue and the child runs to a stable configuration. Nothing
+      # reaches an invocation that is not live, or a child that has stopped.
+      def deliver(work, invoke_id, event)
+        invocation = work.state.invocations[invoke_id]
+        return work if invocation.nil? || !invocation.child.machine_state.running
+
+        within(work, invoke_id) { Run.drain(Routing.enqueue(_1, event, counted: false).stamped) }
+      end
+
+      # A child whose batch stops it tells its parent it completed, ahead of
+      # everything the batch sends; a cancelled child does not.
+      #
+      # @return [Work]
+      def announce(work, batch)
+        state = work.state
+        return work if state.invoked_as.nil? || state.cancelled || batch.none?(Effect::Done)
+
+        work.post(Mail.new(kind: :completed, invoke_id: state.invoked_as, payload: nil))
+      end
+
+      # A child that stopped on its own sends its parent its donedata; one
+      # that was cancelled sends nothing.
+      #
+      # @return [Work]
+      def return_done(work, done)
+        state = work.state
+        return work if state.invoked_as.nil? || state.cancelled
+
+        work.post(Mail.new(kind: :done, invoke_id: state.invoked_as, payload: done.donedata))
+      end
+
+      # One mailbox entry. One that carries an event declares the routes as
+      # it arrives; an entry whose invocation is no longer live is
+      # discarded.
+      #
+      # @return [Work]
+      def take_mail(work, mail)
+        work = work.stamped unless mail.kind == :completed
+        invocation = work.state.invocations[mail.invoke_id]
+        invocation.nil? ? work : open_mail(work, mail, invocation)
+      end
+
+      # A live invocation's entry: a completion notice marks it completed;
+      # an event is taken as an external event; and the done event, built
+      # here, retires it once taken.
+      #
+      # @return [Work]
+      def open_mail(work, mail, invocation)
+        case mail.kind
+        when :completed then work.put_invocation(invocation.with(completed: true))
+        when :event then Run.take(work, mail.payload)
+        else Run.take(work, done_event(work.state.session_id, invocation, mail.payload)).drop_invocation(mail.invoke_id)
+        end
+      end
+
+      # The reference's `Invoke.Answer.done/4`: `done.invoke.` and the
+      # invoke id, its data the child's donedata, from the parent's own
+      # address, carrying the invocation's `caller_context`.
+      #
+      # @return [Event]
+      def done_event(session_id, invocation, donedata)
+        Frozen.copy(Event.external(
+                      "done.invoke.#{invocation.invoke_id}",
+                      data: donedata, invokeid: invocation.invoke_id,
+                      origin: Datamodel::SystemVariables.scxml_location(session_id),
+                      origintype: Datamodel::SystemVariables::SCXML_EVENT_PROCESSOR,
+                      caller_context: invocation.caller_context
+                    ))
+      end
+    end
+  end
+end