service_skeleton 1.0.1 → 2.0.1

data/ultravisor/lib/ultravisor/child/call.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+class Ultravisor::Child::Call
+  attr_reader :method_name
+
+  def initialize(method_name, args, blk, rv_q, rv_fail)
+    @method_name, @args, @blk, @rv_q, @rv_fail = method_name, args, blk, rv_q, rv_fail
+  end
+
+  def go!(receiver)
+    @rv_q << receiver.__send__(@method_name, *@args, &@blk)
+  rescue Exception => ex
+    @rv_q << @rv_fail
+    raise
+  ensure
+    @rv_q.close
+  end
+
+  def child_restarted!
+    @rv_q << @rv_fail
+  end
+end

data/ultravisor/lib/ultravisor/child/call_receiver.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+class Ultravisor::Child::CallReceiver < BasicObject
+  def initialize(&blk)
+    @blk = blk
+  end
+
+  def method_missing(name, *args, &blk)
+    rv_q = ::Queue.new
+    rv_fail = ::Object.new
+    callback = ::Ultravisor::Child::Call.new(name, args, blk, rv_q, rv_fail)
+    @blk.call(callback)
+    rv_q.pop.tap { |rv| ::Kernel.raise ::Ultravisor::ChildRestartedError.new if rv == rv_fail }
+  end
+end

data/ultravisor/lib/ultravisor/child/cast.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+class Ultravisor::Child::Cast
+  attr_reader :method_name
+
+  def initialize(method_name, args, blk)
+    @method_name, @args, @blk = method_name, args, blk
+  end
+
+  def go!(receiver)
+    receiver.__send__(@method_name, *@args, &@blk)
+  end
+
+  def child_restarted!
+    # Meh
+  end
+end

data/ultravisor/lib/ultravisor/child/cast_receiver.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+class Ultravisor::Child::CastReceiver < BasicObject
+  def initialize(&blk)
+    @blk = blk
+  end
+
+  def method_missing(name, *args, &blk)
+    castback = ::Ultravisor::Child::Cast.new(name, args, blk)
+    @blk.call(castback)
+  end
+end

data/ultravisor/lib/ultravisor/child/process_cast_call.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+module Ultravisor::Child::ProcessCastCall
+  private
+
+  def process_castcall
+    begin
+      loop do
+        item = @ultravisor_child_castcall_queue.pop(true)
+
+        # Queue has been closed, which is a polite way of saying "we're done here"
+        return if item.nil?
+
+        item.go!(self)
+
+        castcall_fd.getc
+      end
+    rescue ThreadError => ex
+      if ex.message != "queue empty"
+        #:nocov:
+        raise
+        #:nocov:
+      end
+    end
+  end
+
+  def castcall_fd
+    @ultravisor_child_castcall_fd
+  end
+
+  def process_castcall_loop
+    #:nocov:
+    loop do
+      IO.select([castcall_fd], nil, nil)
+
+      process_castcall
+    end
+    #:nocov:
+  end
+end

data/ultravisor/lib/ultravisor/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+class Ultravisor
+  # Base class of all Ultravisor-specific errors
+  class Error < StandardError; end
+
+  # Tried to register a child with an ID of a child that already exists
+  class DuplicateChildError < Error; end
+
+  # Tried to call `#run` on an ultravisor that is already running
+  class AlreadyRunningError < Error; end
+
+  # A `child.call.<method>` was interrupted by the child instance runner terminating
+  class ChildRestartedError < Error; end
+
+  # Something was wrong with the Klass/Args/Method (KAM) passed
+  class InvalidKAMError < Error; end
+
+  # A child's restart policy was exceeded, and the Ultravisor should
+  # terminate
+  class BlownRestartPolicyError < Error; end
+
+  # An internal programming error (aka "a bug") caused a violation of thread safety
+  # requirements
+  class ThreadSafetyError < Error; end
+end

