concurrent_monitor 0.0.1.ci.release → 0.9.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb40509148c10d59f1faf6655bd3bb5caf6bc2afc17dc7a3e63b7bfae6d04d1
-  data.tar.gz: 071b45c7a8e404b2d8fa6c175355ae8066bdc8693cdff951fce12d07dc2865bd
+  metadata.gz: 6d2a561842bcf407eb933762b7d48f9033b7b4c7d45dc6c042055b689b1ed6b8
+  data.tar.gz: f2de6f5698c4392c16c089cd9556e3942ab947a9459942d4e3757d2872963a18
 SHA512:
-  metadata.gz: 9ec7055d648bb1f10c4f74e28fc0b4d7f2ddbdad9df2851b88ee2f5af2c7cc60cf12ddbd2235e3e45eaadbc78b221bc5a693ec76a44f411866e4b96333c6c025
-  data.tar.gz: 10717aee9fa99a78e800e53bf258e0634e4c7ca81d6f399ebdcecd62701348fb4847c77b14ce340a89076f979c0289eee969348bd3cf7a9d07aae210a4a576f0
+  metadata.gz: 17403d800fd04ce45099243c267027755f18d24b7bb84f9fdd798c3bba4dab384978d40a76df8dba397b14978207d00a6e9c3d031bbb6dc286a81234c1a6f407
+  data.tar.gz: 68fff665dfa471b808bafbdf4b27fe6d423ea9a5ad0405330520f21a1fff6c3f3dbd8410a91a34c5f61ca4e77aa0da3def2081c7bb9c18f9c6f542182ed58ab4

data/lib/async/monitor.rb

@@ -10,12 +10,16 @@ module Async
   class Monitor
     # Common task interface over Async::Task
     class Task < ConcurrentMonitor::Task
-      def initialize(name = nil, report_on_exception: true, &block)
+      def initialize(name_arg = nil, name: name_arg, report_on_exception: true, &block)
         super()
-        Async(annotation: name, finished: report_on_exception ? nil : Async::Condition.new) do |task|
-          @task = task
-          Fiber.current.concurrent_monitor_task = self
-          block.call(self)
+        if block_given?
+          Async(annotation: name, finished: report_on_exception ? nil : false) do |task|
+            @task = task
+            Fiber.current.concurrent_monitor_task = self
+            block.call(self)
+          end
+        else
+          @task = Async::Task.current
         end
       end
 
@@ -23,7 +27,12 @@ module Async
 
       def current? = @task.current?
 
-      def value = @task.wait
+      def value
+        result = @task.wait
+        raise ConcurrentMonitor::TaskStopped, 'Task was stopped' if @task.stopped?
+
+        result
+      end
 
       def stop
         raise Async::Stop if current?
@@ -56,7 +65,7 @@ module Async
       end
 
       def current_task
-        Fiber.current.concurrent_monitor_task
+        Fiber.current.concurrent_monitor_task ||= Task.new
       end
 
       def new_monitor

data/lib/concurrent_monitor/barrier.rb

@@ -43,7 +43,7 @@ module ConcurrentMonitor
     # @param [:to_s] name
     # @param [Boolean] report_on_exception
     # @return [Task]
-    def async(name = nil, report_on_exception: false, &)
+    def async(name_arg = nil, name: name_arg, report_on_exception: false, &)
       synchronize { monitor.async(name, report_on_exception:) { |t| run_task(t, &) }.tap { |t| tasks << t } }
     end
 
@@ -74,8 +74,9 @@ module ConcurrentMonitor
       return enum_for(:each).lazy unless block_given?
 
       each_task do |t|
-        v = t.value
-        yield v unless t.stopped?
+        yield t.value
+      rescue TaskStopped
+        # skip stopped tasks
       end
     end
 
@@ -96,6 +97,11 @@ module ConcurrentMonitor
       (block_given? ? yield(self) : self).tap { each(&:itself) }
     end
 
+    # The value of a barrier is the array of values of all its tasks.
+    def value
+      to_a
+    end
+
     # {#wait}, ensuring {#stop}
     def wait!(&) = ensure_stop { wait(&) }
 

data/lib/concurrent_monitor/future.rb

@@ -11,7 +11,8 @@ module ConcurrentMonitor
       @error = nil
     end
 
-    # Blocks until the future is completed or the timeout expires
+    # Blocks until the future is completed, then returns its value or raises its error.
+    #
     # @return [Object] The value with which the future was fulfilled
     # @raise [StandardError] If the future was rejected
     def value
