eventbox 0.1.0 → 1.0.0

data/docs/my_queue_calls_github.md

@@ -0,0 +1 @@
+[![MyQueue calls](https://raw.github.com/larskanis/eventbox/master/docs/images/my_queue_calls.svg?sanitize=true)](https://www.rubydoc.info/github/larskanis/eventbox/master/file/README.md#my_queue_image)

data/docs/my_queue_calls_local.md

@@ -0,0 +1 @@
+{include:file:docs/images/my_queue_calls.svg}

data/docs/server.md

@@ -1,6 +1,13 @@
+## A TCP server implementation with tracking of startup and shutdown
+
 Race-free server startup and shutdown can be a tricky task.
 The following example illustrates, how a TCP server can be started and interrupted properly.
 
+For startup it makes use of {Eventbox::CompletionProc yield} and {Eventbox::CompletionProc#raise} to complete `MyServer.new` either successfully or with the forwarded exception raised by `TCPServer.new`.
+
+For the shutdown it makes use of {Eventbox::Action#raise} to send a `Stop` signal to the blocking `accept` method.
+The `Stop` instance carries the {Eventbox::CompletionProc} which is used to signal that the shutdown has finished by returning from `MyServer#stop`.
+
 ```ruby
 require "eventbox"
 require "socket"
@@ -8,36 +15,39 @@ require "socket"
 class MyServer < Eventbox
   yield_call def init(bind, port, result)
     @count = 0
-    @server = start_serving(bind, port, result)
+    @server = start_serving(bind, port, result)   # Start an action to handle incomming connections
   end
 
   action def start_serving(bind, port, init_done)
     serv = TCPServer.new(bind, port)
   rescue => err
-    init_done.raise err
+    init_done.raise err        # complete MyServer.new with an exception
   else
-    init_done.yield
+    init_done.yield            # complete MyServer.new without exception
 
-    loop do
+    loop do                    # accept all connection requests until Stop is received
       begin
+        # enable interruption by the Stop class for the duration of the `accept` call
         conn = Thread.handle_interrupt(Stop => :on_blocking) do
-          serv.accept
+          serv.accept          # wait for the next connection request come in
         end
       rescue Stop => st
         serv.close
-        st.stopped.yield
-        break
+        st.stopped.yield       # let MyServer#stop return
+        break                  # and exit the action
       else
-        MyConnection.new(conn, self)
+        MyConnection.new(conn, self)  # Handle each client by its own instance
       end
     end
   end
 
+  # A simple example for a shared resource to be used by several threads
   sync_call def count
-    @count += 1
+    @count += 1                # atomically increment the counter
   end
 
   yield_call def stop(result)
+    # Don't return from `stop` externally, but wait until the server is down
     @server.raise(Stop.new(result))
   end
 
@@ -49,11 +59,12 @@ class MyServer < Eventbox
   end
 end
 
+# Each call to `MyConnection.new` starts a new thread to do the communication.
 class MyConnection < Eventbox
   action def init(conn, server)
     conn.write "Hello #{server.count}"
   ensure
-    conn.close
+    conn.close         # Don't wait for an answer but just close the client connection
   end
 end
 ```
@@ -61,15 +72,15 @@ end
 The server can now be started like so.
 
 ```ruby
-s = MyServer.new('localhost', 12345)
+s = MyServer.new('localhost', 12345)  # Open a TCP socket
 
-10.times.map do
+10.times.map do                       # run 10 client connections in parallel
   Thread.new do
     TCPSocket.new('localhost', 12345).read
   end
-end.each { |th| p th.value }
+end.each { |th| p th.value }          # and print their responses
 
-s.stop
+s.stop                                # shutdown the server socket
 ```
 
 It prints some output like this:

data/docs/threadpool.md

@@ -1,9 +1,12 @@
+## A thread-pool implementation making use of Eventbox
+
 The following class implements a thread-pool with a fixed number of threads to be borrowed by the `pool` method.
-It shows how the action method `start_pool_thread` makes use of the private yield_call `next_job` to query, wait for and retrieve an object from the event scope.
+It shows how the action method `start_pool_thread` makes use of the private {Eventbox.yield_call yield_call} `next_job` to query, wait for and retrieve an object from the event scope.
 
 This kind of object is the block that is given to `pool`.
 Although all closures (blocks, procs and lambdas) are wrapped in a way that allows safe calls from the event scope, it is just passed through to the action scope and retrieved as the result value of `next_job`.
 When this happens, the wrapping is automatically removed, so that the pure block given to `pool` is called in `start_pool_thread`.
+That way each action thread runs one block at the same time, but all started action threads process the blocks concurrently.
 
 ```ruby
 class ThreadPool < Eventbox

data/eventbox.gemspec

@@ -21,11 +21,12 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = "~> 2.3"
+  spec.required_ruby_version = ">= 3.0", "< 4.0"
   spec.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.
 
   spec.add_development_dependency "bundler", ">= 1.16", "< 3"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-hooks"
   spec.add_development_dependency "yard", "~> 0.9"
 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}.

data/lib/eventbox/argument_wrapper.rb

@@ -21,54 +21,55 @@ class Eventbox
         decls = []
         convs = []
         rets = []
+        kwrets = []
         parameters.each_with_index do |(t, n), i|
           €var = n.to_s.start_with?("€")
           case t
           when :req
             decls << n
             if €var
-              convs << "#{n} = WrappedObject.new(#{n}, source_event_loop, :#{n})"
+              convs << "#{n} = Sanitizer.wrap_object(#{n}, source_event_loop, target_event_loop, :#{n})"
             end
             rets << n
           when :opt
             decls << "#{n}=nil"
             if €var
-              convs << "#{n} = #{n} ? WrappedObject.new(#{n}, source_event_loop, :#{n}) : []"
+              convs << "#{n} = #{n} ? Sanitizer.wrap_object(#{n}, source_event_loop, target_event_loop, :#{n}) : []"
             end
             rets << "*#{n}"
           when :rest
             decls << "*#{n}"
             if €var
-              convs << "#{n}.map!{|v| WrappedObject.new(v, source_event_loop, :#{n}) }"
+              convs << "#{n}.map!{|v| Sanitizer.wrap_object(v, source_event_loop, target_event_loop, :#{n}) }"
             end
             rets << "*#{n}"
           when :keyreq
             decls << "#{n}:"
             if €var
-              convs << "#{n} = WrappedObject.new(#{n}, source_event_loop, :#{n})"
+              convs << "#{n} = Sanitizer.wrap_object(#{n}, source_event_loop, target_event_loop, :#{n})"
             end
-            rets << "#{n}: #{n}"
+            kwrets << "#{n}: #{n}"
           when :key
             decls << "#{n}:nil"
             if €var
-              convs << "#{n} = #{n} ? {#{n}: WrappedObject.new(#{n}, source_event_loop, :#{n})} : {}"
+              convs << "#{n} = #{n} ? {#{n}: Sanitizer.wrap_object(#{n}, source_event_loop, target_event_loop, :#{n})} : {}"
             else
               convs << "#{n} = #{n} ? {#{n}: #{n}} : {}"
             end
-            rets << "**#{n}"
+            kwrets << "**#{n}"
           when :keyrest
             decls << "**#{n}"
             if €var
-              convs << "#{n}.each{|k, v| #{n}[k] = WrappedObject.new(v, source_event_loop, :#{n}) }"
+              convs << "#{n}.transform_values!{|v| Sanitizer.wrap_object(v, source_event_loop, target_event_loop, :#{n}) }"
             end
-            rets << "**#{n}"
+            kwrets << "**#{n}"
           when :block
             if €var
               raise "block to `#{name}' can't be wrapped"
             end
           end
         end
-        code = "#{is_proc ? :proc : :lambda} do |source_event_loop#{decls.map{|s| ",#{s}"}.join }| # #{name}\n  #{convs.join("\n")}\n  [#{rets.join(",")}]\nend"
+        code = "#{is_proc ? :proc : :lambda} do |source_event_loop, target_event_loop#{decls.map{|s| ",#{s}"}.join }| # #{name}\n  #{convs.join("\n")}\n  [[#{rets.join(",")}],{#{kwrets.join(",")}}]\nend"
         instance_eval(code, "wrapper code defined in #{__FILE__}:#{__LINE__} for #{name}")
       end
     end

data/lib/eventbox/boxable.rb

@@ -36,7 +36,7 @@ class Eventbox
     #
     # The created method can be safely called from any thread.
     # All method arguments are passed through the {Sanitizer}.
-    # Arguments prefixed by a € sign are automatically passed as {Eventbox::WrappedObject}.
+    # Arguments prefixed by a +€+ sign are automatically passed as {Eventbox::ExternalObject}.
     #
     # The method itself might not do any blocking calls or expensive computations - this would impair responsiveness of the {Eventbox} instance.
     # Instead use {action} in these cases.
@@ -47,13 +47,13 @@ class Eventbox
     def async_call(name, &block)
       unbound_method = self.instance_method(name)
       wrapper = ArgumentWrapper.build(unbound_method, name)
-      with_block_or_def(name, block) do |*args, &cb|
+      with_block_or_def(name, block) do |*args, **kwargs, &cb|
         if @__event_loop__.event_scope?
           # Use the correct method within the class hierarchy, instead of just self.send(*args).
           # Otherwise super() would start an infinite recursion.
-          unbound_method.bind(eventbox).call(*args, &cb)
+          unbound_method.bind(eventbox).call(*args, **kwargs, &cb)
         else
-          @__event_loop__.async_call(eventbox, name, args, cb, wrapper)
+          @__event_loop__.async_call(eventbox, name, args, kwargs, cb, wrapper)
         end
         self
       end
@@ -70,20 +70,20 @@ class Eventbox
     # Blocks are executed by the same thread that calls the {sync_call} method to that time.
     #
     # All method arguments as well as the result value are passed through the {Sanitizer}.
-    # Arguments prefixed by a € sign are automatically passed as {Eventbox::WrappedObject}.
+    # Arguments prefixed by a +€+ sign are automatically passed as {Eventbox::ExternalObject}.
     #
     # The method itself might not do any blocking calls or expensive computations - this would impair responsiveness of the {Eventbox} instance.
     # Instead use {action} in these cases.
     def sync_call(name, &block)
       unbound_method = self.instance_method(name)
       wrapper = ArgumentWrapper.build(unbound_method, name)
-      with_block_or_def(name, block) do |*args, &cb|
+      with_block_or_def(name, block) do |*args, **kwargs, &cb|
         if @__event_loop__.event_scope?
-          unbound_method.bind(eventbox).call(*args, &cb)
+          unbound_method.bind(eventbox).call(*args, **kwargs, &cb)
         else
           answer_queue = Queue.new
-          sel = @__event_loop__.sync_call(eventbox, name, args, cb, answer_queue, wrapper)
-          @__event_loop__.callback_loop(answer_queue, sel)
+          sel = @__event_loop__.sync_call(eventbox, name, args, kwargs, cb, answer_queue, wrapper)
+          @__event_loop__.callback_loop(answer_queue, sel, name)
         end
       end
     end
@@ -106,7 +106,7 @@ class Eventbox
     # Blocks are executed by the same thread that calls the {yield_call} method to that time.
     #
     # All method arguments as well as the result value are passed through the {Sanitizer}.
-    # Arguments prefixed by a € sign are automatically passed as {Eventbox::WrappedObject}.
+    # Arguments prefixed by a +€+ sign are automatically passed as {Eventbox::ExternalObject}.
     #
     # The method itself as well as the Proc object might not do any blocking calls or expensive computations - this would impair responsiveness of the {Eventbox} instance.
     # Instead use {action} in these cases.
@@ -115,37 +115,38 @@ class Eventbox
       wrapper = ArgumentWrapper.build(unbound_method, name)
       with_block_or_def(name, block) do |*args, **kwargs, &cb|
         if @__event_loop__.event_scope?
-          @__event_loop__.safe_yield_result(args, name)
-          args << kwargs unless kwargs.empty?
-          unbound_method.bind(eventbox).call(*args, &cb)
+          @__event_loop__.internal_yield_result(args, name)
+          unbound_method.bind(eventbox).call(*args, **kwargs, &cb)
           self
         else
           answer_queue = Queue.new
           sel = @__event_loop__.yield_call(eventbox, name, args, kwargs, cb, answer_queue, wrapper)
-          @__event_loop__.callback_loop(answer_queue, sel)
+          @__event_loop__.callback_loop(answer_queue, sel, name)
         end
       end
     end
 
     # Threadsafe write access to instance variables.
-    def attr_writer(name)
-      async_call(define_method("#{name}=") do |value|
-        instance_variable_set("@#{name}", value)
-      end)
+    def attr_writer(*names)
+      super
+      names.each do |name|
+        async_call(:"#{name}=")
+      end
     end
 
     # Threadsafe read access to instance variables.
-    def attr_reader(name)
-      sync_call(define_method("#{name}") do
-        instance_variable_get("@#{name}")
-      end)
+    def attr_reader(*names)
+      super
+      names.each do |name|
+        sync_call(:"#{name}")
+      end
     end
 
     # Threadsafe read and write access to instance variables.
     #
-    # Attention: Be careful with read-modify-write operations - they are *not* atomic but are executed as two independent operations.
+    # Attention: Be careful with read-modify-write operations like "+=" - they are *not* atomic but are executed as two independent operations.
     #
-    # This will lose counter increments, since `counter` is incremented in a non-atomic manner:
+    # This will lose counter increments, since +counter+ is incremented in a non-atomic manner:
     #   attr_accessor :counter
     #   async_call def start
     #     10.times { do_something }
@@ -164,9 +165,12 @@ class Eventbox
     #   async_call def increment(by)
     #     @counter += by
     #   end
-    def attr_accessor(name)
-      attr_reader name
-      attr_writer name
+    def attr_accessor(*names)
+      super
+      names.each do |name|
+        async_call(:"#{name}=")
+        sync_call(:"#{name}")
+      end
     end
 
     # Define a private method for asynchronous execution.
@@ -192,7 +196,7 @@ class Eventbox
     #     str              # => "value1"
     #     action.current?  # => true
     #     # `action' can be passed to event scope or external scope,
-    #     # in order to send a signals per Action#raise
+    #     # in order to send a signal per Action#raise
     #   end
     #
     def action(name, &block)
@@ -219,7 +223,7 @@ class Eventbox
 
   # An Action object is thin wrapper for a Ruby thread.
   #
-  # It is returned by {Eventbox#action} and optionally passed as last argument to action methods.
+  # It is returned by {Eventbox::Boxable#action action methods} and optionally passed as last argument to action methods.
   # It can be used to interrupt the program execution by an exception.
   #
   # However in contrast to ruby's builtin threads, any interruption must be explicit allowed.
@@ -228,7 +232,7 @@ class Eventbox
   # It is raised by {Eventbox#shutdown!} and is delivered as soon as a blocking operation is executed.
   #
   # An Action object can be used to stop the action while blocking operations.
-  # It should be made sure, that the `rescue` statement is outside of the block to `handle_interrupt`.
+  # It should be made sure, that the +rescue+ statement is outside of the block to +handle_interrupt+.
   # Otherwise it could happen, that the rescuing code is interrupted by the signal.
   # Sending custom signals to an action works like:
   #
@@ -266,10 +270,9 @@ class Eventbox
     #
     # This method does nothing if the action is already finished.
     #
-    # If {raise} is called within the action (#current? returns `true`), all exceptions are delivered immediately.
-    # This happens regardless of the current interrupt mask set by `Thread.handle_interrupt`.
+    # If {raise} is called within the action ({#current?} returns +true+), all exceptions are delivered immediately.
+    # This happens regardless of the current interrupt mask set by +Thread.handle_interrupt+.
     def raise(*args)
-      # ignore raise, if sent from the action thread
       if AbortAction === args[0] || (Module === args[0] && args[0].ancestors.include?(AbortAction))
         ::Kernel.raise InvalidAccess, "Use of Eventbox::AbortAction is not allowed - use Action#abort or a custom exception subclass"
       end
@@ -294,5 +297,10 @@ class Eventbox
     def join
       @thread.join
     end
+
+    # @private
+    def terminate
+      @thread.terminate
+    end
   end
 end