excadg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1d50ffd84523c400ae4733e67c53d54a791cb066cec4a49dea27b4e7072ecda
+  data.tar.gz: 4b5bf03ce6c2e9190e5af55a9f740247281da6ed6522c37a7ee3dd3698352dc9
+SHA512:
+  metadata.gz: 274e5395a4d9ed5da1c5aba9a368638757f1571ac38aede22b0f729a794813c4611e41dfb901a9d555c0a202d7b494b47e077b9c379383a7cb116c2f1dd32ecd
+  data.tar.gz: e35cd2c39d26791742b1c9ff1255f3c2edb9247b046a09dad62013c6bd9e48fdae54be73e17ae4e1fb430a385a2ec8bc19cfba63a54deffb21b27d59a196da50

data/lib/excadg/assertions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ExcADG
+  # collection of simple assertions
+  module Assertions
+    class << self
+      # asserts that all vars are instances of one of the clss
+      def is_a? vars, clss
+        return if vars.is_a?(Array) && clss == Array
+
+        clss = [clss] unless clss.is_a? Array
+        vars = [vars] unless vars.is_a? Array
+        wrong_vars = vars.reject { |var|
+          clss.any? { |cls|
+            var.is_a? cls
+          }
+        }
+        raise "vars #{wrong_vars} not of classes #{clss}" unless wrong_vars.empty?
+      end
+    end
+  end
+end

data/lib/excadg/broker.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+require_relative 'data_store'
+require_relative 'log'
+require_relative 'request'
+require_relative 'vertex'
+
+module ExcADG
+  # handle requests sending/receiving though Ractor's interface
+  module Broker
+    class << self
+      attr_reader :data_store
+
+      # is used from vertices to send reaqests to the broker
+      # @return data received in response from the main ractor
+      # @raise StandardError if response is a StandardError
+      # @raise CantSendRequest if sending request failed for any reason
+      def ask request
+        raise UnknownRequestType, request unless request.is_a? Request
+
+        begin
+          Ractor.main.send request
+        rescue StandardError => e
+          raise CantSendRequest, cause: e
+        end
+
+        Log.info 'getting response'
+        resp = Ractor.receive
+        Log.debug "got response #{resp}"
+        raise resp if resp.is_a? StandardError
+
+        Log.debug 'returning response'
+        resp
+      end
+
+      # start requests broker for vertices in a separated thread
+      # @return the thread started
+      def run
+        @data_store ||= DataStore.new
+        @broker = Thread.new { loop { process_request } } unless @broker&.alive?
+
+        at_exit {
+          Log.info 'shut down broker'
+          @broker.kill
+        }
+
+        Log.info 'broker is started'
+        @broker
+      end
+
+      # makes a thread to wait for all known vertices to reach a final state
+      # @param timeout total waiting timeout in seconds, nil means wait forever
+      # @param period time between vertices state check
+      def wait_all timeout: 60, period: 1
+        Thread.new {
+          Log.info "timeout is #{timeout} seconds"
+          Timeout.timeout(timeout) {
+            loop {
+              sleep period
+              states = @data_store.to_a.group_by(&:state).keys
+              Log.info "vertices in #{states} exist"
+              # that's the only final states for vertices
+              break if (states - %i[done failed]).empty?
+            }
+          }
+        }
+      end
+
+      private
+
+      # waits for an incoming request,
+      # validates request type and content
+      # then makes and sends an answer
+      def process_request
+        begin
+          request = Ractor.receive
+          Log.info "received request: #{request}"
+          request.self.send case request
+                            when Request::GetStateData
+                              request.filter? ? request.deps.collect { |d| @data_store[d] } : @data_store.to_a
+                            when Request::Update
+                              @data_store << request.data
+                              true
+                            when Request::AddVertex
+                              Vertex.new payload: request.payload, deps: [request.self]
+                            else
+                              raise UnknownRequestType
+                            end
+        rescue StandardError => e
+          Log.warn "error on message processing: #{e.class} / #{e.message} / #{e.backtrace}"
+          request.self.send RequestProcessingFailed.new cause: e
+        end
+        Log.debug 'message processed'
+      end
+    end
+
+    class UnknownRequestType < StandardError; end
+    class CantSendRequest < StandardError; end
+
+    # error type returned by broker thread in case it failed to process incoming request
+    class RequestProcessingFailed < StandardError
+      attr_reader :cause
+
+      def initialize cause:
+        super
+        @cause = cause
+      end
+    end
+  end
+end