@@ -21,8 +22,13 @@ module ConcurrentMonitor
       @value
     end
 
-    def wait(timeout = nil, **wait_opts)
-      synchronize { condition.wait_until(timeout, **wait_opts) { @completed } }
+    # Wait until completed
+    # @overload wait(timeout, exception: nil)
+    #  @param timeout [Numeric|nil]
+    #  @param exception [Class<StandardError>]an error to raise if timeout
+    #  @return [Boolean] true if completed, nil or raises exception if timed out
+    def wait(timeout_arg = nil, timeout: timeout_arg, exception: nil)
+      synchronize { condition.wait_until(timeout, exception:) { @completed } }
     end
 
     # Resolve the future with a block
@@ -41,6 +47,11 @@ module ConcurrentMonitor
       complete! { @value = value }
     end
 
+    # @return [Boolean] true if completed with a value, otherwise false
+    def fulfilled?
+      completed? && !@error
+    end
+
     # Rejects this future with the given error
     # @param error [Exception] The error to reject this future with
     # @return [Boolean] true if the future was rejected, false if already completed
@@ -49,10 +60,17 @@ module ConcurrentMonitor
       complete! { @error = error }
     end
 
+    # @return [Boolean] false if not complete or completed with a value
+    # @return [StandardError] if completed with an error
+    def rejected?
+      completed? && @error
+    end
+
     # @return [Boolean] true if this future has been completed
     def completed?
       synchronize { @completed }
     end
+    alias resolved? completed?
 
     # @return [Boolean] true if this future has not yet been completed
     def pending?

data/lib/concurrent_monitor/semaphore.rb

@@ -37,7 +37,7 @@ module ConcurrentMonitor
     end
 
     # Start a task, blocking until the semaphore can be acquired
-    def async(name = nil, report_on_exception: true, &)
+    def async(name_arg = nil, name: name_arg, report_on_exception: true, &)
       synchronize do
         @condition.wait_while { @task_count >= @limit }
         @task_count += 1

data/lib/concurrent_monitor/task.rb

@@ -3,32 +3,53 @@
 require_relative 'wait_timeout'
 
 module ConcurrentMonitor
+  # Raised when calling #value on a stopped task
+  class TaskStopped < StandardError; end
+
   # @abstract
   # Common interface to underlying tasks
   class Task
     # @!method value
-    #  Wait for task to complete and return its value
+    #  Wait for task to complete and return its value, or raise its error
     #  @return [Object]
+    #  @raise [TaskStopped] if the task was explicitly {#stop stopped} (Thread API)
     #  @raise [StandardError]
 
-    # Wait for task to complete
-    # @return [self]
+    # Wait for task to complete and return its value, or raise its error
+    # @return [Object]
+    # @return [nil] if the task was explicitly {#stop stopped} (Async::Task API)
+    # @raise [StandardError] if task raised an exception
+    # @see stopped?
     def wait
       value
-      self
+    rescue TaskStopped
+      nil
     end
 
-    alias join wait
+    # Wait for task to complete and return self (Thread API)
+    # @return [self]
+    # @raise [TaskStopped] if task was stopped
+    # @raise [StandardError] if task raised an exception
+    def join
+      value
+      self
+    end
 
     # @!method stop
     #  @return [self] after stopping
     #  @raise [Exception] if called from the current task
 
     # @!method stopped?
+    #  Check if task was stopped.
+    #
+    #  A false result is ambiguous unless the calling task has called {#wait} (or rescued {TaskStopped} from a call to
+    #  {#value}/{#join})
     #  @return [Boolean] true if the task has completed via stop.
 
     # @!method alive?
-    #  @return [Boolean] true if the task has not reached completion (as seen by the calling task)
+    #  A true result is ambiguous unless the calling task has called {#wait} (or rescued {TaskStopped} from a call to
+    #  {#value}/{#join})
+    #  @return [Boolean] true if the task has not reached completion
 
     # @!method current?
     #  @return [Boolean] true if this task is the current thread/fiber

data/lib/concurrent_monitor/timeout_clock.rb

@@ -23,12 +23,12 @@ module ConcurrentMonitor
       # Create a TimeoutClock and wait until block is true. See {#wait_until}
       # @example
       #   TimeoutClock.wait_until(60) { closed? || (sleep(1) && false)}
-      def wait_until(timeout = nil, delay: nil, exception: nil, &)
+      def wait_until(timeout_arg = nil, timeout: timeout_arg, delay: nil, exception: nil, &)
         timeout(timeout).wait_until(exception:, delay:, &)
       end
 
       # Create a TimeoutClock and wait while block is true. See {#wait_while}
