eventbox 0.1.0 → 1.0.1

data/lib/eventbox/sanitizer.rb

@@ -18,18 +18,18 @@ class Eventbox
   #
   # In detail this works as following.
   # Objects which are passed through unchanged are:
-  # * {Eventbox}, {Eventbox::Action} and `Module` objects
+  # * {Eventbox}, {Eventbox::Action} and +Module+ objects
   # * Proc objects created by {Eventbox#async_proc}, {Eventbox#sync_proc} and {Eventbox#yield_proc}
   #
   # The following rules apply for wrapping/unwrapping:
-  # * If the object has been marked as {Eventbox#shared_object}, it is wrapped as {WrappedObject} depending on the direction of the data flow (return value or call argument).
+  # * If the object has been marked as {Eventbox#shared_object}, it is wrapped as {WrappedObject} or {ExternalObject} depending on the direction of the data flow (return value or call argument).
   # * If the object is a {WrappedObject} or {ExternalProc} and fits to the target scope, it is unwrapped.
   # Both cases even work if the object is encapsulated by another object.
   #
   # In all other cases the following rules apply:
-  # * If the object is marshalable, it is passed as a deep copy through `Marshal.dump` and `Marshal.load` .
-  # * An object which failed to marshal as a whole is tried to be dissected and values are sanitized recursively.
-  # * If the object can't be marshaled or dissected, it is wrapped as {WrappedObject}.
+  # * If the object is marshalable, it is passed as a deep copy through +Marshal.dump+ and +Marshal.load+ .
+  # * An object which failed to marshal as a whole is tried to be dissected and values are sanitized separately and recursively.
+  # * If the object can't be marshaled or dissected, it is wrapped as {ExternalObject} when passed from external scope to event scope and wrapped as {WrappedObject} when passed from the event scope.
   #   They are unwrapped when passed back to origin scope.
   # * Proc objects passed from event scope to external are wrapped as {WrappedObject}.
   #   They are unwrapped when passed back to event scope.
@@ -46,24 +46,25 @@ class Eventbox
       # Separate the instance variables from the object
       ivns = arg.instance_variables
       ivvs = ivns.map do |ivn|
-        arg.instance_variable_get(ivn)
-      end
-
-      # Temporary set all instance variables to nil
-      ivns.each do |ivn|
+        ivv = arg.instance_variable_get(ivn)
+        # Temporary set all instance variables to nil
         arg.instance_variable_set(ivn, nil)
+        ivv
       end
 
       # Copy the object
       arg2 = yield(arg)
-
-      # Restore the original object
+    rescue
+      # Restore the original object in case of Marshal.dump failure
       ivns.each_with_index do |ivn, ivni|
         arg.instance_variable_set(ivn, ivvs[ivni])
       end
-
-      # sanitize instance variables independently and write them to the copied object
+      raise
+    else
       ivns.each_with_index do |ivn, ivni|
+        # Restore the original object
+        arg.instance_variable_set(ivn, ivvs[ivni])
+        # sanitize instance variables independently and write them to the copied object
         ivv = sanitize_value(ivvs[ivni], source_event_loop, target_event_loop, ivn)
         arg2.instance_variable_set(ivn, ivv)
       end
@@ -81,12 +82,15 @@ class Eventbox
       end
 
       arg2 = yield(arg)
-
+    rescue
+      # Restore the original object in case of Marshal.dump failure
       ms.each_with_index do |m, i|
         arg[m] = vs[i]
       end
-
+      raise
+    else
       ms.each_with_index do |m, i|
+        arg[m] = vs[i]
         v2 = sanitize_value(vs[i], source_event_loop, target_event_loop, m)
         arg2[m] = v2
       end
@@ -102,12 +106,15 @@ class Eventbox
       end
 
       arg2 = yield(arg)
-
+    rescue
+      # Restore the original object in case of Marshal.dump failure
       h.each do |k, v|
         arg[k] = v
       end
-
+      raise
+    else
       h.each do |k, v|
+        arg[k] = v
         arg2[k] = sanitize_value(v, source_event_loop, target_event_loop, k)
       end
 
