goru 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de298097d409c1186dd803f5748a1af3820c23ea0a7243e1d18c42ef35229906
-  data.tar.gz: d834815e8f7f1a0deb22ad6be3cb8c75d900f81b5ffae1e55ce8eb10ef78bb3e
+  metadata.gz: 65d57e96ef8a7bef1abaf43db02e461af067b60238728379b9a5e48cea91c2f9
+  data.tar.gz: feba54796b8120fe753014a9f904c29c3e379ef50910e6cfde0507ca85d4d695
 SHA512:
-  metadata.gz: 8674505286bace79c7b462ccf6c8b779f3b8ba09b7ca16b02a657d11f803a1f45835d286385b59e50b3909eced44e7ce6601db957b20c62737df96b13a24d564
-  data.tar.gz: 353c05c439a9a85aedd2727f6036b8b858e59dd73f5c29acc4291b9533a78d45b375a8e07e57cc3e57765c974c584bc1aa09304e101fecb38652f8f47d8e588d
+  metadata.gz: c65b2730c39ec515c1ab44ee83909c4ea93c53072cb33887aebafaedfeb0131a37c0b3d1bb323b79ce21acdc5248be3fefa3d19c007c9aa5c56217e9a7195541
+  data.tar.gz: f4d7f05d63ad6ce781053946fa0d0e22ec9562b7e20fed83bca8f84441b4f6ec9c30b8b4b79fa7435cc93a76425ec793b6db7ac334aba0fddac84320777226b3

data/CHANGELOG.md

@@ -1,6 +1,21 @@
-## v0.2.0
+## [v0.3.0](https://github.com/bryanp/goru/releases/tag/v0.3.0)
 
