eventbox 0.1.0

data/lib/eventbox/argument_wrapper.rb

@@ -0,0 +1,76 @@
+# frozen-string-literal: true
+
+class Eventbox
+  module ArgumentWrapper
+    def self.build(method, name)
+      parameters = method.parameters
+      if parameters.find { |t, n| n.to_s.start_with?("€") }
+
+        # Change a Proc object to a Method, so that we are able to differ between :opt and :req parameters.
+        # This is because Ruby (wrongly IMHO) reports required parameters as optional.
+        # The only way to get the true parameter types is through define_method.
+        is_proc = Proc === method
+        if is_proc
+          cl = Class.new do
+            define_method(:to_method, &method)
+          end
+          method = cl.instance_method(:to_method)
+          parameters = method.parameters
+        end
+
+        decls = []
+        convs = []
+        rets = []
+        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})"
+            end
+            rets << n
+          when :opt
+            decls << "#{n}=nil"
+            if €var
+              convs << "#{n} = #{n} ? WrappedObject.new(#{n}, source_event_loop, :#{n}) : []"
+            end
+            rets << "*#{n}"
+          when :rest
+            decls << "*#{n}"
+            if €var
+              convs << "#{n}.map!{|v| WrappedObject.new(v, source_event_loop, :#{n}) }"
+            end
+            rets << "*#{n}"
+          when :keyreq
+            decls << "#{n}:"
+            if €var
+              convs << "#{n} = WrappedObject.new(#{n}, source_event_loop, :#{n})"
+            end
+            rets << "#{n}: #{n}"
+          when :key
+            decls << "#{n}:nil"
+            if €var
+              convs << "#{n} = #{n} ? {#{n}: WrappedObject.new(#{n}, source_event_loop, :#{n})} : {}"
+            else
+              convs << "#{n} = #{n} ? {#{n}: #{n}} : {}"
+            end
+            rets << "**#{n}"
+          when :keyrest
+            decls << "**#{n}"
+            if €var
+              convs << "#{n}.each{|k, v| #{n}[k] = WrappedObject.new(v, source_event_loop, :#{n}) }"
+            end
+            rets << "**#{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"
+        instance_eval(code, "wrapper code defined in #{__FILE__}:#{__LINE__} for #{name}")
+      end
+    end
+  end
+end

data/lib/eventbox/boxable.rb