@@ -122,12 +129,15 @@ class Eventbox
       end
 
       arg2 = yield(arg)
-
-      vs.each_index do |i|
+    rescue
+      # Restore the original object in case of Marshal.dump failure
+      vs.each_with_index do |v, i|
         arg[i] = vs[i]
       end
-
+      raise
+    else
       vs.each_with_index do |v, i|
+        arg[i] = vs[i]
         v2 = sanitize_value(v, source_event_loop, target_event_loop, name)
         arg2[i] = v2
       end
@@ -158,9 +168,9 @@ class Eventbox
           unless mel == source_event_loop
             raise InvalidAccess, "object #{arg.inspect} #{"wrapped by #{name} " if name} was marked as shared_object in a different eventbox object than the calling eventbox"
           end
-          WrappedObject.new(arg, mel, name)
+          wrap_object(arg, mel, target_event_loop, name)
         when ExternalSharedObject # External object marked as shared_object
-          WrappedObject.new(arg, source_event_loop, name)
+          wrap_object(arg, source_event_loop, target_event_loop, name)
         else
           # Not tagged -> try to deep copy the object
           begin
@@ -219,16 +229,23 @@ class Eventbox
       args.map { |arg| sanitize_value(arg, source_event_loop, target_event_loop, name) }
     end
 
+    def sanitize_kwargs(args, source_event_loop, target_event_loop, name=nil)
+      args.transform_values { |arg| sanitize_value(arg, source_event_loop, target_event_loop, name) }
+    end
+
     def wrap_proc(arg, name, source_event_loop, target_event_loop)
       if target_event_loop&.event_scope?
-        ExternalProc.new(arg, source_event_loop, name) do |*args, &block|
+        ExternalProc.new(arg, source_event_loop, name) do |*args, **kwargs, &block|
           if target_event_loop&.event_scope?
             # called in the event scope
+
             if block && !(WrappedProc === block)
               raise InvalidAccess, "calling #{arg.inspect} with block argument #{block.inspect} is not allowed - use async_proc, sync_proc, yield_proc or an external proc instead"
             end
-            cbblock = args.last if Proc === args.last
-            target_event_loop._external_proc_call(arg, name, args, block, cbblock, source_event_loop)
+
+            call_context = args.shift if CallContext === args.first
+            cbblock = args.pop if Proc === args.last
+            target_event_loop._external_object_call(arg, :call, name, args, kwargs, block, cbblock, source_event_loop, call_context)
           else
             # called externally
             raise InvalidAccess, "external proc #{arg.inspect} #{"wrapped by #{name} " if name} can not be called in a different eventbox instance"
@@ -238,6 +255,14 @@ class Eventbox
         WrappedObject.new(arg, source_event_loop, name)
       end
     end
+
+    def wrap_object(object, source_event_loop, target_event_loop, name)
+      if target_event_loop&.event_scope?
+        ExternalObject.new(object, source_event_loop, target_event_loop, name)
+      else
+        WrappedObject.new(object, source_event_loop, name)
+      end
+    end
   end
 
   # Generic wrapper for objects that are passed through a foreign scope as reference.
@@ -245,19 +270,87 @@ class Eventbox
   # Access to the object from a different scope is denied, but the wrapper object can be stored and passed back to the origin scope to unwrap it.
   class WrappedObject
     attr_reader :name
+    # @private
     def initialize(object, event_loop, name=nil)
-      @object = object
-      @event_loop = event_loop
-      @name = name
+      @object = object # the object to be wrapped
+      @event_loop = event_loop # the event_loop @object originates from, nil if external scope
+      @name = name # some information to get more meaningful error messages
       @dont_marshal = ExternalSharedObject # protect self from being marshaled
     end
 
+    # @private
     def object_for(target_event_loop)
       @event_loop == target_event_loop ? @object : self
     end
 
     def inspect
