ztimer 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ba1fe46353cca7319d61150f6fe52622d3668db2
-  data.tar.gz: ac6dc6b45e0001d39e63a6ead7950b5db75ac7d0
+SHA256:
+  metadata.gz: 328b728b6ba74021474c30ef9093a1bca987a368b2bd211d5545abc888447ef2
+  data.tar.gz: df0ff61ae1bbf3901a1ddc9fa0ac3416dce79eeb1c4e05f1d9a3f61abce722c0
 SHA512:
-  metadata.gz: 1eac7a0992c9d806a76c35cc31805bb716e7ca8b39e4b15b0609ac8c9415464c816b6b57a74821745b213ad57a9e21843f641b16663c19cf3e46d267b6216ce9
-  data.tar.gz: f81c9081bad5354bb6e0f056596b9c8db7ce5878d6ff6d1da5e82536c218e143c59ef60389bda4b27bed205d09881c35e6c7dccf28f8f15d7395cf487142fe00
+  metadata.gz: d482e9792d40f7083258a66cac5b1857624d02dbc6f4297a3ea608c48f8f50908dc3fe429e0666b54bd67b3b3e9b846f7869aa8ea253e980167bd2502cfd4626
+  data.tar.gz: d5b3ce5d4189739c8a32851383775afe84bd238d324dc26806e122f2b19fd9a4dd65509c9b04ded9aae399b3eeff19bb3a01377155408b680ed533261401b1a3

data/README.md