-      def wait_while(timeout = nil, delay: nil, exception: nil, &)
+      def wait_while(timeout_arg = nil, timeout: timeout_arg, delay: nil, exception: nil, &)
         timeout(timeout).wait_while(exception:, delay:, &)
       end
     end
@@ -86,7 +86,7 @@ module ConcurrentMonitor
             return result
           end
 
-          sleep([delay, self.remaining].min) if delay
+          sleep([delay, self.remaining || delay].min) if delay
         end
 
         raise exception, 'timed out' if exception

data/lib/concurrent_monitor/timeout_watcher.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConcurrentMonitor
+  # Shared timeout watcher that manages timeouts for multiple tasks efficiently.
+  # Caller is responsible for starting the watcher task.
+  class TimeoutWatcher
+    attr_reader :monitor
+
+    include ConcurrentMonitor
+
+    # @param monitor [ConcurrentMonitor::Mixin] the monitor for synchronization
+    def initialize(monitor:)
+      @monitor = monitor
+      @timeouts = {}
+      @condition = monitor.new_condition
+    end
+
+    # Wrap a block with timeout. Spawns the block in a new task, registers it for timeout,
+    # and ensures timeout is cancelled on completion.
+    # @param timeout [Numeric] seconds until timeout
+    # @yield block to execute
+    # @return [Task] the spawned task
+    def with_timeout(timeout_arg = nil, timeout: timeout_arg, **, &block)
+      async(**async) do |t|
+        watch(t, timeout: timeout) if timeout
+        block.call(t)
+      ensure
+        cancel_timeout(t) if timeout
+      end
+    end
+
+    # Cancel timeout for task
+    def cancel_timeout(task = current_task)
+      synchronize { @timeouts.delete(task) }
+    end
+
+    # Run the watcher loop. Caller should spawn this in a task.
+    # @example
+    #   watcher = TimeoutWatcher.new(monitor: self)
+    #   watcher_task = async(name: 'timeout_watcher') { watcher.run }
+    def run
+      until @stopped
+        synchronize do
+          @timeouts.delete_if { |task, clock| clock.expired?.tap { |expired| task.stop if expired } }
+          @condition.wait(@timeouts.values.map(&:remaining).compact.min)
+        end
+      end
+    end
+
+    def stop
+      synchronize do
+        @stopped = true
+        @condition.broadcast
+      end
+    end
+
+    private
+
+    # Register task to be stopped after timeout
+    def watch(task, timeout:)
+      clock = self.timeout(timeout)
+
+      synchronize do
+        @timeouts[task] = clock
+        @condition.broadcast
+      end
+    end
+  end
+end

data/lib/concurrent_monitor/version.rb

@@ -2,5 +2,5 @@
 
 # A unified Monitor interface for both Async (fibers) and Threads.
 module ConcurrentMonitor
-  VERSION = '0.0.1'
+  VERSION = '0.9.0'
 end

data/lib/concurrent_monitor/wait_timeout.rb

@@ -11,7 +11,7 @@ module ConcurrentMonitor
     # @param [Exception|nil] exception an exception to raise on timeout
     # @return [Object] the truthy return value of the block
     # @return [nil] if a timeout occurs
-    def wait_until(timeout = nil, exception: nil)
+    def wait_until(timeout_arg = nil, timeout: timeout_arg, exception: nil)
       TimeoutClock.wait_until(timeout, exception:) { |remaining| yield || (wait(remaining) && false) }
     end
 

data/lib/concurrent_monitor.rb

@@ -6,6 +6,7 @@ require_relative 'concurrent_monitor/condition_variable'
 require_relative 'concurrent_monitor/queue'
 require_relative 'concurrent_monitor/barrier'
 require_relative 'concurrent_monitor/future'
+require_relative 'concurrent_monitor/timeout_watcher'
 require 'forwardable'
 
 # A unified abstraction layer for synchronization and concurrency primitives that works
@@ -45,7 +46,7 @@ module ConcurrentMonitor
 
   # @!attribute [rw] monitor
   #   @return [Async::Monitor,Thread::Monitor] should be set to an instance of Async::Monitor or Thread::Monitor
-  def_delegators :@monitor, :sync, :async, :current_task, :synchronize, :new_condition, :task_dump
+  def_delegators :@monitor, :sync, :async, :current_task, :synchronize, :new_condition, :new_monitor, :task_dump
 
   # @!method new_monitor
   #   @return [Async::Monitor|Thread::Monitor] a new monitor of the same kind as the current one