data/ultravisor/lib/ultravisor/logging_helpers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Ultravisor
+  module LoggingHelpers
+    private
+
+    attr_reader :logger
+
+    def log_exception(ex, progname = nil)
+      #:nocov:
+      progname ||= "#{self.class.to_s}##{caller_locations(2, 1).first.label}"
+
+      logger.error(progname) do
+        explanation = if block_given?
+          yield
+        else
+          false
+        end
+
+        (["#{explanation}#{explanation ? ": " : ""}#{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ")
+      end
+      #:nocov:
+    end
+
+    def logloc
+      #:nocov:
+      loc = caller_locations.first
+      "#{self.class}##{loc.label}"
+      #:nocov:
+    end
+  end
+end

data/ultravisor/spec/example_group_methods.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module ExampleGroupMethods
+  def uses_logger
+    let(:logger) { instance_double(Logger, 'mock') }
+
+    before(:each) do
+      allow(Logger).to receive(:new).and_return(logger)
+      allow(logger).to receive(:debug).with(instance_of(String))
+      allow(logger).to receive(:info).with(instance_of(String))
+      allow(logger).to receive(:error) { |p, &m| puts "#{p}: #{m.call}" }
+      allow(logger).to receive(:level=).with(Logger::INFO)
+      allow(logger).to receive(:formatter=).with(an_instance_of(Proc))
+      allow(logger).to receive(:kind_of?).with(Logger).and_return(true)
+    end
+  end
+end

data/ultravisor/spec/example_methods.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module ExampleMethods
+  def tmptrace
+    require "tracer"
+    Tracer.add_filter { |event, file, line, id, binding, klass, *rest| klass.to_s =~ /Ultravisor/ }
+    Tracer.on { yield }
+  end
+end

data/ultravisor/spec/spec_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require 'bundler'
+Bundler.setup(:default, :development)
+require 'rspec/core'
+require 'rspec/mocks'
+
+Thread.report_on_exception = false
+
+require 'simplecov'
+SimpleCov.start do
+  add_filter('spec')
+end
+
+class ListIncompletelyCoveredFiles
+  def format(result)
+    incompletes = result.files.select { |f| f.covered_percent < 100 }
+
+    unless incompletes.empty?
+      puts
+      puts "Files with incomplete test coverage:"
+      incompletes.each do |f|
+        printf "    %2.01f%%    %s\n", f.covered_percent, f.filename
+      end
+      puts; puts
+    end
+  end
+end
+
+SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
+  SimpleCov::Formatter::HTMLFormatter,
+  ListIncompletelyCoveredFiles
+])
+
+require_relative "./example_group_methods"
+require_relative "./example_methods"
+
+RSpec.configure do |config|
+  config.extend ExampleGroupMethods
+  config.include ExampleMethods
+
+  config.order = :random
+  config.fail_fast = !!ENV["RSPEC_CONFIG_FAIL_FAST"]
+  config.full_backtrace = !!ENV["RSPEC_CONFIG_FULL_BACKTRACE"]
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.after(:each) do
+    Thread.current.name = nil
+  end
+end

data/ultravisor/spec/ultravisor/add_child_spec.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+require_relative "../spec_helper"
+
+require_relative "../../lib/ultravisor"
+
+describe Ultravisor do
+  let(:args) { {} }
+  let(:ultravisor) { Ultravisor.new(**args) }
+  let!(:child) { Ultravisor::Child.new(id: :xtra, klass: Class, method: :to_s) }
+
+  describe "#add_child" do
+    before(:each) do
+      allow(Ultravisor::Child).to receive(:new).and_return(child)
+    end
+
+    context "when the ultravisor isn't running" do
+      it "creates a new Child object" do
+        expect(Ultravisor::Child).to receive(:new).with(id: :xtra, klass: Class, method: :to_s, logger: instance_of(Logger))
+
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+      end
+
+      it "registers the new child" do
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+
+        expect(ultravisor[:xtra]).to be_a(Ultravisor::Child)
+      end
+
+      it "explodes if a dupe child ID is used" do
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+
+        expect do
+          ultravisor.add_child(id: :xtra, klass: Object, method: :to_s)
+        end.to raise_error(Ultravisor::DuplicateChildError)
+      end
+
+      it "doesn't spawn a child thread" do
+        expect(child).to_not receive(:spawn)
+
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+      end
+    end
+
+    context "while the ultravisor *is* running" do
+      let(:mock_thread) { instance_double(Thread) }
+
+      before(:each) do
+        allow(child).to receive(:spawn)
+        ultravisor.instance_variable_set(:@running_thread, mock_thread)
+      end
+
+      it "creates a new Child object" do
+        expect(Ultravisor::Child).to receive(:new).with(id: :xtra, klass: Class, method: :to_s, logger: instance_of(Logger))
+
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+      end
+
+      it "registers the new child" do
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+
+        expect(ultravisor[:xtra]).to be_a(Ultravisor::Child)
+      end
+
+      it "explodes if a dupe child ID is used" do
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+
+        expect do
+          ultravisor.add_child(id: :xtra, klass: Object, method: :to_s)
+        end.to raise_error(Ultravisor::DuplicateChildError)
+      end
+
+      it "spawns a child thread" do
+        ultravisor.add_child(id: :xtra, klass: Class, method: :to_s)
+
+        expect(child).to have_received(:spawn)
+      end
+    end
+  end
+end