@@ -0,0 +1,298 @@
+# frozen-string-literal: true
+
+class Eventbox
+
+  # Extend modules with Eventbox method creation functions
+  #
+  # This works like so:
+  #
+  #   module MyHelpers
+  #     extend Eventbox::Boxable
+  #     sync_call def hello
+  #       puts "hello!"
+  #     end
+  #   end
+  #
+  #   class MyBox < Eventbox
+  #     include MyHelpers
+  #   end
+  #
+  #   MyBox.new.hello   # prints "hello!"
+  #
+  module Boxable
+    private
+
+    # @private
+    def with_block_or_def(name, block, &cexec)
+      alias_method("__#{name}__", name)
+      private("__#{name}__")
+      remove_method(name)
+      define_method(name, &cexec)
+      private name if name == :init
+      name
+    end
+
+    # Define a threadsafe method for asynchronous (fire-and-forget) calls.
+    #
+    # 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}.
+    #
+    # 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.
+    #
+    # In contrast to {sync_call} it's not possible to call external blocks or proc objects from {async_call} methods.
+    #
+    # The method always returns +self+ to the caller.
+    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|
+        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)
+        else
+          @__event_loop__.async_call(eventbox, name, args, cb, wrapper)
+        end
+        self
+      end
+    end
+
+    # Define a method for synchronous calls.
+    #
+    # The created method can be safely called from any thread.
+    # It is simular to {async_call}, but the method waits until the method body is executed and returns its return value.
+    # Since all processing within the event scope of an {Eventbox} instance must not involve blocking operations, sync calls can only return immediate values.
+    # For deferred results use {yield_call} instead.
+    #
+    # It's possible to call external blocks or proc objects from {sync_call} methods.
+    # 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}.
+    #
+    # 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|
+        if @__event_loop__.event_scope?
+          unbound_method.bind(eventbox).call(*args, &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)
+        end
+      end
+    end
+
+    # Define a method for calls with deferred result.
+    #
+    # This call type is simular to {sync_call}, however it's not the result of the method that is returned.
+    # Instead the method is called with one {CompletionProc additional argument} in the event scope, which is used to yield a result value or raise an exception.
+    # In contrast to a +return+ statement, the execution of the method continues after yielding a result.
+    #
+    # The result value can be yielded within the called method, but it can also be stored and called by any other event scope or external method, leading to a deferred method return.
+    # The external thread calling this method is suspended until a result is yielded.
+    # However the Eventbox object keeps responsive to calls from other threads.
+    #
+    # The created method can be safely called from any thread.
+    # If yield methods are called in the event scope, they must get a Proc object as the last argument.
+    # It is called when a result was yielded.
+    #
+    # It's possible to call external blocks or proc objects from {yield_call} methods up to the point when the result was yielded.
+    # 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}.
+    #
+    # 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.
+    def yield_call(name, &block)
+      unbound_method = self.instance_method(name)
+      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)
+          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)
+        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)
+    end
+
+    # Threadsafe read access to instance variables.
+    def attr_reader(name)
+      sync_call(define_method("#{name}") do
+        instance_variable_get("@#{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.
+    #
+    # 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 }
+    #   end
+    #   action def do_something
+    #     self.counter += 1
+    #   end
+    #
+    # Instead don't use accessors but do increments within one method call like so:
+    #   async_call def start
+    #     10.times { do_something }
+    #   end
+    #   action def do_something
+    #     increment 1
+    #   end
+    #   async_call def increment(by)
+    #     @counter += by
+    #   end
+    def attr_accessor(name)
+      attr_reader name
+      attr_writer name
+    end
+
+    # Define a private method for asynchronous execution.
+    #
+    # The call to the action method returns immediately after starting a new action.
+    # It returns an {Action} object.
+    # By default each call to an action method spawns a new thread which executes the code of the action definition.
+    # Alternatively a threadpool can be assigned by {with_options}.
+    #
+    # All method arguments are passed through the {Sanitizer}.
+    #
+    # Actions can return state changes or objects to the event loop by calls to methods created by {async_call}, {sync_call} or {yield_call} or through calling {async_proc}, {sync_proc} or {yield_proc} objects.
+    # To avoid unsafe shared objects, an action has it's own set of local variables or instance variables.
+    # It doesn't have access to variables defined by other methods.
+    #
+    # The {Action} object can be used to interrupt the program execution by an exception.
+    # See {Eventbox::Action} for further information.
+    # If the action method accepts one more argument than given to the action call, it is set to corresponding {Action} instance:
+    #   async_call def init
+    #     do_something("value1")
+    #   end
+    #   action def do_something(str, action)
+    #     str              # => "value1"
+    #     action.current?  # => true
+    #     # `action' can be passed to event scope or external scope,
+    #     # in order to send a signals per Action#raise
+    #   end
+    #
+    def action(name, &block)
+      unbound_method = self.instance_method(name)
+      with_block_or_def(name, block) do |*args, &cb|
+        raise InvalidAccess, "action must not be called with a block" if cb
+
+        gc_actions = self.class.eventbox_options[:gc_actions]
+        sandbox = self.class.allocate
+        sandbox.instance_variable_set(:@__event_loop__, @__event_loop__)
+        sandbox.instance_variable_set(:@__eventbox__, gc_actions ? WeakRef.new(self) : self)
+        meth = unbound_method.bind(sandbox)
+
+        if @__event_loop__.event_scope?
+          args = Sanitizer.sanitize_values(args, @__event_loop__, nil)
+        end
+        # Start a new action thread and return an Action instance
+        @__event_loop__.start_action(meth, name, args)
+      end
+      private name
+      name
+    end
+  end
+
+  # 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 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.
+  # Exceptions raised to an action thread are delayed until a code block is reached which explicit allows interruption.
+  # The only exception which is delivered to the action thread by default is {Eventbox::AbortAction}.
+  # 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`.
+  # Otherwise it could happen, that the rescuing code is interrupted by the signal.
+  # Sending custom signals to an action works like:
+  #
+  #   class MySignal < Interrupt
+  #   end
+  #
+  #   async_call def init
+  #     a = start_sleep
+  #     a.raise(MySignal)
+  #   end
+  #
+  #   action def start_sleep
+  #     Thread.handle_interrupt(MySignal => :on_blocking) do
+  #       sleep
+  #     end
+  #   rescue MySignal
+  #     puts "well-rested"
+  #   end
+  class Action
+    attr_reader :name
+
+    def initialize(name, thread, event_loop)
+      @name = name
+      @thread = thread
+      @event_loop = event_loop
+    end
+
+    attr_reader :event_loop
+    private :event_loop
+
+    # Send a signal to the running action.
+    #
+    # The signal must be kind of Exception.
+    # See {Action} about asynchronous delivery of signals.
+    #
+    # 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`.
+    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
+
+      if @event_loop.event_scope?
+        args = Sanitizer.sanitize_values(args, @event_loop, nil)
+      end
+      @thread.raise(*args)
+    end
+
+    # Send a AbortAction to the running thread.
+    def abort
+      @thread.raise AbortAction
+    end
+
+    # Belongs the current thread to this action.
+    def current?
+      @thread.respond_to?(:current?) ? @thread.current? : (@thread == Thread.current)
+    end
+
+    # @private
+    def join
+      @thread.join
+    end
+  end
+end

data/lib/eventbox/event_loop.rb

@@ -0,0 +1,385 @@
+# frozen-string-literal: true
+
+class Eventbox
+  # @private
+  #
+  # This class manages the calls to event scope methods and procs comparable to an event loop.
+  # It doesn't use an explicit event loop, but uses the calling thread to process the event.
+  #
+  # All methods prefixed with "_" requires @mutex acquired to be called.
+  class EventLoop
+    def initialize(threadpool, guard_time)
+      @threadpool = threadpool
+      @running_actions = []
+      @running_actions_for_gc = []
+      @mutex = Mutex.new
+      @shutdown = false
+      @guard_time_proc = case guard_time
+        when NilClass
+          nil
+        when Numeric
+          guard_time and proc do |dt, name|
+            if dt > guard_time
+              ecaller = caller.find{|t| !(t=~/lib\/eventbox(\/|\.rb:)/) }
+              warn "guard time exceeded: #{"%2.3f" % dt} sec (limit is #{guard_time}) in `#{name}' called from `#{ecaller}' - please move blocking tasks to actions"
+            end
+          end
+        when Proc
+          guard_time
+        else
+          raise ArgumentError, "guard_time should be Numeric, Proc or nil"
+      end
+    end
+
+    # Abort all running action threads.
+    def send_shutdown(object_id=nil)
+#       warn "shutdown called for object #{object_id} with #{@running_actions.size} threads #{@running_actions.map(&:object_id).join(",")}"
+
+      # The finalizer doesn't allow suspension per Mutex, so that we access a read-only copy of @running_actions.
+      # To avoid race conditions with thread creation, set a flag before the loop.
+      @shutdown = true
+
+      # terminate all running action threads
+      begin
+        @running_actions_for_gc.each(&:abort)
+      rescue ThreadError
+        # ThreadPool requires to lock a mutex, which fails in trap context.
+        # So defer the abort through another thread.
+        Thread.new do
+          @running_actions_for_gc.each(&:abort)
+        end
+      end
+
+      nil
+    end
+
+    def shutdown(&completion_block)
+      send_shutdown
+      if event_scope?
+        if completion_block
+          completion_block = new_async_proc(&completion_block)
+
+          # Thread might not be tagged to a calling event scope
+          source_event_loop = Thread.current.thread_variable_get(:__event_loop__)
+          Thread.current.thread_variable_set(:__event_loop__, nil)
+          begin
+            @threadpool.new do
+              @running_actions_for_gc.each(&:join)
+              completion_block.call
+            end
+          ensure
+            Thread.current.thread_variable_set(:__event_loop__, source_event_loop)
+          end
+        end
+      else
+        raise InvalidAccess, "external shutdown call doesn't take a block but blocks until threads have terminated" if completion_block
+        @running_actions_for_gc.each(&:join)
+      end
+    end
+
+    # Make a copy of the thread list for use in shutdown.
+    # The copy is replaced per an atomic operation, so that it can be read lock-free in shutdown.
+    def _update_action_threads_for_gc
+      @running_actions_for_gc = @running_actions.dup
+    end
+
+    # Is the caller running within the event scope context?
+    def event_scope?
+      @mutex.owned?
+    end
+
+    def synchronize_external
+      if event_scope?
+        yield
+      else
+        @mutex.synchronize do
+          yield
+        end
+      end
+    end
+
+    def with_call_frame(name, answer_queue)
+      source_event_loop = Thread.current.thread_variable_get(:__event_loop__)
+      @mutex.lock
+      begin
+        Thread.current.thread_variable_set(:__event_loop__, self)
+        @latest_answer_queue = answer_queue
+        @latest_call_name = name
+        start_time = Time.now
+        yield(source_event_loop)
+      ensure
+        @latest_answer_queue = nil
+        @latest_call_name = nil
+        @mutex.unlock
+        diff_time = Time.now - start_time
+        @guard_time_proc&.call(diff_time, name)
+        Thread.current.thread_variable_set(:__event_loop__, source_event_loop)
+      end
+      source_event_loop
+    end
+
+    def async_call(box, name, args, block, wrapper)
+      with_call_frame(name, nil) do |source_event_loop|
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self, name)
+        block = Sanitizer.sanitize_value(block, source_event_loop, self, name)
+        box.send("__#{name}__", *args, &block)
+      end
+    end
+
+    def sync_call(box, name, args, block, answer_queue, wrapper)
+      with_call_frame(name, answer_queue) do |source_event_loop|
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self, name)
+        block = Sanitizer.sanitize_value(block, source_event_loop, self, name)
+        res = box.send("__#{name}__", *args, &block)
+        res = Sanitizer.sanitize_value(res, self, source_event_loop)
+        answer_queue << res
+      end
+    end
+
+    def yield_call(box, name, args, kwargs, block, answer_queue, wrapper)
+      with_call_frame(name, answer_queue) do |source_event_loop|
+        args << _completion_proc(answer_queue, name, source_event_loop)
+        args << kwargs unless kwargs.empty?
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self, name)
+        block = Sanitizer.sanitize_value(block, source_event_loop, self, name)
+        box.send("__#{name}__", *args, &block)
+      end
+    end
+
+    # Anonymous version of async_call
+    def async_proc_call(pr, args, arg_block, wrapper)
+      with_call_frame(AsyncProc, nil) do |source_event_loop|
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self)
+        arg_block = Sanitizer.sanitize_value(arg_block, source_event_loop, self)
+        pr.yield(*args, &arg_block)
+      end
+    end
+
+    # Anonymous version of sync_call
+    def sync_proc_call(pr, args, arg_block, answer_queue, wrapper)
+      with_call_frame(SyncProc, answer_queue) do |source_event_loop|
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self)
+        arg_block = Sanitizer.sanitize_value(arg_block, source_event_loop, self)
+        res = pr.yield(*args, &arg_block)
+        res = Sanitizer.sanitize_value(res, self, source_event_loop)
+        answer_queue << res
+      end
+    end
+
+    # Anonymous version of yield_call
+    def yield_proc_call(pr, args, kwargs, arg_block, answer_queue, wrapper)
+      with_call_frame(YieldProc, answer_queue) do |source_event_loop|
+        args << _completion_proc(answer_queue, pr, source_event_loop)
+        args << kwargs unless kwargs.empty?
+        args = wrapper.call(source_event_loop, *args) if wrapper
+        args = Sanitizer.sanitize_values(args, source_event_loop, self)
+        arg_block = Sanitizer.sanitize_value(arg_block, source_event_loop, self)
+        pr.yield(*args, &arg_block)
+      end
+    end
+
+    # Called when an external proc finished
+    def external_proc_result(cbresult, res)
+      with_call_frame(ExternalProc, nil) do
+        cbresult.yield(*res)
+      end
+    end
+
+    def new_async_proc(name=nil, klass=AsyncProc, &block)
+      raise InvalidAccess, "async_proc outside of the event scope is not allowed" unless event_scope?
+      wrapper = ArgumentWrapper.build(block, "async_proc #{name}")
+      pr = klass.new do |*args, &arg_block|
+        if event_scope?
+          # called in the event scope
+          block.yield(*args, &arg_block)
+        else
+          # called externally
+          async_proc_call(block, args, arg_block, wrapper)
+        end
+        pr
+      end
+    end
+
+    def new_sync_proc(name=nil, &block)
+      raise InvalidAccess, "sync_proc outside of the event scope is not allowed" unless event_scope?
+      wrapper = ArgumentWrapper.build(block, "sync_proc #{name}")
+      SyncProc.new do |*args, &arg_block|
+        if event_scope?
+          # called in the event scope
+          block.yield(*args, &arg_block)
+        else
+          # called externally
+          answer_queue = Queue.new
+          sel = sync_proc_call(block, args, arg_block, answer_queue, wrapper)
+          callback_loop(answer_queue, sel)
+        end
+      end
+    end
+
+    def new_yield_proc(name=nil, &block)
+      raise InvalidAccess, "yield_proc outside of the event scope is not allowed" unless event_scope?
+      wrapper = ArgumentWrapper.build(block, "yield_proc #{name}")
+      YieldProc.new do |*args, **kwargs, &arg_block|
+        if event_scope?
+          # called in the event scope
+          safe_yield_result(args, block)
+          args << kwargs unless kwargs.empty?
+          block.yield(*args, &arg_block)
+          nil
+        else
+          # called externally
+          answer_queue = Queue.new
+          sel = yield_proc_call(block, args, kwargs, arg_block, answer_queue, wrapper)
+          callback_loop(answer_queue, sel)
+        end
+      end
+    end
+
+    def safe_yield_result(args, name)
+      complete = args.last
+      unless Proc === complete
+        if Proc === name
+          raise InvalidAccess, "yield_proc #{name.inspect} must be called with a Proc object in the event scope but got #{complete.class}"
+        else
+          raise InvalidAccess, "yield_call `#{name}' must be called with a Proc object in the event scope but got #{complete.class}"
+        end
+      end
+      args[-1] = proc do |*cargs, &cblock|
+        unless complete
+          if Proc === name
+            raise MultipleResults, "received multiple results for #{name.inspect}"
+          else
+            raise MultipleResults, "received multiple results for method `#{name}'"
+          end
+        end
+        res = complete.yield(*cargs, &cblock)
+        complete = nil
+        res
+      end
+    end
+
+    private def _completion_proc(answer_queue, name, source_event_loop)
+      new_async_proc(name, CompletionProc) do |*resu|
+        unless answer_queue
+          if Proc === name
+            raise MultipleResults, "received multiple results for #{name.inspect}"
+          else
+            raise MultipleResults, "received multiple results for method `#{name}'"
+          end
+        end
+        resu = Sanitizer.sanitize_values(resu, self, source_event_loop)
+        resu = Sanitizer.return_args(resu)
+        answer_queue << resu
+        answer_queue = nil
+      end
+    end
+
+    def callback_loop(answer_queue, source_event_loop)
+      loop do
+        rets = answer_queue.deq
+        case rets
+        when Callback
+          cbres = rets.block.yield(*rets.args, &rets.arg_block)
+
+          if rets.cbresult
+            cbres = Sanitizer.sanitize_value(cbres, source_event_loop, self)
+            external_proc_result(rets.cbresult, cbres)
+          end
+        when WrappedException
+          answer_queue.close if answer_queue.respond_to?(:close)
+          raise(*rets.exc)
+        else
+          answer_queue.close if answer_queue.respond_to?(:close)
+          return rets
+        end
+      end
+    end
+
+    # Mark an object as to be shared instead of copied.
+    def shared_object(object)
+      if event_scope?
+        ObjectRegistry.set_tag(object, self)
+      else
+        ObjectRegistry.set_tag(object, ExternalSharedObject)
+      end
+      object
+    end
+
+    def thread_finished(action)
+      @mutex.synchronize do
+        @running_actions.delete(action) or raise(ArgumentError, "unknown action has finished: #{action}")
+        _update_action_threads_for_gc
+      end
+    end
+
+    Callback = Struct.new :block, :args, :arg_block, :cbresult
+
+    def _external_proc_call(block, name, args, arg_block, cbresult, source_event_loop)
+      if @latest_answer_queue
+        args = Sanitizer.sanitize_values(args, self, source_event_loop)
+        arg_block = Sanitizer.sanitize_value(arg_block, self, source_event_loop)
+        @latest_answer_queue << Callback.new(block, args, arg_block, cbresult)
+        nil
+      else
+        raise(InvalidAccess, "closure #{"defined by `#{name}' " if name}was yielded by `#{@latest_call_name}', which must a sync_call, yield_call, sync_proc or yield_proc")
+      end
+    end
+
+    def start_action(meth, name, args)
+      # Actions might not be tagged to a calling event scope
+      source_event_loop = Thread.current.thread_variable_get(:__event_loop__)
+      Thread.current.thread_variable_set(:__event_loop__, nil)
+
+      qu = Queue.new
+
+      new_thread = Thread.handle_interrupt(Exception => :never) do
+        @threadpool.new do
+          begin
+            Thread.handle_interrupt(AbortAction => :on_blocking) do
+              if meth.arity == args.length
+                meth.call(*args)
+              else
+                meth.call(*args, qu.deq)
+              end
+            end
+          rescue AbortAction
+            # Do nothing, just exit the action
+          rescue WeakRef::RefError
+            # It can happen that the GC already swept the Eventbox instance, before some instance action is in a blocking state.
+            # In this case access to the Eventbox instance raises a RefError.
+            # Since it's now impossible to execute the action up to a blocking state, abort the action prematurely.
+            raise unless @shutdown
+          ensure
+            thread_finished(qu.deq)
+          end
+        end
+      end
+
+      a = Action.new(name, new_thread, self)
+
+      # Add to the list of running actions
+      synchronize_external do
+        @running_actions << a
+        _update_action_threads_for_gc
+      end
+
+      # Enqueue the action twice (for call and for finish)
+      qu << a << a
+
+      # @shutdown is set without a lock, so that we need to re-check, if it was set while start_action
+      if @shutdown
+        a.abort
+        a.join
+      end
+
+      a
+    ensure
+      Thread.current.thread_variable_set(:__event_loop__, source_event_loop)
+    end
+  end
+end