data/lib/excadg/data_store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'assertions'
+require_relative 'vstate_data'
+
+module ExcADG
+  # collection of {ExcADG::VStateData} for {ExcADG::Broker}
+  class DataStore
+    attr_reader :size
+
+    def initialize
+      # two hashes to store VStateData and access them fast by either key
+      @by_name = {}
+      @by_vertex = {}
+      @size = 0
+    end
+
+    # add new element to the store
+    # adds it to the two hashes to access lated by either attribute
+    # @return current number of elements
+    def << new
+      Assertions.is_a? new, VStateData::Full
+      if (by_name = @by_name[new.name]) && !(by_name.vertex.eql? new.vertex)
+        raise DataSkew,
+              "Vertex named #{new.name} - #{new.vertex} is recorded as #{by_name.vertex} in state"
+      end
+      if (by_vertex = @by_vertex[new.vertex]) && !(by_vertex.name.eql? new.name)
+        raise DataSkew,
+              "Vertex #{new.vertex} named #{new.name} is already named #{by_vertex.name}"
+      end
+
+      @size += 1 unless key? new
+
+      @by_name[new.name] = new if new.name
+      @by_vertex[new.vertex] = new if new.vertex
+    end
+
+    # retrieves VStateData by key
+    # @param key either Vertex or VStateData::Key to retrieve Full state data
+    # @return VStateData::Full for the respective key
+    # @raise StandardError if key is not of a supported type
+    def [] key
+      Assertions.is_a? key, [Vertex, VStateData::Key, Symbol, String]
+
+      case key
+      when Vertex then @by_vertex[key]
+      when Symbol, String then @by_name[key]
+      when VStateData::Key
+        if key.name && @by_name.key?(key.name)
+          @by_name[key.name]
+        elsif key.vertex && @by_vertex.key?(key.vertex)
+          @by_vertex[key.vertex]
+        else
+          nil
+        end
+      end
+    end
+
+    # retrieve all vertices state data,
+    # could contain huge amount of data and be slow to work with;
+    # prefer to access vertices data by name using [] instead
+    def to_a
+      (@by_name.values + @by_vertex.values).uniq
+    end
+
+    # checks if there is data for a given key
+    def key? key
+      case key
+      when Vertex then @by_vertex.key? key
+      when Symbol, String then @by_name.key? key
+      when VStateData::Key
+        @by_name.key?(key.name) || @by_vertex.key?(key.vertex)
+      else
+        false
+      end
+    end
+
+    class DataSkew < StandardError; end
+  end
+end

data/lib/excadg/dependency_manager.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal:true
+
+require_relative 'assertions'
+require_relative 'log'
+require_relative 'vstate_data'
+
+module ExcADG
+  # manage list of dependencies
+  # dependencies could be of 2 types:
+  # - vertex - see vertex.rb
+  # - symbol - :name attribute of the vertex
+  class DependencyManager
+    attr_reader :deps, :data
+
+    # @param deps list of symbols or vertices to watch for as dependencies
+    def initialize deps:
+      Assertions.is_a? deps, Array
+      Assertions.is_a? deps, [Vertex, Symbol]
+
+      @deps = deps.collect { |raw_dep|
+        case raw_dep
+        when Symbol then VStateData::Key.new name: raw_dep
+        when Vertex then VStateData::Key.new vertex: raw_dep
+        end
+      }
+      @data = []
+    end
+
+    # deduct (update) dependencies with new data
+    # - counts :done dependencies
+    # - preserves :done deps data
+    # @param new_data - Array of VStateData retrieved from the broker
+    def deduct_deps new_data
+      data = filter_foreign new_data
+      Log.debug "received deps: #{data}"
+
+      assert_failed data
+
+      done_deps = data.select(&:done?)
+      @data += done_deps
+      Log.debug "done deps: #{done_deps}"
+
+      @deps.reject! { |dep| done_deps.include? dep }
+      Log.info "deps left: #{@deps.collect(&:to_s)}}"
+    end
+
+    private
+
+    # filters out deps doesn't belong to the manager
+    def filter_foreign new_data
+      if (new_data - @deps).empty?
+        new_data
+      else
+        Log.warn 'non-deps state received, filtering'
+        Log.debug "non-dep states: #{new_data - @deps}"
+        new_data.filter { |state_data| deps.include? state_data }
+      end
+    end
+
+    # checks if any dependencies in the received data are failed
+    def assert_failed data
+      failed_deps = data.select(&:failed?).collect(&:to_s)
+      Log.debug "failed deps: #{failed_deps}"
+      raise "some deps failed: #{failed_deps}" unless failed_deps.empty?
+    end
+  end
+end

