zoidberg 0.0.1 → 0.1.0

data/lib/zoidberg/proxy.rb

@@ -0,0 +1,211 @@
+require 'zoidberg'
+
+module Zoidberg
+
+  # Instance proxy that filters requests to shelled instance
+  class Proxy < BasicObject
+
+    autoload :Confined, 'zoidberg/proxy/confined'
+    autoload :Liberated, 'zoidberg/proxy/liberated'
+
+    class << self
+      @@__registry = ::Hash.new
+
+      # @return [Hash] WeakRef -> Proxy mapping
+      def registry
+        @@__registry
+      end
+
+      # Register the proxy a WeakRef is pointing to
+      #
+      # @param r_id [Integer] object ID of WeakRef
+      # @param proxy [Zoidberg::Proxy] actual proxy instance
+      # @return [Zoidberg::Proxy]
+      def register(r_id, proxy)
+        @@__registry[r_id] = proxy
+      end
+
+      # Destroy the proxy referenced by the WeakRef with the provided
+      # ID
+      #
+      # @param o_id [Integer] Object ID
+      # @return [Truthy, Falsey]
+      def scrub!(o_id)
+        proxy = @@__registry.delete(o_id)
+        if(proxy)
+          proxy._zoidberg_destroy!
+        end
+      end
+    end
+
+    # Setup proxy for proper scrubbing support
+    def self.inherited(klass)
+      klass.class_eval do
+        # @return [Array] arguments used to build real instance
+        attr_accessor :_build_args
+        # @return [Object] wrapped instance
+        attr_reader :_raw_instance
+      end
+    end
+
+    # Abstract class gets no builder
+    def initialize(*_)
+      raise NotImplementedError
+    end
+
+    # @return [TrueClass, FalseClass] currently locked
+    def _zoidberg_locked?
+      false
+    end
+
+    # @return [TrueClass, FalseClass] currently unlocked
+    def _zoidberg_available?
+      !_zoidberg_locked?
+    end
+
+    # @return [Object]
+    def _zoidberg_link=(inst)
+      @_zoidberg_link = inst
+    end
+
+    # @return [Object, NilClass]
+    def _zoidberg_link
+      @_zoidberg_link
+    end
+
+    # Set an optional state signal instance
+    #
+    # @param signal [Signal]
+    # @return [Signal]
+    def _zoidberg_signal=(signal)
+      @_zoidberg_signal = signal
+    end
+
+    # Send a signal if the optional signal instance has been set
+    #
+    # @param sig [Symbol]
+    # @return [TrueClass, FalseClass] signal was sent
+    def _zoidberg_signal(sig)
+      if(@_zoidberg_signal)
+        @_zoidberg_signal.signal(sig)
+        true
+      else
+        false
+      end
+    end
+
+    # Properly handle an unexpected exception when encountered
+    #
+    # @param e [Exception]
+    def _zoidberg_unexpected_error(e)
+      ::Zoidberg.logger.error "Unexpected exception: #{e.class} - #{e}"
+      unless((defined?(Timeout) && e.is_a?(Timeout::Error)) || e.is_a?(::Zoidberg::DeadException))
+        if(_zoidberg_link)
+          if(_zoidberg_link.class.trap_exit)
+            ::Zoidberg.logger.warn "Calling linked exit trapper #{@_raw_instance.class.name} -> #{_zoidberg_link.class}: #{e.class} - #{e}"
+            _zoidberg_link.async.send(
+              _zoidberg_link.class.trap_exit, @_raw_instance, e
+            )
+          end
+        else
+          if(@_supervised)
+            ::Zoidberg.logger.warn "Unexpected error for supervised class `#{@_raw_instance.class.name}`. Handling error (#{e.class} - #{e})"
+            ::Zoidberg.logger.debug "#{e.class}: #{e}\n#{e.backtrace.join("\n")}"
+            _zoidberg_handle_unexpected_error(e)
+          end
+        end
+      end
+    end
+
+    # When real instance is being supervised, unexpected exceptions
+    # will force the real instance to be terminated and replaced with
+    # a fresh instance.
+    #
+    # If the real instance provides a #restart
+    # method that will be called instead of forcibly terminating the
+    # current real instance and rebuild a new instance.
+    #
+    # If the real instance provides a #restarted! method, that method
+    # will be called on the newly created instance on replacement
+    #
+    # @param error [Exception] exception that was caught
+    # @return [TrueClass]
+    def _zoidberg_handle_unexpected_error(error)
+      if(_raw_instance.respond_to?(:restart))
+        begin
+          _raw_instance.restart(error)
+          return # short circuit
+        rescue => e
+        end
+      end
+      _zoidberg_destroy!
+      _aquire_lock!
+      args = _build_args.dup
+      @_raw_instance = args.shift.unshelled_new(
+        *args.first,
+        &args.last
+      )
+      _raw_instance._zoidberg_proxy(self)
+      if(_raw_instance.respond_to?(:restarted!))
+        _raw_instance.restarted!
+      end
+      _release_lock!
+      true
+    end
+
+    # Destroy the real instance. Will update all methods on real
+    # instance to raise exceptions noting it as terminated rendering
+    # it unusable. This is generally used with the supervise module
+    # but can be used on its own if desired.
+    #
+    # @return [TrueClass]
+    def _zoidberg_destroy!(error=nil, &block)
+      unless(_raw_instance.respond_to?(:_zoidberg_destroyed))
+        if(_raw_instance.respond_to?(:terminate))
+          if(_raw_instance.method(:terminate).arity == 0)
+            _raw_instance.terminate
+          else
+            _raw_instance.terminate(error)
+          end
+        end
+        death_from_above = ::Proc.new do
+          ::Kernel.raise ::Zoidberg::DeadException.new('Instance in terminated state!')
+        end
+        death_from_above_display = ::Proc.new do
+          "#<#{self.class.name}:TERMINATED>"
+        end
+        block.call if block
+        _raw_instance.instance_variables.each do |i_var|
+          _raw_instance.remove_instance_variable(i_var)
+        end
+        (
+          _raw_instance.public_methods(false) +
+          _raw_instance.protected_methods(false) +
+          _raw_instance.private_methods(false)
+        ).each do |m_name|
+          next if m_name.to_sym == :alive?
+          _raw_instance.send(:define_singleton_method, m_name, &death_from_above)
+        end
+        _raw_instance.send(:define_singleton_method, :to_s, &death_from_above_display)
+        _raw_instance.send(:define_singleton_method, :inspect, &death_from_above_display)
+        _raw_instance.send(:define_singleton_method, :_zoidberg_destroyed, ::Proc.new{ true })
+        _zoidberg_signal(:destroyed)
+      end
+      true
+    end
+    alias_method :terminate, :_zoidberg_destroy!
+
+    # @return [self]
+    def _zoidberg_object
+      self
+    end
+
+  end
+end
+
+# jruby compat [https://github.com/jruby/jruby/pull/2520]
+if(Zoidberg::Proxy.instance_methods.include?(:object_id))
+  class Zoidberg::Proxy
+    undef_method :object_id
+  end
+end