-      "#<#{self.class} @object=#{@object.inspect} @name=#{@name.inspect}>"
+      el = case @event_loop
+        when EventLoop then @event_loop.object_id.to_s(16)
+        else @event_loop.inspect
+      end
+      "#<#{self.class} @object=#{@object.inspect} @name=#{@name.inspect} @event_loop=#{el}>"
+    end
+  end
+
+  # Wrapper for objects created external or in the action scope of some Eventbox instance.
+  #
+  # External objects can be called from event scope by {ExternalObject#send}.
+  #
+  # External objects can also be passed to action or to external scope.
+  # In this case a {ExternalObject} is unwrapped back to the ordinary object.
+  #
+  # @see ExternalProc
+  class ExternalObject < WrappedObject
+    # @private
+    def initialize(object, event_loop, target_event_loop, name=nil)
+      super(object, event_loop, name)
+      @target_event_loop = target_event_loop
+    end
+
+    # Invoke the external objects within the event scope.
+    #
+    # It can be called within {Eventbox::Boxable#sync_call sync_call} and {Eventbox::Boxable#yield_call yield_call} methods and from {Eventbox#sync_proc} and {Eventbox#yield_proc} closures.
+    # The method then runs in the background on the thread that called the event scope method in execution.
+    #
+    # It's also possible to invoke the external object with an explicit {Eventbox::CallContext} instead of the implicit call context of a sync or yield call.
+    # The explicit {Eventbox::CallContext} must be given as the very first parameter and it is not passed to the object call.
+    # The object call is then done in the given context of an arbitrary event scope method or closure that didn't return yet.
+    # In this case the method runs in the background on the thread that is waiting for the call to return.
+    #
+    # If the call to the external object doesn't return immediately, it blocks the calling thread or the thread of the {Eventbox::CallContext}.
+    # If this is not desired, an {Eventbox::Boxable#action action} can be used instead, to invoke the method of the object on a dedicated thread.
+    # However in any case calling the external object doesn't block the Eventbox instance itself.
+    # It still keeps responsive to calls from other threads.
+    #
+    # Optionally a proc can be provided as the last argument which acts as a completion callback.
+    # This proc is invoked, when the call has finished, with the result value as argument.
+    #
+    #   class Sender < Eventbox
+    #     sync_call def init(€obj)  # €-variables are passed as reference instead of copy
+    #       # invoke the object given to Sender.new
+    #       # and when completed, print the result of strip
+    #       €obj.send :strip, ->(res){ p res }
+    #     end
+    #   end
+    #   Sender.new(" a b c ")    # Output: "a b c"
+    def send(method, *args, **kwargs, &block)
+      if @target_event_loop&.event_scope?
+        # called in the event scope
+        if CallContext === method
+          call_context = method
+          method = args.shift
+        end
+
+        if block && !(WrappedProc === block)
+          raise InvalidAccess, "calling `#{method}' with block argument #{block.inspect} is not allowed - use async_proc, sync_proc, yield_proc or an external proc instead"
+        end
+
+        cbblock = args.pop if Proc === args.last
+        @target_event_loop._external_object_call(@object, method, @name, args, kwargs, block, cbblock, @event_loop, call_context)
+      else
+        # called externally
+        raise InvalidAccess, "external object #{self.inspect} #{"wrapped by #{name} " if name} can not be called in a different eventbox instance"
+      end
     end
   end
 
@@ -283,9 +376,21 @@ class Eventbox
 
   WrappedException = Struct.new(:exc)
 
-  # Proc object provided as the last argument of {Eventbox.yield_call} and {Eventbox#yield_proc}.
+  # Proc object provided as the last argument of {Eventbox::Boxable#yield_call yield_call} and {Eventbox#yield_proc}.
+  #
+  # Used to let the corresponding yield call return a value:
+  #   class MyBox < Eventbox
+  #     yield_call def number(result)
+  #       result.yield 42
+  #     end
+  #   end
+  #   MyBox.new.number   # => 42
+  #
+  # Alternatively the yield call can respond with an exception by {CompletionProc#raise}.
   class CompletionProc < AsyncProc
-    # Raise an exception in the context of the waiting {Eventbox.yield_call} or {Eventbox#yield_proc} method.
+    include CallContext
+
+    # Raise an exception in the context of the waiting {Eventbox::Boxable#yield_call yield_call} or {Eventbox#yield_proc} method.
     #
     # This allows to raise an exception to the calling scope from external or action scope:
     #