data/ultravisor/spec/ultravisor/child/call_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+require_relative "../../../lib/ultravisor/child"
+require_relative "../../../lib/ultravisor/error"
+
+class CastCallTest
+  class FakeError < RuntimeError; end
+
+  def run
+  end
+
+  def poke_processor
+    process_castcall
+  end
+
+  def failing_method
+    raise FakeError
+  end
+end
+
+describe Ultravisor::Child do
+  let(:child) { Ultravisor::Child.new(**args) }
+  let(:instance) { child.__send__(:new_instance) }
+
+  describe "#call" do
+    context "without enable_castcall" do
+      let(:args) do
+        {
+          id: :call_child,
+          klass: CastCallTest,
+          method: :run,
+        }
+      end
+
+      it "does not accept calls to #call" do
+        expect { child.call }.to raise_error(NoMethodError)
+      end
+    end
+
+    context "with enable_castcall" do
+      let(:args) do
+        {
+          id: :call_child,
+          klass: CastCallTest,
+          method: :run,
+          enable_castcall: true,
+        }
+      end
+
+      before(:each) do
+        # Got to have an instance otherwise all hell breaks loose
+        child.instance_variable_set(:@instance, instance)
+
+        # So we can check if and when it's been called
+        allow(instance).to receive(:to_s).and_call_original
+        allow(instance).to receive(:failing_method).and_call_original
+      end
+
+      it "accepts calls to #call" do
+        expect { child.call }.to_not raise_error
+      end
+
+      it "does not accept call calls to methods that do not exist on the worker object" do
+        expect { child.call.flibbetygibbets }.to raise_error(NoMethodError)
+      end
+
+      it "does not accept call calls to private methods on the worker object" do
+        expect { child.call.eval }.to raise_error(NoMethodError)
+      end
+
+      it "accepts calls to methods that exist on the worker object" do
+        th = Thread.new { child.call.to_s }
+        th.join(0.01)
+        instance.poke_processor
+        expect { th.value }.to_not raise_error
+      end
+
+      it "calls the instance method only when process_castcall is called" do
+        th = Thread.new { child.call.to_s }
+        th.join(0.001)
+
+        # Thread should be ticking along, not dead
+        expect(th.status).to eq("sleep")
+        expect(instance).to_not have_received(:to_s)
+        instance.poke_processor
+        expect(instance).to have_received(:to_s)
+        expect(th.value).to be_a(String)
+      end
+
+      it "raises a relevant error if the call itself causes an exception is dying" do
+        th = Thread.new { child.call.failing_method }
+        th.join(0.001)
+
+        expect(instance).to_not have_received(:failing_method)
+        expect { instance.poke_processor }.to raise_error(CastCallTest::FakeError)
+        expect(instance).to have_received(:failing_method)
+
+        expect { th.value }.to raise_error(Ultravisor::ChildRestartedError)
+      end
+
+      it "raises a relevant error if the instance is dying" do
+        instance.instance_variable_get(:@ultravisor_child_castcall_queue).close
+
+        expect { child.call.to_s }.to raise_error(Ultravisor::ChildRestartedError)
+      end
+
+      it "raises an error to all incomplete calls if the instance terminates" do
+        th = Thread.new { child.call.to_s }
+
+        th.join(0.001) until th.status == "sleep"
+
+        expect(instance).to_not have_received(:to_s)
+        child.instance_variable_get(:@spawn_m).synchronize { child.__send__(:termination_cleanup) }
+
+        expect { th.value }.to raise_error(Ultravisor::ChildRestartedError)
+      end
+    end
+  end
+end