data/lib/excadg/log.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require_relative 'assertions'
+
+module ExcADG
+  # logging support
+  module Log
+    # ractor-based logger
+    # this ractor logger receives messages from other ractors and log them
+    # it can be useful in case logging shouldn't interrupt other thread
+    # @param dest - what to write logs to, $stdout by default, gets interpret as filename unless IO
+    # @param level - one of the Logger's log levels
+    class RLogger < Ractor
+      def self.new dest: $stdout, level: Logger::INFO
+        super(dest, level) { |dest, level|
+          File.open(dest, 'w+', &:write) unless dest.is_a? IO
+          l ||= Logger.new dest
+          l.level = level
+          l.formatter = proc { |severity, datetime, progname, msg|
+            format('%20s | %4s | %-10s || %s', datetime, severity, progname, msg)
+          }
+          while log = Ractor.receive
+            # Expect 3 args - severity, proc name and message
+            l.public_send(log.first, log[1], &-> { log.last.to_s + "\n" })
+          end
+        }
+      end
+    end
+
+    def self.method_missing(method, *args, &_block)
+      return if @muted
+
+      r = Ractor.current
+      @main.send [method, r&.to_s || r.object_id, *args]
+    rescue Ractor::ClosedError => e
+      # last hope - there is tty
+      puts "can't send message to logging ractor: #{e}"
+    end
+
+    def self.respond_to_missing?
+      true
+    end
+
+    # default logger e.g. for tests
+    @main = RLogger.new
+    @muted = false
+
+    # replaces default logger with a custom logger
+    def self.logger new_logger
+      Assertions.is_a? new_logger, RLogger
+      @main = new_logger
+    end
+
+    # mute logging by ignoring all incoming log requests
+    def self.mute
+      @muted = true
+    end
+  end
+end

data/lib/excadg/payload/example.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative '../broker'
+require_relative '../request'
+
+module ExcADG
+  # payload examples to demonstrate framework capabilities
+  # most of the payloads in the file are used in tests
+  module Payload::Example
+    # minimalistic payload that does nothing
+    # but echoes its args or :ping by default
+    class Echo
+      include Payload
+      def get
+        -> { @args }
+      end
+
+      def sanitize args
+        args.nil? ? :ping : args
+      end
+    end
+
+    # dependencies data processing example
+    # deps_data is an Array with a VStateData objects for each dependency
+    # the example just checks that all deps returned :ping, fails otherwise
+    class Receiver
+      include Payload
+      def get
+        lambda { |deps_data|
+          deps_data.collect { |d|
+            raise 'incorrect data received from dependencies' unless d.data.eql? :ping
+          }
+        }
+      end
+    end
+
+    # payload that fails
+    class Faulty
+      include Payload
+
+      def get
+        -> { raise @args }
+      end
+    end
+
+    # payload that sleeps @args or 1 second(s)
+    class Sleepy
+      include Payload
+      def get
+        -> { sleep @args }
+      end
+
+      def sanitize args
+        args.is_a?(Integer) ? args : 0.1
+      end
+    end
+
+    # calculate Nth member of the function
+    # y = x(n) * (x(n-1)) where x(0) = 0 and x(1) = 1
+    # it illustrates how payload can be customized with @args
+    # and extended by adding methods
+    class Multiplier
+      include Payload
+      def get
+        -> { get_el x: @args }
+      end
+
+      def get_el x:
+        case x
+        when 0 then 0
+        when 1 then 1
+        else
+          x * get_el(x: x - 1)
+        end
+      end
+    end
+
+    # payload that does something on condition received from its deps
+    # see spec/vertex_spec.rb for full example
+    class Condition
+      include Payload
+      def get
+        lambda { |deps_data|
+          ExcADG::Broker.ask ExcADG::Request::AddVertex.new(payload: Echo.new) if deps_data.all? { |d| d.data.eql? :trigger }
+        }
+      end
+    end
+
+    # payload that implements an idiomatic loop by
+    # making N vertices - one for each of its dependencies
+    class Loop
+      include Payload
+      def get
+        lambda { |deps_data|
+          deps_data.first.data.collect { |e|
+            ExcADG::Broker.ask ExcADG::Request::AddVertex.new payload: Echo.new(args: e)
+          }
+        }
+      end
+    end
+  end
+end

