eventbox 0.1.0 → 1.0.1

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/gems/eventbox/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,6 @@ 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.2"
   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 "minitest", "~> 5.0"
-  spec.add_development_dependency "yard", "~> 0.9"
 end

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_call(eventbox, *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_call(eventbox, *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

data/lib/eventbox/call_context.rb

@@ -0,0 +1,47 @@
+# frozen-string-literal: true
+
+class Eventbox
+  module CallContext
+    # @private
+    def __answer_queue__
+      @__answer_queue__
+    end
+
+    # @private
+    attr_writer :__answer_queue__
+  end
+
+  class BlockingExternalCallContext
+    include CallContext
+  end
+
+  class ActionCallContext
+    include CallContext
+
+    # @private
+    def initialize(event_loop)
+      answer_queue = Queue.new
+      meth = proc do
+        event_loop.callback_loop(answer_queue, nil, self.class)
+      end
+      @action = event_loop.start_action(meth, self.class, [])
+
+      def answer_queue.gc_stop(object_id)
+        close
+      end
+      ObjectSpace.define_finalizer(self, answer_queue.method(:gc_stop))
+
+      @__answer_queue__ = answer_queue
+    end
+
+    # The action that drives the call context.
+    attr_reader :action
+
+    # Terminate the call context and the driving action.
+    #
+    # The method returns immediately and the corresponding action is terminated asynchonously.
+    def shutdown!
+      @__answer_queue__.close
+    end
+  end
+end