concurrent-ruby 1.2.0 → 1.2.3

data/lib/concurrent-ruby/concurrent/timer_task.rb

@@ -32,6 +32,17 @@ module Concurrent
   # be tested separately then passed to the `TimerTask` for scheduling and
   # running.
   #
+  # A `TimerTask` supports two different types of interval calculations.
+  # A fixed delay will always wait the same amount of time between the
+  # completion of one task and the start of the next. A fixed rate will
+  # attempt to maintain a constant rate of execution regardless of the
+  # duration of the task. For example, if a fixed rate task is scheduled
+  # to run every 60 seconds but the task itself takes 10 seconds to
+  # complete, the next task will be scheduled to run 50 seconds after
+  # the start of the previous task. If the task takes 70 seconds to
+  # complete, the next task will be start immediately after the previous
+  # task completes. Tasks will not be executed concurrently.
+  #
   # In some cases it may be necessary for a `TimerTask` to affect its own
   # execution cycle. To facilitate this, a reference to the TimerTask instance
   # is passed as an argument to the provided block every time the task is
@@ -74,6 +85,12 @@ module Concurrent
   #
   #   #=> 'Boom!'
   #
+  # @example Configuring `:interval_type` with either :fixed_delay or :fixed_rate, default is :fixed_delay
+  #   task = Concurrent::TimerTask.new(execution_interval: 5, interval_type: :fixed_rate) do
+  #          puts 'Boom!'
+  #        end
+  #   task.interval_type #=> :fixed_rate
+  #
   # @example Last `#value` and `Dereferenceable` mixin
   #   task = Concurrent::TimerTask.new(
   #     dup_on_deref: true,
@@ -87,7 +104,7 @@ module Concurrent
   #
   # @example Controlling execution from within the block
   #   timer_task = Concurrent::TimerTask.new(execution_interval: 1) do |task|
-  #     task.execution_interval.times{ print 'Boom! ' }
+  #     task.execution_interval.to_i.times{ print 'Boom! ' }
   #     print "\n"
   #     task.execution_interval += 1
   #     if task.execution_interval > 5
@@ -96,7 +113,7 @@ module Concurrent
   #     end
   #   end
   #
-  #   timer_task.execute # blocking call - this task will stop itself
+  #   timer_task.execute
   #   #=> Boom!
   #   #=> Boom! Boom!
   #   #=> Boom! Boom! Boom!
@@ -152,18 +169,30 @@ module Concurrent
     # Default `:execution_interval` in seconds.
     EXECUTION_INTERVAL = 60
 
-    # Default `:timeout_interval` in seconds.
-    TIMEOUT_INTERVAL = 30
+    # Maintain the interval between the end of one execution and the start of the next execution.
+    FIXED_DELAY = :fixed_delay
+
+    # Maintain the interval between the start of one execution and the start of the next.
+    # If execution time exceeds the interval, the next execution will start immediately
+    # after the previous execution finishes. Executions will not run concurrently.
+    FIXED_RATE = :fixed_rate
+
+    # Default `:interval_type`
+    DEFAULT_INTERVAL_TYPE = FIXED_DELAY
 
     # Create a new TimerTask with the given task and configuration.
     #
     # @!macro timer_task_initialize
     #   @param [Hash] opts the options defining task execution.
-    #   @option opts [Integer] :execution_interval number of seconds between
+    #   @option opts [Float] :execution_interval number of seconds between
     #     task executions (default: EXECUTION_INTERVAL)
     #   @option opts [Boolean] :run_now Whether to run the task immediately
     #     upon instantiation or to wait until the first #  execution_interval
     #     has passed (default: false)
+    #   @options opts [Symbol] :interval_type method to calculate the interval
+    #     between executions, can be either :fixed_rate or :fixed_delay.
+    #     (default: :fixed_delay)
+    #   @option opts [Executor] executor, default is `global_io_executor`
     #
     #   @!macro deref_options
     #
@@ -242,6 +271,10 @@ module Concurrent
       end
     end
 