@@ -300,38 +405,49 @@ class Eventbox
     #   end
     #   MyBox.new   # => raises RuntimeError (raise from action MyBox#process)
     #
-    # In contrast to a direct call of `Kernel.raise`, calling this method doesn't abort the current context.
+    # In contrast to a direct call of +Kernel.raise+, calling this method doesn't abort the current context.
     # Instead when in the event scope, raising the exception is deferred until returning to the calling external or action scope.
     def raise(*args)
       self.call(WrappedException.new(args))
     end
   end
 
-  # Wrapper for Proc objects created external of some Eventbox instance.
+  # Wrapper for Proc objects created external or in the action scope of some Eventbox instance.
+  #
+  # External Proc objects can be invoked from event scope by {ExternalProc#call}.
+  # It can be called within {Eventbox::Boxable#sync_call sync_call} and {Eventbox::Boxable#yield_call yield_call} methods and from {Eventbox#sync_proc} and {Eventbox#yield_proc} closures.
+  # The proc then runs in the background on the thread that called the event scope method in execution.
+  #
+  # It's also possible to invoke it within a {Eventbox::Boxable#async_call async_call} or {Eventbox#async_proc}, when the method or proc that brought the external proc into the event scope, is a yield call that didn't return yet.
+  # In this case the proc runs in the background on the thread that is waiting for the yield call to return.
   #
-  # External Proc objects can be invoked from event scope through {Eventbox.sync_call} and {Eventbox.yield_call} methods.
   # Optionally a proc can be provided as the last argument which acts as a completion callback.
   # This proc is invoked, when the call has finished, with the result value as argument.
   #
   #   class Callback < Eventbox
   #     sync_call def init(&block)
-  #       block.call(5, proc do |res|  # invoke the block given to Callback.new
-  #         p res                      # print the block result (5 + 1)
-  #       end)
+  #       # invoke the block given to Callback.new
+  #       # and when completed, print the result of the block
+  #       block.call 5, ->(res){ p res }
   #     end
   #   end
   #   Callback.new {|num| num + 1 }    # Output: 6
   #
   # External Proc objects can also be passed to action or to external scope.
-  # In this case a {ExternalProc} is unwrapped back to an ordinary Proc object.
+  # In this case a {ExternalProc} is unwrapped back to the ordinary Proc object.
+  #
+  # @see ExternalObject
   class ExternalProc < WrappedProc
+    # @private
     attr_reader :name
+    # @private
     def initialize(object, event_loop, name=nil)
       @object = object
       @event_loop = event_loop
       @name = name
     end
 
+    # @private
     def object_for(target_event_loop)
       @event_loop == target_event_loop ? @object : self
     end

data/lib/eventbox/thread_pool.rb

@@ -68,6 +68,10 @@ class Eventbox
         end
       end
 
+      async_call def terminate
+        @action.abort
+      end
+
       # @private
       async_call def __start__(action, input)
         # Send the block to the start_pool_thread as result of next_job
@@ -120,6 +124,8 @@ class Eventbox
             Thread.handle_interrupt(Exception => :immediate) do
               sleep # Aborted by the exception
             end
+          rescue Eventbox::AbortAction
+            raise # The thread-pool was requested to shutdown
           rescue Exception
           end
         end
@@ -166,5 +172,9 @@ class Eventbox
     private async_call def gc_finished
       @run_gc_when_busy = true
     end
+
+    def inspect
+      "#<#{self.class}:#{self.object_id} @requests=#{@requests.length} @jobless=#{@jobless.length} @run_gc_when_busy=#{@run_gc_when_busy.inspect}>"
+    end
   end
 end

data/lib/eventbox/timer.rb

@@ -9,28 +9,36 @@ class Eventbox
   #     include Eventbox::Timer
   #
   #     async_call def init
-  #       super   # make sure Timer#init is called
+  #       super     # Make sure Timer#init is called
   #       timer_after(1) do
   #         puts "one second elapsed"
   #       end
   #     end
   #   end
   #