-*unreleased*
+*released on 2023-07-10*
+
+  * `chg` [#16](https://github.com/bryanp/goru/pull/16) Improve control flow ([bryanp](https://github.com/bryanp))
+  * `fix` [#17](https://github.com/bryanp/goru/pull/17) Handle `IOError` from closed selector ([bryanp](https://github.com/bryanp))
+  * `chg` [#15](https://github.com/bryanp/goru/pull/15) Rename `default_scheduler_count` ([bryanp](https://github.com/bryanp))
+  * `chg` [#14](https://github.com/bryanp/goru/pull/14) Improve cold start of scheduler ([bryanp](https://github.com/bryanp))
+  * `chg` [#13](https://github.com/bryanp/goru/pull/13) Go back to selector-based reactor ([bryanp](https://github.com/bryanp))
+  * `chg` [#12](https://github.com/bryanp/goru/pull/12) Refactor bridges (again) ([bryanp](https://github.com/bryanp))
+  * `dep` [#11](https://github.com/bryanp/goru/pull/11) Change responsibilities of routine sleep behavior to be more clear ([bryanp](https://github.com/bryanp))
+  * `chg` [#10](https://github.com/bryanp/goru/pull/10) Optimize how reactor status is set ([bryanp](https://github.com/bryanp))
+  * `chg` [#9](https://github.com/bryanp/goru/pull/9) Refactor bridges ([bryanp](https://github.com/bryanp))
+  * `chg` [#8](https://github.com/bryanp/goru/pull/8) Cleanup finished routines on next tick ([bryanp](https://github.com/bryanp))
+
+## [v0.2.0](https://github.com/bryanp/goru/releases/tag/v0.2.0)
+
+*released on 2023-05-01*
 
   * `fix` [#6](https://github.com/bryanp/goru/pull/6) Finish routines on error ([bryanp](https://github.com/bryanp))
   * `fix` [#5](https://github.com/bryanp/goru/pull/5) Correctly set channel status to `finished` when closed ([bryanp](https://github.com/bryanp))

data/README.md

@@ -201,6 +201,34 @@ Goru::Scheduler.go(io: io, intent: :r) { |routine|
 }
 ```
 
+## Bridges
+
+Goru supports coordinated buffered io using bridges:
+
+```ruby
+writer = Goru::Channel.new
+
+Goru::Scheduler.go(io: io, intent: :r) { |routine|
+  case routine.intent
+  when :r
+    routine.bridge(intent: :w, channel: writer) { |bridge|
+      bridge << SecureRandom.hex
+    }
+  when :w
+    if (data = writer.read)
+      routine.write(data)
+    end
+  end
+}
+```
+
+Using bridges, the io routine is only called again when two conditions are met:
+
+1. The io object matches the bridged intent (e.g. it is writable).
+2. The channel is in the correct state to reciprocate the intent (e.g. it has data).
+
+See the [server example](./examples/server.rb) for a more complete use-case.
+
 ## Credits
 
 Goru was designed while writing a project in Go and imagining what Go-like concurrency might look like in Ruby.

data/lib/goru/bridge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Goru
+  # [public]
+  #
+  class Bridge
+    def initialize(routine:, channel:)
+      @routine = routine
+      @channel = channel
+      @channel.add_observer(self)
+      update_status
+    end
+
+    # [public]
+    #
+    attr_reader :status
+
+    # [public]
+    #
+    private def set_status(status)
+      @status = status
+      status_changed
+    end
+
+    # [public]
+    #
+    def update_status
+      # noop
+    end
+
+    private def status_changed
+      case @status
+      when :ready
+        @routine.bridged
+      when :finished
+        @channel.remove_observer(self)
+        @routine.unbridge
+      end
+    end
+
+    def channel_received
+      update_status
+    end
+
+    def channel_read
+      update_status
+    end
+
+    def channel_closed
+      update_status
+    end
+  end
+end

data/lib/goru/bridges/readable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../bridge"
+
+module Goru
+  module Bridges
+    class Readable < Bridge
+      private def update_status
+        status = if @routine.status == :finished
+          :finished
+        elsif @channel.full?
+          :idle
+        elsif @channel.closed?
+          :finished
+        else
+          :ready
+        end
+
+        set_status(status)
+      end
+    end
+  end
+end

data/lib/goru/bridges/writable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../bridge"
+
+module Goru
+  module Bridges
+    class Writable < Bridge
+      private def update_status
+        status = if @routine.status == :finished
+          :finished
+        elsif @channel.any?
+          :ready
+        elsif @channel.closed?
+          :finished
+        else
+          :idle
+        end
+
+        set_status(status)
+      end
+    end
+  end
+end

data/lib/goru/reactor.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 require "nio"
-
 require "timers/group"
 require "timers/wait"
 
-require_relative "routines/bridge"
 require_relative "routines/io"
 
 module Goru
@@ -16,12 +14,11 @@ module Goru
       @queue = queue
       @scheduler = scheduler
       @routines = Set.new
-      @bridges = Set.new
       @timers = Timers::Group.new
-      @selector = NIO::Selector.new
       @stopped = false
       @status = nil
-      @mutex = Mutex.new
+      @selector = NIO::Selector.new
+      @commands = []
     end
 
     # [public]
@@ -31,169 +28,140 @@ module Goru
     # [public]
     #
     def run
-      until @stopped
-        set_status(:running)
-
-        @routines.each do |routine|
-          call_routine(routine)
-        end
+      set_status(:running)
 
-        begin
-          wait_for_routine(block: false)
-        rescue ThreadError
-          interval = @timers.wait_interval
-
-          if interval.nil?
-            if @routines.empty?
-              if @selector.empty?
-                become_idle
-              else
-                wait_for_bridge do
-                  wait_for_selector
-                end
-              end
-            else
-              wait_for_bridge do
-                wait_for_selector(0)
-              end
-            end
-          elsif interval > 0
-            if @selector.empty?
-              wait_for_interval(interval)
-            else
-              wait_for_bridge do
-                wait_for_selector(interval)
-              end
-            end
-          end
-
-          @timers.fire
-        end
+      until @stopped
+        tick
       end
     ensure
+      @timers.cancel
       @selector.close
       set_status(:finished)
     end
 
-    private def become_idle
-      set_status(:idle)
-      @scheduler.signal(self)
-      wait_for_routine
-    end
-
-    private def wait_for_selector(timeout = nil)
-      @selector.select(timeout) do |monitor|
-        monitor.value.call
+    private def tick
+      # Apply queued commands.
+      #
+      while (command = @commands.shift)
+        action, routine = command
+
+        case action
+        when :adopt
+          routine.reactor = self
+          @routines << routine
+          routine.adopted
+        when :cleanup
+          @routines.delete(routine)
+        when :register
+          monitor = @selector.register(routine.io, routine.intent)
+          monitor.value = routine.method(:wakeup)
+          routine.monitor = monitor
+        when :deregister
+          routine.monitor&.close
+          routine.monitor = nil
+        end
       end
-    end
 
-    private def wait_for_bridge
-      if @bridges.any?(&:applicable?) && @bridges.none?(&:ready?)
-        wait_for_routine
-      else
-        yield
-      end
-    end
+      # Call each ready routine.
+      #
+      @routines.each do |routine|
+        next unless routine.ready?
 
-    private def wait_for_interval(timeout)
-      Timers::Wait.for(timeout) do |remaining|
-        break if wait_for_routine(timeout: remaining)
-      rescue ThreadError
-        # nothing to do
+        catch :continue do
+          routine.call
+        end
       end
-    end
 
-    private def wait_for_routine(block: true, timeout: nil)
-      if timeout
-        if (routine = @queue.pop(timeout: timeout))
-          adopt_routine(routine)
-        end
-      elsif (routine = @queue.pop(!block))
+      # Adopt a new routine if available.
+      #
+      if (routine = @queue.pop(true))
         adopt_routine(routine)
       end
+    rescue ThreadError
+      interval = @timers.wait_interval
+
+      if interval.nil? && @routines.empty?
+        set_status(:idle)
+        @scheduler.signal
+        wait
+        set_status(:running)
+      elsif interval.nil?
+        wait unless @routines.any?(&:ready?)
+      elsif interval > 0
+        wait(timeout: interval)
+      end
+
+      @timers.fire
     end
 
-    # [public]
-    #
-    def finished?
-      @mutex.synchronize do
-        @status == :idle || @status == :stopped
+    private def wait(timeout: nil)
+      @selector.select(timeout) do |monitor|
+        monitor.value.call
       end
     end
 
     # [public]
     #
-    def signal
-      unless @selector.empty?
-        @selector.wakeup
-      end
+    def finished?
+      @status == :idle || @status == :stopped
     end
 
     # [public]
     #
     def wakeup
-      signal
-      @queue << :wakeup
+      @selector.wakeup
+    rescue IOError
+      # nothing to do
     end
 
     # [public]
     #
     def stop
       @stopped = true
-      @selector.wakeup
-    rescue IOError
+      wakeup
+    rescue ClosedQueueError
+      # nothing to do
     end
 
     # [public]
     #
-    def routine_asleep(routine, seconds)
+    def asleep_for(seconds)
       @timers.after(seconds) {
-        routine.wake
+        yield
       }
     end
 
     # [public]
     #
     def adopt_routine(routine)
-      case routine
-      when Routines::IO
-        monitor = @selector.register(routine.io, routine.intent)
-        monitor.value = routine
-        routine.monitor = monitor
-        routine.reactor = self
-      when Routines::Bridge
-        routine.reactor = self
-        @bridges << routine
-      when Routine
-        routine.reactor = self
-        @routines << routine
-      end
+      command(:adopt, routine)
     end
 
     # [public]
     #
     def routine_finished(routine)
-      case routine
-      when Routines::Bridge
-        @bridges.delete(routine)
-      when Routines::IO
-        @selector.deregister(routine.io)
-      else
-        @routines.delete(routine)
-      end
+      command(:cleanup, routine)
     end
 
-    private def set_status(status)
-      @mutex.synchronize do
-        @status = status
-      end
+    # [public]
+    #
+    def register(routine)
+      command(:register, routine)
     end
 
-    private def call_routine(routine)
-      case routine.status
-      when :ready
-        routine.call
-      end
+    # [public]
+    #
+    def deregister(routine)
+      command(:deregister, routine)
+    end
+
+    private def command(action, routine)
+      @commands << [action, routine]
+      wakeup
+    end
+
+    private def set_status(status)
+      @status = status
     end
   end
 end

data/lib/goru/routine.rb

@@ -53,10 +53,10 @@ module Goru
     # [public]
     #
     def finished(result = nil)
-      unless @finished
-        @result = result
-        set_status(:finished)
-      end
+      @result = result
+      set_status(:finished)
+
+      throw :continue
     end
 
     # [public]
@@ -80,13 +80,17 @@ module Goru
     #
     def sleep(seconds)
       set_status(:idle)
-      @reactor.routine_asleep(self, seconds)
+      @reactor.asleep_for(seconds) do
+        set_status(:ready)
+      end
+
+      throw :continue
     end
 
     # [public]
     #
-    def wake
-      set_status(:ready)
+    def ready?
+      @status == :ready
     end
 
     # [public]
@@ -104,5 +108,11 @@ module Goru
         @reactor&.routine_finished(self)
       end
     end
+
+    # [public]
+    #
+    def adopted
+      # noop
+    end
   end
 end

data/lib/goru/routines/channel.rb

@@ -12,6 +12,7 @@ module Goru
 
         @channel = channel
         @channel.add_observer(self)
+        update_status
       end
 
       private def status_changed

data/lib/goru/routines/channels/readable.rb

@@ -8,12 +8,6 @@ module Goru
       # [public]
       #
       class Readable < Channel
-        def initialize(...)
-          super
-
-          update_status
-        end
-
         # [public]
         #
         def read

data/lib/goru/routines/channels/writable.rb

@@ -8,12 +8,6 @@ module Goru
       # [public]
       #
       class Writable < Channel
-        def initialize(...)
-          super
-
-          update_status
-        end
-
         # [public]
         #
         def <<(message)

data/lib/goru/routines/io.rb

@@ -1,51 +1,87 @@
 # frozen_string_literal: true
 
 require_relative "../routine"
-require_relative "bridges/readable"
-require_relative "bridges/writable"
+require_relative "../bridges/readable"
+require_relative "../bridges/writable"
 
 module Goru
   module Routines
     # [public]
     #
     class IO < Routine
-      def initialize(state = nil, io:, intent:, &block)
+      def initialize(state = nil, io:, intent:, event_loop:, &block)
         super(state, &block)
 
         @io = io
         @intent = normalize_intent(intent)
-        @status = :selecting
+        @event_loop = event_loop
+        @status = :orphaned
         @monitor = nil
-        @finishers = []
       end
 
       # [public]
       #
       attr_reader :io, :intent
 
-      attr_writer :monitor
+      attr_accessor :monitor
+
+      # [public]
+      #
+      def adopted
+        set_status(:ready)
+      end
+
+      # [public]
+      #
+      def wakeup
+        # Keep this io from being selected again until the underlying routine is called.
+        # Interests are reset in `#call`.
+        #
+        @monitor&.interests = nil
+
+        set_status(:io_ready)
+      end
+
+      READY_STATUSES = [:io_ready, :ready].freeze
+      READY_BRIDGE_STATUSES = [nil, :ready].freeze
+
+      # [public]
+      #
+      def ready?
+        READY_STATUSES.include?(@status) && READY_BRIDGE_STATUSES.include?(@bridge&.status)
+      end
+
+      def call
+        super
+
+        @monitor&.interests = @intent
+      end
 
       # [public]
       #
       def accept
         @io.accept_nonblock
+      rescue Errno::EAGAIN
+        wait
+      rescue Errno::ECONNRESET, Errno::EPIPE, EOFError
+        finished
+        nil
+      end
+
+      def wait
+        set_status(:selecting)
+        @reactor.register(self) unless @monitor
+
+        throw :continue
       end
 
       # [public]
       #
       def read(bytes)
-        result = @io.read_nonblock(bytes, exception: false)
-
-        case result
-        when nil
-          finished
-          nil
-        when :wait_readable
-          # nothing to do
-        else
-          result
-        end
-      rescue Errno::ECONNRESET
+        @io.read_nonblock(bytes)
+      rescue Errno::EAGAIN
+        wait
+      rescue Errno::ECONNRESET, Errno::EPIPE, EOFError
         finished
         nil
       end
@@ -53,18 +89,10 @@ module Goru
       # [public]
       #
       def write(data)
-        result = @io.write_nonblock(data, exception: false)
-
-        case result
-        when nil
-          finished
-          nil
-        when :wait_writable
-          # nothing to do
-        else
-          result
-        end
-      rescue Errno::ECONNRESET
+        @io.write_nonblock(data)
+      rescue Errno::EAGAIN
+        wait
+      rescue Errno::ECONNRESET, Errno::EPIPE, EOFError
         finished
         nil
       end
@@ -75,38 +103,56 @@ module Goru
         intent = normalize_intent(intent)
         validate_intent!(intent)
 
-        @monitor.interests = intent
+        @monitor&.interests = intent
         @intent = intent
       end
 
       # [public]
       #
-      def bridge(channel, intent:)
+      def bridge(state = nil, intent:, channel:, &block)
+        raise "routine is already bridged" if @bridge
+
         intent = normalize_intent(intent)
         validate_intent!(intent)
+        self.intent = intent
 
-        bridge = case intent
+        @bridge = case intent
         when :r
           Bridges::Readable.new(routine: self, channel: channel)
         when :w
           Bridges::Writable.new(routine: self, channel: channel)
         end
 
-        on_finished { bridge.finished }
-        @reactor.adopt_routine(bridge)
-        bridge
+        routine = case intent
+        when :r
+          Routines::Channels::Readable.new(state, channel: channel, &block)
+        when :w
+          Routines::Channels::Writable.new(state, channel: channel, &block)
+        end
+
+        @reactor.adopt_routine(routine)
+        @reactor.wakeup
+
+        routine
+      end
+
+      # [public]
+      #
+      def bridged
+        @reactor.wakeup
       end
 
       # [public]
       #
-      def on_finished(&block)
-        @finishers << block
+      def unbridge
+        @bridge = nil
+        @reactor.wakeup
       end
 
       private def status_changed
         case @status
         when :finished
-          @finishers.each(&:call)
+          @reactor&.deregister(self)
         end
 
         super

data/lib/goru/scheduler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "etc"
+require "nio"
 require "is/global"
 
 require_relative "channel"
@@ -16,7 +17,6 @@ module Goru
   #
   class Scheduler
     include Is::Global
-    include MonitorMixin
 
     class << self
       # Prevent issues when including `Goru` at the toplevel.
@@ -29,17 +29,18 @@ module Goru
 
       # [public]
       #
-      def default_scheduler_count
+      def default_reactor_count
         Etc.nprocessors
       end
     end
 
-    def initialize(count: self.class.default_scheduler_count)
+    def initialize(count: self.class.default_reactor_count)
       super()
 
-      @stopping = false
+      @waiting = false
+      @stopped = false
       @routines = Thread::Queue.new
-      @condition = new_cond
+      @selector = NIO::Selector.new
 
       @reactors = count.times.map {
         Reactor.new(queue: @routines, scheduler: self)
@@ -60,7 +61,7 @@ module Goru
       raise ArgumentError, "cannot set both `io` and `channel`" if io && channel
 
       routine = if io
-        Routines::IO.new(state, io: io, intent: intent, &block)
+        Routines::IO.new(state, io: io, intent: intent, event_loop: @io_event_loop, &block)
       elsif channel
         case intent
         when :r
@@ -73,7 +74,7 @@ module Goru
       end
 
       @routines << routine
-      @reactors.each(&:signal)
+      @reactors.each(&:wakeup)
 
       routine
     end
@@ -81,12 +82,11 @@ module Goru
     # [public]
     #
     def wait
-      synchronize do
-        @condition.wait_until do
-          @stopping
-        end
-      end
-    rescue Interrupt
+      @waiting = true
+      @reactors.each(&:wakeup)
+      @selector.select while @waiting
+    rescue IOError, Interrupt
+      # nothing to do
     ensure
       stop
     end
@@ -94,22 +94,25 @@ module Goru
     # [public]
     #
     def stop
-      @stopping = true
+      @stopped = true
       @routines.close
+      @selector.close
       @reactors.each(&:stop)
       @threads.each(&:join)
     end
 
     # [public]
     #
-    def signal(reactor)
-      synchronize do
-        if @reactors.all?(&:finished?)
-          @stopping = true
-        end
+    def signal
+      return unless @waiting && @reactors.all?(&:finished?)
+      @waiting = false
+      wakeup
+    end
 
-        @condition.signal
-      end
+    def wakeup
+      @selector.wakeup
+    rescue IOError
+      # nothing to do
     end
   end
 end

data/lib/goru/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Goru
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 
   # [public]
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: goru
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bryan Powell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-01 00:00:00.000000000 Z
+date: 2023-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: core-extension
@@ -90,12 +90,12 @@ files:
 - LICENSE
 - README.md
 - lib/goru.rb
+- lib/goru/bridge.rb
+- lib/goru/bridges/readable.rb
+- lib/goru/bridges/writable.rb
 - lib/goru/channel.rb
 - lib/goru/reactor.rb
 - lib/goru/routine.rb
-- lib/goru/routines/bridge.rb
-- lib/goru/routines/bridges/readable.rb
-- lib/goru/routines/bridges/writable.rb
 - lib/goru/routines/channel.rb
 - lib/goru/routines/channels/readable.rb
 - lib/goru/routines/channels/writable.rb
@@ -121,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.9
+rubygems_version: 3.4.12
 signing_key:
 specification_version: 4
 summary: Concurrent routines for Ruby.

data/lib/goru/routines/bridge.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../routine"
-
-module Goru
-  module Routines
-    # [public]
-    #
-    class Bridge < Routine
-      def initialize(state = nil, routine:, channel:, &block)
-        super(state, &block)
-
-        @routine = routine
-        @channel = channel
-        @channel.add_observer(self)
-      end
-
-      # [public]
-      #
-      def ready?
-        @status == :ready
-      end
-
-      private def status_changed
-        case @status
-        when :finished
-          @channel.remove_observer(self)
-        end
-
-        super
-      end
-
-      def channel_received
-        update_status
-      end
-
-      def channel_read
-        update_status
-      end
-
-      def channel_closed
-        update_status
-      end
-    end
-  end
-end

data/lib/goru/routines/bridges/readable.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../bridge"
-
-module Goru
-  module Routines
-    module Bridges
-      class Readable < Bridge
-        def initialize(...)
-          super
-
-          update_status
-        end
-
-        # [public]
-        #
-        def applicable?
-          @routine.intent == :r
-        end
-
-        private def update_status
-          status = if @routine.status == :finished
-            :finished
-          elsif @channel.full?
-            :idle
-          elsif @channel.closed?
-            :finished
-          else
-            :ready
-          end
-
-          set_status(status)
-        end
-      end
-    end
-  end
-end

data/lib/goru/routines/bridges/writable.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../bridge"
-
-module Goru
-  module Routines
-    module Bridges
-      class Writable < Bridge
-        def initialize(...)
-          super
-
-          update_status
-        end
-
-        # [public]
-        #
-        def applicable?
-          @routine.intent == :w
-        end
-
-        private def update_status
-          status = if @routine.status == :finished
-            :finished
-          elsif @channel.any?
-            :ready
-          elsif @channel.closed?
-            :finished
-          else
-            :idle
-          end
-
-          set_status(status)
-        end
-      end
-    end
-  end
-end