@@ -58,6 +58,20 @@ my_timer = Ztimer.new(concurrency: 5) # create a new Ztimer instance
 end
 ```
 
+| Method | Description  |
+|--------|-------------|
+| `async(&block)` | Execute the block asynchronously. |
+| `after(milliseconds, &block)` | Execute the block after the specified amount of milliseconds. |
+| `at(datetime, &block)` | Execute the block at the specified timestamp. |
+| `every(milliseconds, start_at: nil, &block)` | Execute the block at the specified interval of milliseconds. A custom `:start_at` param could be provided to specify an offset timestamp. |
+| `secondly(seconds, offset: 0, &block)` | Executes the block every N seconds. An `:offset` of seconds could be specified to shift the begining of the time slot. By default the block will be exected at the begining of the time slot. Example: `secondly(5)` will run at second `0`, `5`, `10`, `15`, etc. |
+| `minutely(minutes, offset: 0, &block)` | Executes the block every N minutes. An `:offset` of minutes could be specified to shift the begining of the time slot. By default the block will be exected at the begining of the time slot. Example: `minutely(5)` will run at minute `0`, `5`, `10`, `15`, etc. |
+| `hourly(hours, offset: 0, &block)` | Executes the block every N hours. An `:offset` of hours could be specified to shift the begining of the time slot. By default the block will be exected at the begining of the time slot. Example: `hourly(5)` will run at hour `0`, `5`, `10`, `15`, etc. |
+| `daily(days, offset: 0, &block)` | Executes the block every N days. An `:offset` of days could be specified to shift the begining of the time slot. By default the block will be exected at the begining of the time slot. Example: `daily(5)` will run on day `0`, `5`, `10`, `15`, etc. |
+| `day_of_week(day, &block)` | Execute the block only on the specified day of week. Valid days are: `"sun", "mon", "tue", "thu", "wen", "fri", "sat"`. |
+| `days_of_week(days, &block)` | Execute the block on the specified days of week. |
+
+
 By default **Ztimer** will run at maximum 20 jobs concurrently, so that if you have 100 jobs to be
 executed at the same time, at most 20 of them will run concurrently. This is necessary in order to prevent uncontrolled threads spawn when many jobs have to be run at the same time.
 

data/lib/ztimer/slot.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
 
 class Ztimer
+  # Implements a slot, which represents a block of code to be executed at specified time slot.
   class Slot
     attr_reader :enqueued_at, :expires_at, :recurrency, :callback
     attr_accessor :started_at, :executed_at
 
-    def initialize(enqueued_at, expires_at,recurrency = -1, &callback)
+    def initialize(enqueued_at, expires_at, recurrency = -1, &callback)
       @enqueued_at = enqueued_at
       @expires_at  = expires_at
       @recurrency  = recurrency
@@ -15,17 +17,15 @@ class Ztimer
     end
 
     def recurrent?
-      return @recurrency > 0
+      @recurrency.positive?
     end
 
     def reset!
-      if recurrent?
-        @expires_at += recurrency
-      end
+      @expires_at += recurrency if recurrent?
     end
 
     def canceled?
-      return @canceled
+      @canceled
     end
 
     def cancel!
@@ -33,7 +33,7 @@ class Ztimer
     end
 
     def <=>(other)
-      return @expires_at <=> other.expires_at
+      @expires_at <=> other.expires_at
     end
   end
 end

data/lib/ztimer/sorted_store.rb

@@ -1,95 +1,92 @@
+# frozen_string_literal: true
 
 class Ztimer
+  # Implements a performant sorted store for time slots, which uses binary search to optimize
+  # new items insertion and items retrievement.
   class SortedStore
-
     def initialize
       @store = []
     end
 
     def <<(value)
       @store.insert(position_for(value), value)
-      return self
+
+      self
     end
 
     def delete(value)
       index = index_of(value)
-      if index
-        @store.delete_at(index)
-      else
-        return nil
-      end
+
+      index.nil? ? nil : @store.delete_at(index)
     end
 
     def [](index)
-      return @store[index]
+      @store[index]
     end
 
     def first
-      return @store.first
+      @store.first
     end
 
     def last
-      return @store.last
+      @store.last
     end
 
     def shift
-      return @store.shift
+      @store.shift
     end
 
     def pop
-      return @store.pop
+      @store.pop
     end
 
     def index_of(value, start = 0, stop = [@store.count - 1, 0].max)
-      if start > stop
-        return nil
-      elsif start == stop
-        return value == @store[start] ? start : nil
-      else
-        position = ((stop + start)/ 2).to_i
-        case value <=> @store[position]
-        when -1 then return index_of(value, start, position)
-        when  0 then return position
-        when  1 then return index_of(value, position + 1, stop)
-        end
+      return nil if start > stop
+      return value == @store[start] ? start : nil if start == stop
+
+      position = ((stop + start) / 2).to_i
+
+      case value <=> @store[position]
+      when -1 then index_of(value, start, position)
+      when  0 then position
+      when  1 then index_of(value, position + 1, stop)
       end
     end
 
     def count
-      return @store.count
+      @store.count
     end
 
     def size
-      return @store.size
+      @store.size
     end
 
     def empty?
-      return @store.empty?
+      @store.empty?
     end
 
     def clear
-      return @store.clear
+      @store.clear
     end
 
     def to_a
-      return @store.dup
+      @store.dup
     end
 
-
     protected
 
     def position_for(item, start = 0, stop = [@store.count - 1, 0].max)
-      if start > stop
-        raise "Invalid range (#{start}, #{stop})"
-      elsif start == stop
+      raise "Invalid range (#{start}, #{stop})" if start > stop
+
+      if start == stop
         element = @store[start]
-        return element.nil? || ((item <=> element) <= 0) ? start : start + 1
+        element.nil? || ((item <=> element) <= 0) ? start : start + 1
       else
-        position = ((stop + start)/ 2).to_i
+        position = ((stop + start) / 2).to_i
         case item <=> @store[position]
-        when -1 then return position_for(item, start, position)
-        when  0 then return position
-        when  1 then return position_for(item, position + 1, stop)
+        when -1 then position_for(item, start, position)
+        when  0 then position
+        when  1 then position_for(item, position + 1, stop)
         end
       end
     end

data/lib/ztimer/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Ztimer
-  VERSION = "0.6.0"
+  VERSION = '1.0.0'
 end

data/lib/ztimer/watcher.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
 
 class Ztimer
+  # Implements a watcher which allows to enqueue Ztimer::Slot items, that will be executed
+  # as soon as the time of Ztimer::Slot is reached.
   class Watcher
-
     def initialize(&callback)
       @thread   = nil
       @slots    = Ztimer::SortedStore.new
@@ -10,17 +12,15 @@ class Ztimer
       @mutex    = Mutex.new
     end
 
-    def << (slot)
+    def <<(slot)
       @mutex.synchronize do
         @slots << slot
-        if @slots.first == slot
-          run
-        end
+        run if @slots.first == slot
       end
     end
 
     def jobs
-      return @slots.size
+      @slots.size
     end
 
     protected
@@ -37,10 +37,11 @@ class Ztimer
     def start
       @lock.synchronize do
         return if @thread
+
         @thread = Thread.new do
           loop do
             begin
-              delay = get_delay
+              delay = calculate_delay
               if delay.nil?
                 Thread.stop
                 next
@@ -48,10 +49,10 @@ class Ztimer
 
               select(nil, nil, nil, delay / 1_000_000.to_f) if delay > 1 # 1 microsecond of cranularity
 
-              while get_first_expired do
+              while fetch_first_expired
               end
-            rescue => e
-              puts e.inspect + "\n" + e.backtrace.join("\n")
+            rescue StandardError => e
+              puts "#{e.inspect}\n#{e.backtrace.join("\n")}"
             end
           end
         end
@@ -59,11 +60,11 @@ class Ztimer
       end
     end
 
-    def get_delay
-      return @mutex.synchronize { @slots.empty? ? nil : @slots.first.expires_at - utc_microseconds }
+    def calculate_delay
+      @mutex.synchronize { @slots.empty? ? nil : @slots.first.expires_at - utc_microseconds }
     end
 
-    def get_first_expired
+    def fetch_first_expired
       @mutex.synchronize do
         slot = @slots.first
         if slot && (slot.expires_at < utc_microseconds)
@@ -89,7 +90,7 @@ class Ztimer
     end
 
     def utc_microseconds
-      return Time.now.to_f * 1_000_000
+      Time.now.to_f * 1_000_000
     end
   end
 end

data/lib/ztimer.rb

@@ -1,8 +1,11 @@
-require "ztimer/version"
-require "ztimer/slot"
-require "ztimer/sorted_store"
-require "ztimer/watcher"
+# frozen_string_literal: true
 
+require 'ztimer/version'
+require 'ztimer/slot'
+require 'ztimer/sorted_store'
+require 'ztimer/watcher'
+
+# Implements a timer which allows to execute a block with a delay, recurrently or asynchronously.
 class Ztimer
   @default_instance = nil
 
@@ -10,7 +13,7 @@ class Ztimer
 
   def initialize(concurrency: 20)
     @concurrency  = concurrency
-    @watcher      = Ztimer::Watcher.new(){|slot| execute(slot) }
+    @watcher      = Ztimer::Watcher.new { |slot| execute(slot) }
     @workers_lock = Mutex.new
     @count_lock   = Mutex.new
     @queue        = Queue.new
@@ -18,6 +21,7 @@ class Ztimer
     @count        = 0
   end
 
+  # Execute the code block asyncrhonously right now
   def async(&callback)
     enqueued_at = utc_microseconds
     slot        = Slot.new(enqueued_at, enqueued_at, -1, &callback)
@@ -25,9 +29,10 @@ class Ztimer
     incr_counter!
     execute(slot)
 
-    return slot
+    slot
   end
 
+  # Execute the code block after the specified delay
   def after(milliseconds, &callback)
     enqueued_at = utc_microseconds
     expires_at  = enqueued_at + milliseconds * 1000
@@ -35,39 +40,104 @@ class Ztimer
 
     add(slot)
 
-    return slot
+    slot
   end
 
-  def every(milliseconds, &callback)
-    enqueued_at = utc_microseconds
-    expires_at  = enqueued_at + milliseconds * 1000
-    slot        = Slot.new(enqueued_at, expires_at, milliseconds * 1000, &callback)
+  # Execute the code block at a specific datetime
+  def at(datetime, &callback)
+    enqueued_at = datetime.to_f * 1_000_000
+
+    slot = Slot.new(enqueued_at, enqueued_at, -1, &callback)
+    add(slot)
+
+    slot
+  end
+
+  # Execute the code block every N milliseconds.
+  # When :start_at is specified, the first execution will start at specified date/time
+  def every(milliseconds, start_at: nil, &callback)
+    enqueued_at = start_at ? start_at.to_f * 1_000_000 : utc_microseconds
+    expires_at = enqueued_at + milliseconds * 1000
+    slot = Slot.new(enqueued_at, expires_at, milliseconds * 1000, &callback)
 
     add(slot)
 
-    return slot
+    slot
+  end
+
+  # Run ztimer every N seconds, starting with the nearest time slot (ex. secondly(5)
+  # will run at second 0, 5, 10, 15, etc.)
+  def secondly(seconds, offset: 0, &callback)
+    start_time = utc_microseconds
+    milliseconds = (seconds.to_f * 1000).to_i
+    enqueued_at = start_time - (start_time % (milliseconds * 1000)) + offset * 1_000_000
+    expires_at = enqueued_at + milliseconds * 1000
+
+    slot = Slot.new(enqueued_at, expires_at, milliseconds * 1000, &callback)
+    add(slot)
+
+    slot
+  end
+
+  # Run ztimer every N minutes, starting at the nearest time slot (ex. minutely(2) will run at minute 0, 2, 4, 6, etc.)
+  def minutely(minutes, offset: 0, &callback)
+    secondly(minutes.to_f * 60, offset: offset.to_f * 60, &callback)
+  end
+
+  # Run ztimer every N hours, starting at the nearest time slot (ex. hourly(2) will run at hour 0, 2, 4, 6, etc.)
+  def hourly(hours, offset: 0, &callback)
+    minutely(hours.to_f * 60, offset: offset.to_f * 60, &callback)
+  end
+
+  def daily(days, offset: 0, &callback)
+    raise ArgumentError, "Days number should be > 0: #{days.inspect}" if days.to_f <= 0
+
+    hourly(days.to_f * 24, offset: offset.to_f * 24, &callback)
+  end
+
+  def day_of_week(day, &callback)
+    days = %w[sun mon tue thu wen fri sat]
+    current_day = Time.now.wday
+
+    index = day.to_i
+    if day.is_a?(String)
+      # Find day number by day name
+      index = days.index { |day_name| day.strip.downcase == day_name }
+      raise ArgumentError, "Invalid week day: #{day.inspect}" if index.nil?
+    elsif index.negative? || index > 6
+      raise ArgumentError, "Invalid week day: #{day.inspect}"
+    end
+
+    offset = 0
+    offset = (current_day > index ? index - current_day : current_day - index) if current_day != index
+
+    daily(7, offset: offset, &callback)
+  end
+
+  def days_of_week(*args, &callback)
+    args.map { |day| day_of_week(day, &callback) }
   end
 
   def jobs_count
-    return @watcher.jobs
+    @watcher.jobs
   end
 
   def concurrency=(new_value)
-    raise ArgumentError.new("Invalid concurrency value: #{new_value}") unless new_value.is_a?(Fixnum) && new_value >= 1
+    value_is_integer = new_value.is_a?(Integer)
+    raise ArgumentError, "Invalid concurrency value: #{new_value}" unless value_is_integer && new_value >= 1
+
     @concurrency = new_value
   end
 
-
   def stats
     {
-      running:   @running,
+      running: @running,
       scheduled: @watcher.jobs,
       executing: @queue.size,
-      total:     @count
+      total: @count
     }
   end
 
-
   def self.method_missing(name, *args, &block)
     @default_instance ||= Ztimer.new(concurrency: 20)
     @default_instance.send(name, *args, &block)
@@ -108,12 +178,13 @@ class Ztimer
           begin
             current_slot.executed_at = utc_microseconds
             current_slot.callback.call(current_slot) unless current_slot.callback.nil? || current_slot.canceled?
-          rescue => e
-            STDERR.puts e.inspect + (e.backtrace ? "\n" + e.backtrace.join("\n") : "")
+          rescue StandardError => e
+            backtrace = e.backtrace ? "\n#{e.backtrace.join("\n")}" : ''
+            warn e.inspect + backtrace
           end
         end
       rescue ThreadError
-        puts "queue is empty"
+        puts 'queue is empty'
       end
       @workers_lock.synchronize { @running -= 1 }
     end
@@ -121,6 +192,6 @@ class Ztimer
   end
 
   def utc_microseconds
-    return Time.now.to_f * 1_000_000
+    Time.now.to_f * 1_000_000
   end
 end

data/ztimer.gemspec

@@ -1,25 +1,28 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'ztimer/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "ztimer"
+  spec.name          = 'ztimer'
   spec.version       = Ztimer::VERSION
-  spec.authors       = ["Groza Sergiu"]
-  spec.email         = ["serioja90@gmail.com"]
+  spec.authors       = ['Groza Sergiu']
+  spec.email         = ['serioja90@gmail.com']
 
-  spec.summary       = %q{An asyncrhonous timer}
-  spec.description   = %q{Ruby asyncrhonous timer that allows you to enqueue tasks to be executed asyncrhonously after a delay}
-  spec.homepage      = "https://github.com/serioja90/ztimer"
-  spec.license       = "MIT"
+  spec.summary       = %(An asyncrhonous timer)
+  spec.description   = %(Ruby asyncrhonous timer that allows you to enqueue tasks to be executed asyncrhonously after a delay)
+  spec.homepage      = 'https://github.com/serioja90/ztimer'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.5'
 
-  spec.add_development_dependency "bundler", "~> 1.11"
-  spec.add_development_dependency "rake",    "~> 10.0"
-  spec.add_development_dependency "rspec",   "~> 3.0"
+  spec.add_development_dependency 'bundler', '~>2.2', '>= 2.2.33'
+  spec.add_development_dependency 'rake', '~>12.3', '>= 12.3.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ztimer
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Groza Sergiu
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-20 00:00:00.000000000 Z
+date: 2022-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,28 +16,40 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.33
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.33
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -87,15 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: An asyncrhonous timer