data/lib/excadg/payload/wrapper.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'open3'
+
+module ExcADG
+  # Payloads that wraps other programs execution
+  module Payload::Wrapper
+    # runs a binary
+    # save its stdout, stderr and exit code to state
+    # provides path to temp file with dependencies data JSON in a DEPS_DATAFILE env variable
+    class Bin
+      include Payload
+      def get
+        lambda { |deps_data|
+          begin
+            f = nil
+            Dir.mktmpdir { |dir|
+              f = File.new File.join(dir, 'data.json'), 'w+'
+              f.write JSON.generate deps_data
+              f.flush
+              stdout, stderr, status = Open3.capture3({ 'DEPS_DATAFILE' => f.path }, args)
+              data = { stdout:, stderr:, exitcode: status.exitstatus }
+              raise CommandFailed, data unless status.exitstatus.zero?
+
+              data
+            }
+          ensure
+            f&.close
+          end
+        }
+      end
+
+      def sanitize args
+        raise "arguments should be a String, got #{args}" unless args.is_a? String
+
+        args
+      end
+
+      # exception with command execution result
+      # for cases when the command fails
+      class CommandFailed < StandardError
+        # @param data same data as what would be returned by a successful run
+        def initialize data
+          super 'command failed'
+          @data = data
+        end
+
+        def to_json(*args)
+          @data.to_json(*args)
+        end
+      end
+    end
+
+    # runs a ruby script
+    # behaves same as the Bin reg parameters and return data
+    class Ruby < Bin
+      def sanitize args
+        raise "arguments should be a String, got #{args}" unless args.is_a? String
+
+        "ruby #{args}"
+      end
+    end
+  end
+end

data/lib/excadg/payload.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ExcADG
+  # module to base payload for {ExcADG::Vertex} -es on it,
+  # reason for having this special module to provider simple labmdas
+  # is that Ractor (which is a base for {ExcADG::Vertex})
+  # require its parameters scope to be shareable
+  module Payload
+    attr_accessor :args
+
+    # main method of the payload that holds code to be executed within vertex,
+    # vertex takes care of error processing - there is no need to mask exceptions,
+    # this method should return a Proc, that:
+    # * could receive up to 1 arguments
+    # * 1st argument, if specified, is an {Array} of {ExcADG::VStateData} from the vertex dependencies
+    # * could access @args of the obejct, which was set on object's constructing
+    # @return {Proc}
+    # @raise {ExcADG::Payload::NoPayloadSet} by default to fail vertices with partially-implemented payload
+    def get
+      raise NoPayloadSet, 'payload is empty'
+    end
+
+    # constructor to store arguments for the lambda in the object
+    #
+    # implementation implies that child class could implement {#sanitize}
+    # to transform args as needed
+    def initialize args: nil
+      @args = respond_to?(:sanitize) ? send(:sanitize, args) : args
+    end
+
+    class NoPayloadSet < StandardError; end
+    class IncorrectPayloadArity < StandardError; end
+  end
+end
+
+require_relative 'payload/example'
+require_relative 'payload/wrapper'