@@ -83,9 +84,9 @@ module ConcurrentMonitor
   # @param [Numeric|TimeoutClock] timeout
   # @param [Class|StandardError|nil] exception if set the error to raise on timeout
   # @return [Object] task result, nil if timed out without exception
-  def with_timeout(timeout, exception: nil, condition: new_condition, &block)
+  def with_timeout(timeout_arg, timeout: timeout_arg, exception: nil, condition: new_condition, **kw_async, &block)
     done = false
-    task = async do |t|
+    task = async(**kw_async) do |t|
       block.call(t)
     ensure
       synchronize do
@@ -95,7 +96,7 @@ module ConcurrentMonitor
     end
 
     begin
-      synchronize { condition.wait_until(timeout, exception:) { done } }
+      synchronize { condition.wait_until(timeout:, exception:) { done } }
     ensure
       task.stop
     end
@@ -123,6 +124,16 @@ module ConcurrentMonitor
     Future.new(monitor:)
   end
 
+  def new_semaphore(limit:, monitor: self)
+    Semaphore.new(monitor:, limit:)
+  end
+
+  # Creates a new timeout watcher
+  # @return [TimeoutWatcher]
+  def new_timeout_watcher(monitor: self)
+    TimeoutWatcher.new(monitor:)
+  end
+
   # @!attribute [rw] monitor
   #   @return [Thread::Monitor|Async::Monitor]
   attr_accessor :monitor

data/lib/thread/monitor.rb

@@ -10,7 +10,7 @@ class Thread
   class Monitor
     # rubocop:disable Lint/InheritException
 
-    # Raised from when a task is stopped
+    # Raised from stop when a task is stopped
     class Stop < Exception; end
 
     # rubocop:enable Lint/InheritException
@@ -23,17 +23,24 @@ class Thread
     # @!visibility private
     # Common task interface over Thread
     class Task < ConcurrentMonitor::Task
-      def initialize(name = nil, report_on_exception: true, &block)
+      def initialize(name_arg = nil, name: name_arg, report_on_exception: true, &block)
         super()
         @stopped = nil
-        @thread = Thread.new(self, name, report_on_exception, block) do |t, n, e, b|
-          run_thread(t, n, e, &b)
-        rescue Stop
-          @stopped = true
-          nil
-        ensure
-          @stopped ||= false
-        end
+
+        @thread =
+          if block_given?
+            Thread.new(self, name, report_on_exception, block) do |t, n, e, b|
+              run_thread(t, n, e, &b)
+            rescue Stop
+              @stopped = true
+              nil
+            ensure
+              @stopped ||= false
+            end
+          else
+            # this is the main thread
+            Thread.current.tap { |t| t.thread_variable_set(:concurrent_monitor_task, self) }
+          end
       end
 
       def alive? = @thread.alive?
@@ -41,12 +48,13 @@ class Thread
       def current? = @thread == Thread.current
 
       def value
-        return nil if @stopped
+        result = @thread.value
+        raise ConcurrentMonitor::TaskStopped, 'Task was stopped' if @stopped
 
-        @thread.value
+        result
       rescue Stop
         @stopped = true
-        nil
+        raise ConcurrentMonitor::TaskStopped, 'Task was stopped'
       end
 
       def stop
@@ -58,7 +66,7 @@ class Thread
         self # race with alive?
       end
 
-      # must call join or value before @stopped will be true
+      # must call wait before @stopped will be true
       def stopped?
         !!@stopped
       end
@@ -99,7 +107,7 @@ class Thread
       end
 
       def current_task
-        Thread.current.thread_variable_get(:concurrent_monitor_task)
+        Thread.current.thread_variable_get(:concurrent_monitor_task) || Task.new
       end
 
       def task_dump(io = $stderr)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: concurrent_monitor
 version: !ruby/object:Gem::Version
-  version: 0.0.1.ci.release
+  version: 0.9.0.rc1
 platform: ruby
 authors:
 - Grant Gardner
@@ -25,6 +25,7 @@ files:
 - lib/concurrent_monitor/semaphore.rb
 - lib/concurrent_monitor/task.rb
 - lib/concurrent_monitor/timeout_clock.rb
+- lib/concurrent_monitor/timeout_watcher.rb
 - lib/concurrent_monitor/version.rb
 - lib/concurrent_monitor/wait_timeout.rb
 - lib/thread/monitor.rb