+  #   MyBox.new     # Schedule the alarm after 1 sec
+  #   sleep 2       # Wait for the timer to be triggered
+  #
   # The main functions are timer_after and timer_every.
   # They schedule asynchronous calls to the given block:
-  #   timer_after(3) do
+  #   timer_after(3.0) do
   #     # executed once after 3 seconds
   #   end
   #
-  #   timer_every(3) do
-  #     # executed repeatedly every 3 seconds
+  #   timer_every(1.5) do
+  #     # executed repeatedly every 1.5 seconds
   #   end
   #
-  # Both functions return an Alarm object which can be used to cancel the alarm through timer_cancel.
+  # Both functions return an {Alarm} object which can be used to cancel the alarm through {timer_cancel}.
   #
-  # timer_after, timer_every and timer_cancel can be used within the event scope, in actions and from external scope.
+  # {Timer} always uses one {Eventbox::Boxable#action action} thread per Eventbox object, regardless of the number of scheduled timers.
+  # All alarms are called from this thread.
+  # {timer_after}, {timer_every} and {timer_cancel} can be used within the {file:README.md#event-scope event scope}, in actions and from external scope.
+  # Alarms defined within the event scope must be non-blocking, as any other code in the event scope.
+  # Alarms defined in action or external scope should also avoid blocking code, otherwise one alarm can delay the next alarm.
   #
-  # {Timer} always uses one action thread per Eventbox object, regardless of the number of scheduled timers.
+  # *Note:* Each object that includes the {Timer} module must be explicit terminated by {Eventbox#shutdown!}.
+  # It is (currently) not freed by the garbarge collector.
   module Timer
     class Reload < RuntimeError
     end
@@ -124,6 +132,8 @@ class Eventbox
     end
 
     # Cancel an alarm previously scheduled per timer_after or timer_every
+    #
+    # The method does nothing, if the alarm is no longer active.
     async_call def timer_cancel(alarm)
       a = @timer_alarms.delete(alarm)
       if a

data/lib/eventbox/version.rb

@@ -1,5 +1,5 @@
 # frozen-string-literal: true
 
 class Eventbox
-  VERSION = "0.1.0"
+  VERSION = "1.0.1"
 end

data/lib/eventbox.rb

@@ -2,10 +2,11 @@
 
 require "weakref"
 require "eventbox/argument_wrapper"
-require "eventbox/sanitizer"
+require "eventbox/call_context"
 require "eventbox/boxable"
 require "eventbox/event_loop"
 require "eventbox/object_registry"
+require "eventbox/sanitizer"
 
 class Eventbox
   autoload :VERSION, "eventbox/version"
@@ -18,7 +19,7 @@ class Eventbox
   class MultipleResults < RuntimeError; end
   class AbortAction < RuntimeError; end
 
-  if RUBY_ENGINE=='jruby' && RUBY_VERSION.split(".").map(&:to_i).pack("C*") < [9,2,1,0].pack("C*") ||
+  if RUBY_ENGINE=='jruby' && JRUBY_VERSION.split(".").map(&:to_i).pack("C*") < [9,2,1,0].pack("C*") ||
       RUBY_ENGINE=='truffleruby'
     # This is a workaround for bug https://github.com/jruby/jruby/issues/5314
     # which was fixed in JRuby-9.2.1.0.
@@ -90,7 +91,7 @@ class Eventbox
   # Create a new {Eventbox} instance.
   #
   # All arguments are passed to the init() method when defined.
-  def initialize(*args, &block)
+  def initialize(*args, **kwargs, &block)
     options = self.class.eventbox_options
 
     # This instance variable is set to self here, but replaced by Boxable#action to a WeakRef
@@ -104,7 +105,7 @@ class Eventbox
       self.class.instance_variable_set(:@eventbox_methods_checked, true)
 
       obj = Object.new
-      meths = methods - obj.methods - [:__getobj__, :shutdown!, :shared_object]
+      meths = methods - obj.methods - [:__getobj__, :shutdown!, :shared_object, :€]
       prmeths = private_methods - obj.private_methods
       prohib = meths.find do |name|
         !prmeths.include?(:"__#{name}__")