data/lib/excadg/request.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'assertions'
+require_relative 'payload'
+require_relative 'vstate_data'
+
+module ExcADG
+  # base class for messages between Ractors
+  class Request
+    attr_reader :self
+
+    def initialize
+      @self = Ractor.current
+    end
+
+    # request to get state data
+    class GetStateData < ExcADG::Request
+      attr_reader :deps
+
+      # @param deps Array of VStateData::Key
+      def initialize deps: nil
+        super()
+        @deps = deps
+      end
+
+      def filter?
+        !@deps.nil?
+      end
+    end
+
+    # request to update self state in the central storage
+    class Update < ExcADG::Request
+      attr_reader :data
+
+      def initialize data:
+        super()
+        Assertions.is_a? data, VStateData::Full
+
+        @data = data
+      end
+    end
+
+    # request to make and start a new vertex
+    class AddVertex < ExcADG::Request
+      attr_reader :payload
+
+      def initialize payload:
+        super()
+        raise "Incorrent payload type: #{payload.class}" unless payload.is_a? Payload
+
+        @payload = payload
+      end
+    end
+  end
+end

data/lib/excadg/rtimeout.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ExcADG
+  # simple ractor-safe timeout implementation
+  # @param timeout timeout in seconds
+  # @param block payload to run with timeout
+  module RTimeout
+    def await timeout: nil, &block
+      return block.call if timeout.nil? || timeout.zero?
+
+      timed_out = false
+      payload = Thread.new { Thread.current[:result] = block.call }
+      Thread.new {
+        sleep timeout
+        payload.kill
+        timed_out = true
+      }
+
+      payload.join
+      timed_out ? raise(TimedOutError) : payload[:result]
+    end
+    module_function :await
+
+    class TimedOutError < StandardError; end
+  end
+end

data/lib/excadg/state_machine.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'rgl/adjacency'
+require 'rgl/base'
+
+require_relative 'broker'
+require_relative 'log'
+require_relative 'request'
+require_relative 'vstate_data'
+
+module ExcADG
+  # carry states and transitions for individual vertices
+  class StateMachine
+    # sets in stone possible state transitions
+    GRAPH = RGL::DirectedAdjacencyGraph.new
+    GRAPH.add_edge :new, :ready
+    GRAPH.add_edge :ready, :done
+    # any transition could end-up in a failed state
+    GRAPH.add_vertex :failed
+    Ractor.make_shareable GRAPH
+
+    # add states graph to the current object
+    def initialize name:
+      @state = :new
+      @state_edge_bindings = {}
+      @state_transition_data = {}
+
+      @name = name
+    end
+
+    # bind action to one of the state graph's edges
+    def bind_action source, target, &block
+      [source, target].each { |state|
+        raise WrongState, "unknown state #{state}" unless GRAPH.has_vertex? state
+      }
+      raise WrongTransition.new source, target unless GRAPH.has_edge? source, target
+
+      edge = GRAPH.edges.find { |e| e.source == source && e.target = target }
+      @state_edge_bindings[edge] = block
+    end
+
+    # transition to next state
+    # @return: state data (result) / nil if it's a final step
+    def step
+      Log.debug 'taking another step'
+      assert_state_transition_bounds
+
+      target_candidates = GRAPH.each_adjacent @state
+      Log.debug "possible candidates: #{target_candidates.size}"
+      return nil if target_candidates.none?
+      raise WrongState, "state #{@state} has more than one adjacent states" unless target_candidates.one?
+
+      target = target_candidates.first
+      Log.debug "found a candidate: #{target}"
+      edge = GRAPH.edges.find { |e| e.source == @state && e.target = target }
+      begin
+        @state_transition_data[target] = @state_edge_bindings[edge].call
+        @state = target
+        Log.debug "moved to #{@state}"
+      rescue StandardError => e
+        Log.error "step failed with #{e} / #{e.backtrace}"
+        @state_transition_data[:failed] = e
+        @state = :failed
+      ensure
+        begin
+          Broker.ask Request::Update.new data: state_data
+        rescue StandardError => e
+          @state_transition_data[:failed] = e
+          @state = :failed
+          Broker.ask Request::Update.new data: state_data
+        end
+      end
+      @state_transition_data[@state]
+    end
+
+    def assert_state_transition_bounds
+      raise NotAllTransitionsBound, GRAPH.edges - @state_edge_bindings.keys unless GRAPH.edges.eql? @state_edge_bindings.keys
+    end
+
+    # makes state data for the current vertex
+    def state_data
+      VStateData::Full.new name: @name, data: @state_transition_data[@state], state: @state
+    end
+
+    class WrongState < StandardError; end
+
+    class WrongTransition < StandardError
+      def initialize src, dest
+        super("Transition #{src} -> #{dest} is not available.")
+      end
+    end
+
+    class NotAllTransitionsBound < StandardError; end
+  end
+end