data/lib/zoidberg/registry.rb

@@ -0,0 +1,7 @@
+require 'zoidberg'
+
+module Zoidberg
+  class Registry < Bogo::Smash
+    include Zoidberg::Shell
+  end
+end

data/lib/zoidberg/shell.rb

@@ -0,0 +1,354 @@
+require 'zoidberg'
+
+module Zoidberg
+
+  # Customized exception type used when instance has been terminated
+  class DeadException < RuntimeError; end
+
+  # Librated proxy based shell
+  module SoftShell
+
+    class AsyncProxy
+      attr_reader :target
+      def initialize(instance)
+        @target = instance
+      end
+      def method_missing(*args, &block)
+        target._zoidberg_thread(
+          Thread.new{
+            begin
+              target.send(*args, &block)
+            rescue Exception => e
+              target._zoidberg_proxy.send(:raise, e)
+            end
+          }
+        )
+        nil
+      end
+    end
+
+    # Unlock current lock on instance and execute given block
+    # without locking
+    #
+    # @yield block to execute without lock
+    # @return [Object] result of block
+    def defer
+      _zoidberg_proxy._release_lock!
+      begin
+        result = yield if block_given?
+        _zoidberg_proxy._aquire_lock!
+        result
+      rescue Exception => e
+        _zoidberg_proxy._aquire_lock!
+        raise e
+      end
+    end
+
+    # Perform an async action
+    #
+    # @param locked [Truthy, Falsey] lock when running
+    # @return [AsyncProxy, NilClass]
+    def async(locked=false, &block)
+      if(block_given?)
+        unless(locked)
+          thread = ::Thread.new do
+            self.instance_exec(&block)
+          end
+        else
+          thread = ::Thread.new{ current_self.instance_exec(&block) }
+        end
+        _zoidberg_thread(thread)
+        nil
+      else
+        ::Zoidberg::SoftShell::AsyncProxy.new(locked ? current_self : self)
+      end
+    end
+
+    # Register a running thread for this instance. Registered
+    # threads are tracked and killed on cleanup
+    #
+    # @param thread [Thread]
+    # @return [TrueClass]
+    def _zoidberg_thread(thread)
+      _zoidberg_proxy._raw_threads[self.object_id].push(thread)
+      true
+    end
+
+    # Provide a customized sleep behavior which will unlock the real
+    # instance while sleeping
+    #
+    # @param length [Numeric, NilClass]
+    # @return [Float]
+    def sleep(length=nil)
+      if(_zoidberg_proxy._locker == ::Thread.current)
+        defer do
+          start_time = ::Time.now.to_f
+          if(length)
+            ::Kernel.sleep(length)
+          else
+            ::Kernel.sleep
+          end
+          ::Time.now.to_f - start_time
+        end
+      else
+        start_time = ::Time.now.to_f
+        if(length)
+          ::Kernel.sleep(length)
+        else
+          ::Kernel.sleep
+        end
+        ::Time.now.to_f - start_time
+      end
+    end
+
+    def self.included(klass)
+      unless(klass.include?(::Zoidberg::Shell))
+        klass.class_eval do
+          include ::Zoidberg::Shell
+        end
+      end
+    end
+
+  end
+
+  # Confined proxy based shell
+  module HardShell
+
+    class AsyncProxy
+      attr_reader :target, :locked
+      def initialize(instance, locked)
+        @target = instance
+        @locked = locked
+      end
+      def method_missing(*args, &block)
+        target._async_request(locked ? :blocking : :nonblocking, *args, &block)
+        nil
+      end
+    end
+
+    # Unlock current lock on instance and execute given block
+    # without locking
+    #
+    # @yield block to execute without lock
+    # @return [Object] result of block
+    def defer(&block)
+      Fiber.yield
+      if(block)
+        ::Fiber.new(&block).resume
+      end
+    end
+
+    # Perform an async action
+    #
+    # @param locked [Truthy, Falsey] lock when running
+    # @return [AsyncProxy, NilClass]
+    def async(locked=false, &block)
+      if(block)
+        if(locked)
+          current_self.instance_exec(&block)
+        else
+          current_self._async_request(locked ? :blocking : :nonblocking, :instance_exec, &block)
+        end
+      else
+        ::Zoidberg::HardShell::AsyncProxy.new(current_self, locked)
+      end
+    end
+
+    # Provide a customized sleep behavior which will unlock the real
+    # instance while sleeping
+    #
+    # @param length [Numeric, NilClass]
+    # @return [Float]
+    def sleep(length=nil)
+      start_time = ::Time.now.to_f
+      if(length)
+        ::Kernel.sleep(length)
+      else
+        ::Thread.current[:root_fiber] == ::Fiber.current ? ::Kernel.sleep : ::Fiber.yield
+      end
+      ::Time.now.to_f - start_time
+    end
+
+    def self.included(klass)
+      unless(klass.include?(::Zoidberg::Shell))
+        klass.class_eval do
+          include ::Zoidberg::Shell
+        end
+      end
+    end
+
+  end
+
+  # Provides a wrapping around a real instance. Including this module
+  # within a class will enable magic.
+  module Shell
+
+    module InstanceMethods
+
+      # Initialize the signal instance if not
+      def _zoidberg_signal_interface
+        unless(@_zoidberg_signal)
+          @_zoidberg_signal = ::Zoidberg::Signal.new(:cache_signals => self.class.option?(:cache_signals))
+        end
+        @_zoidberg_signal
+      end
+
+      # @return [Timer]
+      def timer
+        unless(@_zoidberg_timer)
+          @_zoidberg_timer = Timer.new
+        end
+        @_zoidberg_timer
+      end
+
+      # Register a recurring action
+      #
+      # @param interval [Numeric]
+      # @yield action to run
+      # @return [Timer]
+      def every(interval, &block)
+        timer.every(interval, &block)
+      end
+
+      # Register an action to run after interval
+      #
+      # @param interval [Numeric]
+      # @yield action to run
+      # @return [Timer]
+      def after(interval, &block)
+        timer.after(interval, &block)
+      end
+
+      # Send a signal to single waiter
+      #
+      # @param name [String, Symbol] name of signal
+      # @param arg [Object] optional argument to transmit
+      # @return [TrueClass, FalseClass]
+      def signal(name, arg=nil)
+        current_self._zoidberg_signal_interface.signal(*[name, arg].compact)
+      end
+
+      # Broadcast a signal to all waiters
+      # @param name [String, Symbol] name of signal
+      # @param arg [Object] optional argument to transmit
+      # @return [TrueClass, FalseClass]
+      def broadcast(name, arg=nil)
+        current_self._zoidberg_signal_interface.broadcast(*[name, arg].compact)
+      end
+
+      # Wait for a given signal
+      #
+      # @param name [String, Symbol] name of signal
+      # @return [Object]
+      def wait_for(name)
+        defer{ current_self._zoidberg_signal_interface.wait_for(name) }
+      end
+      alias_method :wait, :wait_for
+
+      # @return [TrueClass, FalseClass]
+      def alive?
+        !respond_to?(:_zoidberg_destroyed)
+      end
+
+      # Provide access to the proxy instance from the real instance
+      #
+      # @param oxy [Zoidberg::Proxy]
+      # @return [NilClass, Zoidberg::Proxy]
+      def _zoidberg_proxy(oxy=nil)
+        if(oxy)
+          @_zoidberg_proxy = oxy
+        end
+        @_zoidberg_proxy
+      end
+      alias_method :current_self, :_zoidberg_proxy
+      alias_method :current_actor, :_zoidberg_proxy
+
+      # Link given shelled instance to current shelled instance to
+      # handle any exceptions raised from async actions
+      #
+      # @param inst [Object]
+      # @return [TrueClass]
+      def link(inst)
+        inst._zoidberg_link = current_self
+        true
+      end
+
+    end
+
+    module ClassMethods
+
+      # Override real instance's .new method to provide a proxy instance
+      def new(*args, &block)
+        if(self.include?(Zoidberg::HardShell))
+          proxy = Zoidberg::Proxy::Confined.new(self, *args, &block)
+        elsif(self.include?(Zoidberg::SoftShell))
+          proxy = Zoidberg::Proxy::Liberated.new(self, *args, &block)
+        else
+          raise TypeError.new "Unable to determine `Shell` type for this class `#{self}`!"
+        end
+        weak_ref = Zoidberg::WeakRef.new(proxy)
+        Zoidberg::Proxy.register(weak_ref.__id__, proxy)
+        ObjectSpace.define_finalizer(weak_ref, Zoidberg::Proxy.method(:scrub!))
+        weak_ref
+      end
+
+      # Trap unhandled exceptions from linked instances and handle via
+      # given method name
+      #
+      # @param m_name [String, Symbol] method handler name
+      # @return [String, Symbol]
+      def trap_exit(m_name=nil)
+        if(m_name)
+          @m_name = m_name
+        end
+        @m_name
+      end
+
+    end
+
+    # Inject Shell magic into given class when included
+    #
+    # @param klass [Class]
+    def self.included(klass)
+      unless(klass.ancestors.include?(Zoidberg::Shell::InstanceMethods))
+        klass.class_eval do
+
+          class << self
+            alias_method :unshelled_new, :new
+
+            # Set an option or multiple options
+            #
+            # @return [Array<Symbol>]
+            def option(*args)
+              @option ||= []
+              unless(args.empty?)
+                @option += args
+                @option.map!(&:to_sym).uniq!
+              end
+              @option
+            end
+
+            # Check if option is available
+            #
+            # @param arg [Symbol]
+            # @return [TrueClass, FalseClass]
+            def option?(arg)
+              option.include?(arg.to_sym)
+            end
+
+          end
+
+          include InstanceMethods
+          extend ClassMethods
+          include Bogo::Memoization
+        end
+      end
+      unless(klass.include?(SoftShell) || klass.include?(HardShell))
+        klass.class_eval do
+          include Zoidberg.default_shell
+        end
+      end
+    end
+
+  end
+end