@@ -120,7 +121,7 @@ class Eventbox
     @__event_loop__ = EventLoop.new(options[:threadpool], options[:guard_time])
     ObjectSpace.define_finalizer(self, @__event_loop__.method(:send_shutdown))
 
-    init(*args, &block)
+    init(*args, **kwargs, &block)
   end
 
   def self.method_added(name)
@@ -240,19 +241,70 @@ class Eventbox
   # Mark an object as to be shared instead of copied.
   #
   # A marked object is never passed as copy, but passed as reference.
-  # The object is therefore wrapped as {WrappedObject} when used in an unsafe scope.
-  # Wrapping as {WrappedObject} denies access from external/action scope to event scope objects and vice versa.
-  # It also denies access to objects originated from a foreign event scope.
-  # However the object can be passed as reference and is automatically unwrapped when passed back to the original scope.
+  # The object is therefore wrapped as {WrappedObject} or {ExternalObject} when used in an unsafe scope.
+  # Objects marked within the event scope are wrapped as {WrappedObject}, which denies access from external/action scope or the event scope of a different Eventbox instance.
+  # Objects marked in external/action scope are wrapped as {ExternalObject} which allows {External.send asynchronous calls} from event scope.
+  # In all cases the object can be passed as reference and is automatically unwrapped when passed back to the original scope.
   # It can therefore be used to modify the original object even after traversing the boundaries.
   #
-  # Wrapping and unwrapping works even if the shared object is stored within another object as instance variable or within a collection class.
-  #
   # The mark is stored for the lifetime of the object, so that it's enough to mark only once at object creation.
+  #
+  # Due to {Eventbox::Sanitizer Sanitizer dissection} of non-marshalable objects, wrapping and unwrapping works even if the shared object is stored within another object as instance variable or within a collection class.
+  # This is in contrast to €-variables which can only wrap the argument object as a whole when entering the event scope.
+  # See the difference here:
+  #
+  #   A = Struct.new(:a)
+  #   class Bo < Eventbox
+  #     sync_call def go(struct, €struct)
+  #       p struct            # prints #<struct A a=#<Eventbox::ExternalObject @object="abc" @name=:a>>
+  #       p €struct           # prints #<Eventbox::ExternalObject @object=#<struct A a="abc"> @name=:€struct>
+  #       [struct, €struct]
+  #     end
+  #   end
+  #   e = Bo.new
+  #   o = A.new(e.shared_object("abc"))
+  #   e.go(o, o)              # => [#<struct A a="abc">, #<struct A a="abc">]
   public def shared_object(object)
     @__event_loop__.shared_object(object)
   end
 
+  public def €(object)
+    @__event_loop__.€(object)
+  end
+
+  # Starts a new action dedicated to call external objects.
+  #
+  # It returns a {CallContext} which can be used with {Eventbox::ExternalObject#send} and {Eventbox::ExternalProc#call}.
+  #
+  # @returns [ActionCallContext]  A new call context provided by a newly started action.
+  private def new_action_call_context
+    ActionCallContext.new(@__event_loop__)
+  end
+
+  # Get the context of the waiting external call within a yield or sync method or closure.
+  #
+  # Callable within the event scope only.
+  #
+  # @returns [BlockingExternalCallContext]  The current call context.
+  #   Returns +nil+ in async_call or async_proc context.
+  #
+  # Usable as first parameter to {ExternalProc.call} and {ExternalObject.send}.
+  private def call_context
+    if @__event_loop__.event_scope?
+      @__event_loop__._latest_call_context
+    else
+      raise InvalidAccess, "not in event scope"
+    end
+  end
+
+  private def with_call_context(ctx, &block)
+    if @__event_loop__.event_scope?
+      @__event_loop__.with_call_context(ctx, &block)
+    else
+      raise InvalidAccess, "not in event scope"
+    end
+  end
+
   # Force stop of all action threads spawned by this {Eventbox} instance.
   #
   # It is possible to enable automatic cleanup of action threads by the garbage collector through {Eventbox.with_options}.