data/lib/excadg/tui.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'io/console'
+
+require_relative 'broker'
+require_relative 'state_machine'
+
+module ExcADG
+  # render status on the screen
+  module Tui
+    MAX_VERTEX_TO_SHOW = 10
+    DELAY = 0.2
+    DEFAULT_BOX_SIZE = { height: 50, width: 150 }.freeze
+    # TODO: do runtime calc
+    BOX_SIZE = {
+      height: DEFAULT_BOX_SIZE[:height] > (IO.console&.winsize&.first || 1000) ? IO.console.winsize.first : DEFAULT_BOX_SIZE[:height],
+      width: DEFAULT_BOX_SIZE[:width] > (IO.console&.winsize&.last || 1000) ? IO.console.winsize.last : DEFAULT_BOX_SIZE[:width]
+    }.freeze
+    CONTENT_SIZE = {
+      height: BOX_SIZE[:height] - 4, # 2 for borders, 1 for \n, 1 for remark
+      width: BOX_SIZE[:width] - 5 # 2 for borders, 2 to indent
+    }.freeze
+    LINE_TEMPLATE = "| %-#{CONTENT_SIZE[:width]}s |\n".freeze
+
+    @started_at = DateTime.now.strftime('%Q').to_i
+
+    class << self
+      # spawns a thread to show stats to console in background
+      def run
+        Log.info 'spawning tui'
+        @thread = Thread.new {
+          loop {
+            print_in_box stats
+            sleep DELAY
+          }
+        }
+      end
+
+      def summarize has_failed, timed_out
+        @thread.kill
+        print_in_box stats + (print_summary has_failed, timed_out)
+      end
+
+      private
+
+      # @param content is a list of lines to print
+      def print_in_box content
+        clear
+        print "+-#{'-' * CONTENT_SIZE[:width]}-+\n"
+        content[..CONTENT_SIZE[:height]].each { |line|
+          if line.size > CONTENT_SIZE[:width]
+            printf LINE_TEMPLATE, "#{line[...(CONTENT_SIZE[:width] - 3)]}..."
+          else
+            printf LINE_TEMPLATE, line
+          end
+        }
+        if content.size < CONTENT_SIZE[:height]
+          (CONTENT_SIZE[:height] - content.size).times { printf LINE_TEMPLATE, ' ' }
+        else
+          printf LINE_TEMPLATE, '<some content did not fit and was cropped>'[..CONTENT_SIZE[:width]]
+        end
+        print "+-#{'-' * CONTENT_SIZE[:width]}-+\n"
+      end
+
+      def print_summary has_failed, timed_out
+        [timed_out ? 'execution timed out' : 'execution completed',
+         "#{has_failed ? 'some' : 'no'} vertices failed"]
+      end
+
+      # make summary paragraph on veritces
+      def stats
+        [
+          "time spent (ms): #{DateTime.now.strftime('%Q').to_i - @started_at}",
+          "vertices seen: #{Broker.data_store.size}",
+          'progress:'
+        ] + state_stats.collect { |line| "  #{line}" }
+      end
+
+      def clear
+        print "\e[2J\e[f"
+      end
+
+      # make states summary, one for a line with consistent placing
+      def state_stats
+        skeleton = StateMachine::GRAPH.vertices.collect { |v| [v, []] }.to_h
+        # rubocop:disable Style/HashTransformValues
+        filled = skeleton.merge Broker.data_store.to_a
+                                      .group_by(&:state)
+                                      .collect { |state, vertices| [state, vertices_stats(vertices)] }
+                                      .to_h
+        # rubocop:enable Style/HashTransformValues
+        filled.collect { |k, v| format '%-10s: %s', k, "#{v.empty? ? '<none>' : v}" }
+      end
+
+      def vertices_stats vertice_pairs
+        full_list = vertice_pairs.collect(&:name)
+        addition = full_list.size > MAX_VERTEX_TO_SHOW ? "... and #{full_list.size - MAX_VERTEX_TO_SHOW} more" : ''
+        full_list[0...MAX_VERTEX_TO_SHOW].join(', ') + addition
+      end
+    end
+  end
+end