data/lib/zoidberg/signal.rb

@@ -0,0 +1,109 @@
+require 'thread'
+require 'zoidberg'
+
+module Zoidberg
+  # Wait/send signals
+  class Signal
+
+    # empty value when no object is provided
+    EMPTY_VALUE = :_zoidberg_empty_
+
+    include SoftShell
+
+    # @return [Smash] meta information on current waiters
+    attr_reader :waiters
+    # @return [TrueClass, FalseClass]
+    attr_reader :cache_signals
+
+    # Create a new instance for sending and receiving signals
+    #
+    # @param args [Hash] options
+    # @return [self]
+    def initialize(args={})
+      @cache_signals = args.fetch(:cache_signals, false)
+      @waiters = Smash.new
+    end
+
+    # Set cache behavior
+    #
+    # @param arg [TrueClass, FalseClass] set behavior
+    # @return [TrueClass, FalseClass] behavior
+    def cache_signals(arg=nil)
+      unless(arg.nil?)
+        @cache_signals = !!arg
+      end
+      @cache_signals
+    end
+
+    # Send a signal to _one_ waiter
+    #
+    # @param signal [Symbol] name of signal
+    # @param obj [Object] optional Object to send
+    # @return [TrueClass, FalseClass] if signal was sent
+    def signal(signal, obj=EMPTY_VALUE)
+      if(signal_init(signal, :signal))
+        waiters[signal][:queue].push obj
+        true
+      else
+        false
+      end
+    end
+
+    # Send a signal to _all_ waiters
+    #
+    # @param signal [Symbol] name of signal
+    # @param obj [Object] optional Object to send
+    # @return [TrueClass, FalseClass] if signal(s) was/were sent
+    def broadcast(signal, obj=EMPTY_VALUE)
+      if(signal_init(signal, :signal))
+        num = waiters[signal][:threads].size
+        num = 1 if num < 1
+        num.times do
+          waiters[signal][:queue].push obj
+        end
+        true
+      else
+        false
+      end
+    end
+
+    # Wait for a signal
+    #
+    # @param signal [Symbol] name of signal
+    # @return [Float] number of seconds waiting for signal
+    def wait_for(signal)
+      signal_init(signal, :wait)
+      start_sleep = Time.now.to_f
+      waiters[signal][:threads].push(Thread.current)
+      val = defer{ waiters[signal][:queue].pop }
+      waiters[signal][:threads].delete(Thread.current)
+      val == EMPTY_VALUE ? (Time.now.to_f - start_sleep) : val
+    end
+
+    protected
+
+    # Initialize the signal structure data
+    #
+    # @param name [String, Symbol] name of signal
+    # @param origin [String] origin of init
+    # @return [TrueClass, FalseClass]
+    def signal_init(name, origin)
+      if(waiters[name])
+        cache_signals ||
+          origin == :wait ||
+          (origin == :signal && !waiters[name][:threads].empty?)
+      else
+        if(origin == :wait || (origin == :signal && cache_signals))
+          waiters[name] = Smash.new(
+            :queue => Queue.new,
+            :threads => []
+          )
+          true
+        else
+          false
+        end
+      end
+    end
+
+  end
+end

data/lib/zoidberg/supervise.rb

@@ -0,0 +1,41 @@
+require 'zoidberg'
+
+module Zoidberg
+  # Add supervision to instance
+  module Supervise
+    # Customized exception type to wrap allowed errors
+    class AbortException < StandardError
+      attr_accessor :original_exception
+    end
+
+    module InstanceMethods
+
+      # Customized method for raising exceptions that have been
+      # properly handled (preventing termination)
+      #
+      # @param e [Exception]
+      # @raises [AbortException]
+      def abort(e)
+        new_e = ::Zoidberg::Supervise::AbortException.new
+        new_e.original_exception = e
+        ::Kernel.raise new_e
+      end
+
+    end
+
+    # Include supervision into given class when included
+    #
+    # @param klass [Class]
+    def self.included(klass)
+      unless(klass.include?(Zoidberg::Shell))
+        klass.class_eval{ include Zoidberg::Shell }
+      end
+      unless(klass.include?(Zoidberg::Supervise::InstanceMethods))
+        klass.class_eval do
+          include InstanceMethods
+        end
+      end
+    end
+
+  end
+end