cache_box 0.0.1.pre.preview5 → 0.0.1.pre.preview10

data/lib/cache_box/helper/validate.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+class CacheBox
+  module Helper
+    # Common validation methods.
+    module Validate
+      # Input:
+      #
+      # arg  = String | Symbol
+      # name = String
+      #
+      # Output: arg
+      def validate_string_or_symbol!(arg, name)
+        return arg if arg.is_a?(Symbol) || arg.is_a?(String)
+
+        klass = arg.class
+        value = arg.inspect
+
+        raise(ArgumentError, "#{name} must be a Symbol or String, got #{klass}: #{value}")
+      end
+
+      # Input:
+      #
+      # args = Array[String | Symbol]
+      # name = String
+      #
+      # Output: args
+      def validate_array_of_string_or_symbol!(args, name)
+        unless args.is_a?(Array)
+          klass = args.class
+          value = args.inspect
+
+          raise(
+            ArgumentError,
+            "#{name} must be an Array, got #{klass}: #{value}"
+          )
+        end
+
+        args.each do |arg|
+          next if arg.is_a?(Symbol) || arg.is_a?(String)
+
+          klass = arg.class
+          value = arg.inspect
+
+          raise(
+            ArgumentError,
+            "#{name} must contain Symbol or String, got #{klass}: #{value} in #{args}"
+          )
+        end
+
+        args
+      end
+
+      # Input:
+      #
+      # block = &block
+      # name  = String
+      #
+      # Output: N/A
+      def validate_block_presence!(block, name)
+        return block if block
+
+        raise(ArgumentError, "The `#{name}` method requires a block")
+      end
+
+      # Input:
+      #
+      # edge = String |
+      #        Symbol |
+      #        Hash{1 String | Symbol => String | Symbol | Array[...String | Symbol]}
+      #
+      # Output: edge
+      def validate_edge!(edge)
+        return edge if edge.is_a?(Symbol) || edge.is_a?(String)
+
+        if edge.is_a?(Hash)
+          validate_hash_edge!(edge)
+
+          edge
+        else
+          klass = edge.class
+          value = edge.inspect
+
+          raise(
+            ArgumentError,
+            "edge has an unknown structure; #{klass}: #{value}"
+          )
+        end
+      end
+
+      private
+
+      # Input:
+      #
+      # edge = Hash{1 String | Symbol => String | Symbol | Array[...String | Symbol]}
+      #
+      # Output: edge
+      def validate_hash_edge!(edge)
+        if (size = edge.size) != 1
+          raise(
+            ArgumentError,
+            "edge must have one mapping, got #{size}: #{edge.inspect}"
+          )
+        end
+
+        name  = edge.keys.first
+        needs = edge[name]
+
+        validate_string_or_symbol!(name, 'edge name')
+        validate_needs!(needs)
+
+        edge
+      end
+
+      # Input:
+      #
+      # arg = String | Symbol | Array[...String | Symbol]
+      #
+      # Output: arg
+      def validate_needs!(arg)
+        return arg if arg.is_a?(Symbol) || arg.is_a?(String)
+
+        if arg.is_a?(Array)
+          validate_array_of_string_or_symbol!(arg, 'edge needs')
+
+          arg
+        else
+          klass = arg.class
+          value = arg.inspect
+
+          raise(
+            ArgumentError,
+            "edge needs has an unknown structure; #{klass}: #{value}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cache_box/scheduler/base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class CacheBox
+  module Scheduler
+    class Base
+      include CacheBox::Helper::Validate
+
+      # Input:
+      #
+      # logger = Logger
+      #
+      # Output: N/A
+      def initialize(logger: nil)
+        @logger = logger || Logger.new(STDOUT, level: Logger::INFO)
+
+        @lookup = {}
+        @needs  = {}
+        @feeds  = {}
+        @roots  = []
+        @leaves = []
+      end
+
+      # Input:
+      #
+      # edge = String |
+      #        Symbol |
+      #        Hash{String | Symbol => String | Symbol | Array[String | Symbol]}
+      #
+      # Output: self
+      def add(edge)
+        validate_edge!(edge)
+
+        needs_o = extract_needs(edge)
+        needs_s = needs_o.map(&:to_s)
+        needs_s.each_with_index do |arg, index|
+          next if @lookup.key?(arg)
+
+          raise(
+            ArgumentError,
+            "Graph does not contain required node #{needs_o[index].inspect}"
+          )
+        end
+
+        name_o = extract_name(edge)
+        name_s = name_o.to_s
+        if @lookup.key?(name_s)
+          raise(
+            ArgumentError,
+            "Graph already contains a node named #{name_o.inspect}"
+          )
+        end
+
+        @lookup[name_s] = name_o
+        @needs[name_s]  = needs_s
+
+        @leaves << name_s
+        needs_s.each do |need_s|
+          existing = @feeds[need_s]
+
+          @feeds[need_s] = existing ? existing << name_s : [name_s]
+          @leaves.delete(need_s)
+        end
+        @roots << name_s if needs_s == []
+
+        self
+      end
+
+      # Input:
+      #
+      # nodes = Hash{...String => Array[String | Symbol, Proc(Object)]}
+      # unit  = CacheBox::Unit
+      #
+      # Output: Hash{...String | Symbol => Object}
+      def run!(_nodes, _unit)
+        raise(
+          NotImplementedError,
+          'The `#run/2` method needs to be implemented in your subclass!'
+        )
+      end
+
+      private
+
+      # Input: String | Symbol | Hash[1 String | Symbol => Object]
+      #
+      # Output: String | Symbol
+      def extract_name(edge)
+        return edge.dup if edge.is_a?(Symbol) || edge.is_a?(String)
+
+        edge.keys.first.dup
+      end
+
+      # Input: ?
+      #
+      # Output: Array[...String | Symbol]
+      def extract_needs(edge)
+        return [] unless edge.is_a?(Hash)
+
+        name  = edge.keys.first
+        needs = edge[name]
+
+        if needs.is_a?(Array)
+          needs.map(&:dup)
+        else
+          [needs.dup]
+        end
+      end
+    end
+  end
+end

data/lib/cache_box/scheduler/concurrent.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+class CacheBox
+  module Scheduler
+    class Concurrent < Base
+
+      # TODO: write and use a thread pool
+
+      # Input:
+      #
+      # nodes = Hash{...String => Array[String | Symbol, Proc(Object)]}
+      # unit  = CacheBox::Unit
+      #
+      # Output: Hash{...String | Symbol => Object}
+      def run!(nodes, unit)
+        work    = @roots.dup
+        threads = []
+
+        condition = ConditionVariable.new
+
+        condition_lock = Mutex.new
+        scheduler_lock = Mutex.new
+
+        scheduler = Thread.new do
+          condition_lock.synchronize do
+            index = 0
+            loop do
+              stop = false
+
+              scheduler_lock.synchronize do
+                loop do
+                  break if index >= work.size
+
+                  name_s = work[index]
+                  thread = Thread.new do
+                    callable = nodes[name_s][1]
+                    needs    = @needs[name_s]
+                    input    = {}
+
+                    scheduler_lock.synchronize do
+                      needs.each do |need|
+                        next unless unit.has?(need)
+
+                        input[@lookup[need]] = unit.result(need)
+                      end
+                    end
+
+                    callable.call(input)
+
+                    scheduler_lock.synchronize do
+                      @feeds[name_s]&.each do |feed|
+                        work.push(feed) unless work.include?(feed)
+                      end
+
+                      threads.delete(Thread.current)
+                    end
+
+                    condition_lock.synchronize do
+                      condition.signal
+                    end
+                  end
+                  threads << thread
+
+                  index += 1
+                end
+
+                stop = true if threads.empty?
+              end
+
+              break if stop
+
+              condition.wait(condition_lock)
+            end
+          end
+        end
+
+        scheduler.join
+
+        result = {}
+        @leaves.each do |name_s|
+          next unless unit.has?(name_s)
+
+          result[@lookup[name_s]] = unit.result(name_s)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/cache_box/scheduler/serial.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+class CacheBox
+  module Scheduler
+    class Serial < Base
+      # Input:
+      #
+      # nodes = Hash{...String => Array[String | Symbol, Proc(Object)]}
+      # unit  = CacheBox::Unit
+      #
+      # Output: Hash{...String | Symbol => Object}
+      def run!(nodes, unit)
+        plan = @leaves.dup.reverse
+
+        plan_index = 0
+        loop do
+          name_s = plan[plan_index]
+
+          unless unit.has?(name_s)
+            needs = @needs[name_s]
+            needs.reverse_each { |need| plan << need }
+          end
+
+          plan_index += 1
+          break if plan_index >= plan.size
+        end
+
+        sequence = plan.reverse
+        sequence.each_with_index do |name_s, index|
+          next if unit.has?(name_s)
+
+          callable = nodes[name_s][1]
+          needs    = @needs[name_s]
+          input    = {}
+
+          needs.each do |need|
+            next unless unit.has?(need)
+
+            input[@lookup[need]] = unit.result(need)
+          end
+          callable.call(input)
+
+          needs.each do |need|
+            needed = false
+
+            sequence[(index + 1)..-1].each do |item|
+              needed = true if @needs[item].include?(need)
+            end
+
+            unit.clear(need) unless needed
+          end
+        end
+
+        result = {}
+        @leaves.each do |name_s|
+          next unless unit.has?(name_s)
+
+          result[@lookup[name_s]] = unit.result(name_s)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/cache_box/stash.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class CacheBox
+  # A thread safe, in memory, key value storage.
+  #
+  # The object itself is thread safe but it's contents is not.
+  class Stash
+    def initialize(state = nil)
+      @lock  = Mutex.new
+      @state = state || {}
+    end
+
+    def [](key)
+      @lock.synchronize do
+        @state[key]
+      end
+    end
+
+    def []=(key, value)
+      @lock.synchronize do
+        @state[key] = value
+      end
+    end
+
+    def delete(key)
+      @lock.synchronize do
+        @state.delete(key)
+      end
+    end
+
+    def key?(key)
+      @lock.synchronize do
+        @state.key?(key)
+      end
+    end
+
+    def with
+      @lock.synchronize do
+        yield(@state)
+      end
+    end
+  end
+end