data/lib/excadg/vertex.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'broker'
+require_relative 'dependency_manager'
+require_relative 'log'
+require_relative 'payload'
+require_relative 'request'
+require_relative 'rtimeout'
+require_relative 'state_machine'
+
+module ExcADG
+  # Individual vertex of the execution graph to run in a separated Ractor
+  class Vertex < Ractor
+    include RTimeout
+
+    # @return parsed info about the Ractor: number, file, line in file, status
+    def info
+      inspect.scan(/^#<Ractor:#(\d+)\s(.*):(\d+)\s(\w+)>$/).first
+    end
+
+    # Ractor's internal status
+    # @return Symbol, :unknown if parsing failed
+    def status
+      (info&.dig(3) || :unknwon).to_sym
+    end
+
+    # @return Ractor's number, -1 if parsing failed
+    def number
+      info&.dig(0).to_i || -1
+    end
+
+    def to_s
+      "#{number} #{status}"
+    end
+
+    # below are shortcut methods to access Vertex data from the main Ractor
+
+    # obtains current Vertex-es data by lookup in the Broker's data,
+    # available from the main Ractor only
+    def data
+      Broker.data_store[self]
+    end
+
+    # gets current Vertex's state,
+    # available from the main Ractor only
+    def state
+      data&.state
+    end
+
+    # gets current Vertex's name,
+    # available from the main Ractor only
+    def name
+      data&.name
+    end
+
+    class << self
+      # make a vertex, it runs automagically
+      # @param payload Payload object to run in this Vertex
+      # @param name optional vertex name to identify vertex
+      # @param deps list of other Vertices or names to wait for
+      # @param timeout total time in seconds for the payload to run
+      # @raise Payload::IncorrectPayloadArity in case payload returns function with arity > 1
+      # @raise Payload::NoPayloadSet in case payload provided has incorrect type
+      def new payload:, name: nil, deps: [], timeout: nil
+        raise Payload::NoPayloadSet, "expected payload, got #{payload.class}" unless payload.is_a? Payload
+
+        raise Payload::IncorrectPayloadArity, "arity is #{payload.get.arity}, supported only 0 and 1" unless [0, 1].include? payload.get.arity
+
+        super(payload, name, timeout, DependencyManager.new(deps:)) { |payload, name, timeout, deps_manager|
+          state_machine = StateMachine.new(name: name || "v#{number}".to_sym)
+          Broker.ask Request::Update.new data: state_machine.state_data
+          Log.info 'building vertex lifecycle'
+          state_machine.bind_action(:new, :ready) {
+            until deps_manager.deps.empty?
+              deps_data = Broker.ask Request::GetStateData.new(deps: deps_manager.deps)
+              deps_manager.deduct_deps deps_data
+              sleep 0.2
+            end
+            deps_manager.data
+          }
+          state_machine.bind_action(:ready, :done) {
+            function = payload.get
+            await(timeout:) {
+              case function.arity
+              when 0 then function.call
+              when 1 then function.call state_machine.state_data.data
+              else
+                raise Payload::IncorrectPayloadArity, "unexpected payload arity: #{function.arity}, supported only 0 and 1"
+              end
+            }
+          }
+
+          Log.debug "another step fades: #{state_machine.state_data}" while state_machine.step
+
+          Log.debug 'shut down'
+        }
+      end
+    end
+  end
+end

data/lib/excadg/vstate_data.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal:true
+
+require 'json'
+
+require_relative 'assertions'
+require_relative 'state_machine'
+require_relative 'vertex'
+
+module ExcADG
+  # Vertex state data as filled by {ExcADG::StateMachine}
+  # to be transferred between vertices
+  module VStateData
+    # class to support comparison and Arrays operations
+    class Key
+      attr_reader :name, :vertex
+
+      def initialize name: nil, vertex: nil
+        raise 'name or vertex are required' if name.nil? && vertex.nil?
+
+        Assertions.is_a?(vertex, Vertex) unless vertex.nil?
+
+        @name = name
+        @vertex = vertex
+      end
+
+      include Comparable
+      def <=> other
+        return nil unless (other.is_a? self.class) || (is_a? other.class)
+        # no mutual fields to compare
+        return nil if (@vertex.nil? && other.name.nil?) || (@name.nil? && other.vertex.nil?)
+
+        # name takes preference
+        @name.nil? || other.name.nil? ? @vertex <=> other.vertex : @name <=> other.name
+      end
+
+      def eql? other
+        (self <=> other)&.zero? || false
+      end
+
+      def to_s
+        (@name || @vertex).to_s
+      end
+    end
+
+    # contains actual data
+    class Full < Key
+      attr_reader :state, :data, :name, :vertex
+
+      # param state: Symbol, one of StateMachine.GRAPH.vertices
+      # param data: all data returned by a Vertice's Payload
+      # param name: Symboli -c name of the associated Vertex
+      # param vertex: Vertex that produced the data
+      def initialize state:, data:, name:, vertex: nil
+        # observation: Ractor.current returns Vertex object if invoked from a Vertex
+        super(name:, vertex: vertex || Ractor.current)
+        @state = state
+        @data = data
+      end
+
+      def to_s
+        "#{name || vertex} (#{state})"
+      end
+
+      # method omits objects without a good known text representation
+      def to_json(*args)
+        {
+          name: @name,
+          state: @state,
+          data: @data
+        }.to_json(*args)
+      end
+
+      # converts full object to key to use in Hash
+      def to_key
+        Key.new vertex: @vertex, name: @name
+      end
+
+      # auto-generated methods to check states easier;
+      # note: define_method causes these object to become un-shareable
+      # what breaks Broker's messaging
+      def method_missing(method, *_args, &_block)
+        raise NoMethodError unless respond_to_missing? method, _args
+
+        @state.eql? method[...-1].to_sym
+      end
+
+      def respond_to_missing? method, *_args
+        method.to_s.end_with?('?') && ExcADG::StateMachine::GRAPH.has_vertex?(method[...-1].to_sym)
+      end
+    end
+  end
+end

data/lib/excadg.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal:true
+
+# Execute Acyclic Directed Graph
+module ExcADG; end
+
+require_relative 'excadg/assertions'
+require_relative 'excadg/broker'
+require_relative 'excadg/data_store'
+require_relative 'excadg/dependency_manager'
+require_relative 'excadg/log'
+require_relative 'excadg/payload'
+require_relative 'excadg/request'
+require_relative 'excadg/rtimeout'
+require_relative 'excadg/state_machine'
+require_relative 'excadg/tui'
+require_relative 'excadg/vertex'
+require_relative 'excadg/vstate_data'

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: excadg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- skorobogatydmitry
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-06 00:00:00.000000000 Z
+dependencies: []
+description: "# Description\n\nThat's a library (framework) to execute a graph of
+  dependent tasks (vertices).  \nIts main feature is to run all possible tasks independently
+  in parallel once they're ready.  \nAnother feature is that the graph is dynamic
+  and any vertex could produce another vertice(s) to extend execution graph.\n"
+email: skorobogaty.dmitry@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/excadg.rb
+- lib/excadg/assertions.rb
+- lib/excadg/broker.rb
+- lib/excadg/data_store.rb
+- lib/excadg/dependency_manager.rb
+- lib/excadg/log.rb
+- lib/excadg/payload.rb
+- lib/excadg/payload/example.rb
+- lib/excadg/payload/wrapper.rb
+- lib/excadg/request.rb
+- lib/excadg/rtimeout.rb
+- lib/excadg/state_machine.rb
+- lib/excadg/tui.rb
+- lib/excadg/vertex.rb
+- lib/excadg/vstate_data.rb
+homepage: https://rubygems.org/gems/excadg
+licenses:
+- LGPL-3.0-only
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Execute Acyclic Directed Graph
+test_files: []