+    # @!attribute [r] interval_type
+    # @return [Symbol] method to calculate the interval between executions
+    attr_reader :interval_type
+
     # @!attribute [rw] timeout_interval
     # @return [Fixnum] Number of seconds the task can run before it is
     #   considered to have failed.
@@ -264,11 +297,17 @@ module Concurrent
       set_deref_options(opts)
 
       self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
+      if opts[:interval_type] && ![FIXED_DELAY, FIXED_RATE].include?(opts[:interval_type])
+        raise ArgumentError.new('interval_type must be either :fixed_delay or :fixed_rate')
+      end
       if opts[:timeout] || opts[:timeout_interval]
         warn 'TimeTask timeouts are now ignored as these were not able to be implemented correctly'
       end
+
       @run_now = opts[:now] || opts[:run_now]
-      @executor = Concurrent::SafeTaskExecutor.new(task)
+      @interval_type = opts[:interval_type] || DEFAULT_INTERVAL_TYPE
+      @task = Concurrent::SafeTaskExecutor.new(task)
+      @executor = opts[:executor] || Concurrent.global_io_executor
       @running = Concurrent::AtomicBoolean.new(false)
       @value = nil
 
@@ -289,17 +328,18 @@ module Concurrent
 
     # @!visibility private
     def schedule_next_task(interval = execution_interval)
-      ScheduledTask.execute(interval, args: [Concurrent::Event.new], &method(:execute_task))
+      ScheduledTask.execute(interval, executor: @executor, args: [Concurrent::Event.new], &method(:execute_task))
       nil
     end
 
     # @!visibility private
     def execute_task(completion)
       return nil unless @running.true?
-      _success, value, reason = @executor.execute(self)
+      start_time = Concurrent.monotonic_time
+      _success, value, reason = @task.execute(self)
       if completion.try?
         self.value = value
-        schedule_next_task
+        schedule_next_task(calculate_next_interval(start_time))
         time = Time.now
         observers.notify_observers do
           [time, self.value, reason]
@@ -307,5 +347,15 @@ module Concurrent
       end
       nil
     end
+
+    # @!visibility private
+    def calculate_next_interval(start_time)
+      if @interval_type == FIXED_RATE
+        run_time = Concurrent.monotonic_time - start_time
+        [execution_interval - run_time, 0].max
+      else # FIXED_DELAY
+        execution_interval
+      end
+    end
   end
 end

data/lib/concurrent-ruby/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '1.2.0'
+  VERSION = '1.2.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: concurrent-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.3
 platform: ruby
 authors:
 - Jerry D'Antonio
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-23 00:00:00.000000000 Z
+date: 2024-01-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   Modern concurrency tools including agents, futures, promises, thread pools, actors, supervisors, and more.
@@ -76,7 +76,6 @@ files:
 - lib/concurrent-ruby/concurrent/collection/copy_on_write_observer_set.rb
 - lib/concurrent-ruby/concurrent/collection/java_non_concurrent_priority_queue.rb
 - lib/concurrent-ruby/concurrent/collection/lock_free_stack.rb
-- lib/concurrent-ruby/concurrent/collection/map/atomic_reference_map_backend.rb
 - lib/concurrent-ruby/concurrent/collection/map/mri_map_backend.rb
 - lib/concurrent-ruby/concurrent/collection/map/non_concurrent_map_backend.rb
 - lib/concurrent-ruby/concurrent/collection/map/synchronized_map_backend.rb
@@ -147,7 +146,6 @@ files:
 - lib/concurrent-ruby/concurrent/thread_safe/synchronized_delegator.rb
 - lib/concurrent-ruby/concurrent/thread_safe/util.rb
 - lib/concurrent-ruby/concurrent/thread_safe/util/adder.rb
-- lib/concurrent-ruby/concurrent/thread_safe/util/cheap_lockable.rb
 - lib/concurrent-ruby/concurrent/thread_safe/util/data_structures.rb
 - lib/concurrent-ruby/concurrent/thread_safe/util/power_of_two_tuple.rb
 - lib/concurrent-ruby/concurrent/thread_safe/util/striped64.rb