timers 4.1.2 → 4.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 97c81b8ed305099faee9ecec3ee32f6960b70d54
-  data.tar.gz: 90d94a796bfe60e78963b0053648396aefdb19b6
+SHA256:
+  metadata.gz: e7c61c9db77955d85c69ca83499add3629c71628af3a825d78978b2383182b4a
+  data.tar.gz: 27f570753d83d4b4a98ee6ede089908d571347df8ba411edb56fe4ae965e703c
 SHA512:
-  metadata.gz: dbea5311bcd5fb7bfe7c98191ac15146647b91ab5c994309f3bc14fe394ac97832361afa6ff7f257d844a802265125a5bafa051026fa1eed979f8310d8a21f87
-  data.tar.gz: 2097c9e9d6e838550fa3c4735db828173852dd5e598670a376a04de132274df6464687cfe0e72992c2469d5d355932808fe1147e44ec5f26e2162046267c37ad
+  metadata.gz: a7bac196cc0e3e1a784f7ba961c4a09539c875f80ac366da0b0d091d9f6ad1a505fb0a86a0c9d61d44a3495342029d003749b3ac072904b37f667d8e6e90b356
+  data.tar.gz: 4fa05113f72aef3abe63804a097e7fd9322c5b84a2a9ad14d590906e3ca59754857378a085388c52f9eb7ef1beb934b6b75789c3c087eee0b900f3446ace7207

data/lib/timers/events.rb

@@ -1,111 +1,111 @@
 # frozen_string_literal: true
 
-require "forwardable"
-require "hitimes"
+# Released under the MIT License.
+# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2016, by Tony Arcieri.
+# Copyright, 2014, by Lavir the Whiolet.
+# Copyright, 2015, by Utenmiki.
+# Copyright, 2015, by Donovan Keme.
+# Copyright, 2021, by Wander Hillen.
 
-require "timers/timer"
+require_relative "timer"
+require_relative "priority_heap"
 
 module Timers
-  # Maintains an ordered list of events, which can be cancelled.
-  class Events
-    # Represents a cancellable handle for a specific timer event.
-    class Handle
-      def initialize(time, callback)
-        @time = time
-        @callback = callback
-      end
-
-      # The absolute time that the handle should be fired at.
-      attr_reader :time
-
-      # Cancel this timer, O(1).
-      def cancel!
-        # The simplest way to keep track of cancelled status is to nullify the
-        # callback. This should also be optimal for garbage collection.
-        @callback = nil
-      end
-
-      # Has this timer been cancelled? Cancelled timer's don't fire.
-      def cancelled?
-        @callback.nil?
-      end
-
-      def >(other)
-        @time > other.to_f
-      end
-
-      def to_f
-        @time
-      end
-
-      # Fire the callback if not cancelled with the given time parameter.
-      def fire(time)
-        @callback.call(time) if @callback
-      end
-    end
-
-    def initialize
-      # A sequence of handles, maintained in sorted order, future to present.
-      # @sequence.last is the next event to be fired.
-      @sequence = []
-    end
-
-    # Add an event at the given time.
-    def schedule(time, callback)
-      handle = Handle.new(time.to_f, callback)
-
-      index = bisect_left(@sequence, handle)
-
-      # Maintain sorted order, O(logN) insertion time.
-      @sequence.insert(index, handle)
-
-      handle
-    end
-
-    # Returns the first non-cancelled handle.
-    def first
-      while (handle = @sequence.last)
-        return handle unless handle.cancelled?
-        @sequence.pop
-      end
-    end
-
-    # Returns the number of pending (possibly cancelled) events.
-    def size
-      @sequence.size
-    end
-
-    # Fire all handles for which Handle#time is less than the given time.
-    def fire(time)
-      pop(time).reverse_each do |handle|
-        handle.fire(time)
-      end
-    end
-
-    private
-
-    # Efficiently take k handles for which Handle#time is less than the given
-    # time.
-    def pop(time)
-      index = bisect_left(@sequence, time)
-
-      @sequence.pop(@sequence.size - index)
-    end
-
-    # Return the left-most index where to insert item e, in a list a, assuming
-    # a is sorted in descending order.
-    def bisect_left(a, e, l = 0, u = a.length)
-      while l < u
-        m = l + (u - l).div(2)
-
-        if a[m] > e
-          l = m + 1
-        else
-          u = m
-        end
-      end
-
-      l
-    end
-  end
+	# Maintains a PriorityHeap of events ordered on time, which can be cancelled.
+	class Events
+		# Represents a cancellable handle for a specific timer event.
+		class Handle
+			include Comparable
+			
+			def initialize(time, callback)
+				@time = time
+				@callback = callback
+			end
+			
+			# The absolute time that the handle should be fired at.
+			attr_reader :time
+			
+			# Cancel this timer, O(1).
+			def cancel!
+				# The simplest way to keep track of cancelled status is to nullify the
+				# callback. This should also be optimal for garbage collection.
+				@callback = nil
+			end
+			
+			# Has this timer been cancelled? Cancelled timer's don't fire.
+			def cancelled?
+				@callback.nil?
+			end
+			
+			def <=> other
+				@time <=> other.time
+			end
+			
+			# Fire the callback if not cancelled with the given time parameter.
+			def fire(time)
+				@callback.call(time) if @callback
+			end
+		end
+		
+		def initialize
+			# A sequence of handles, maintained in sorted order, future to present.
+			# @sequence.last is the next event to be fired.
+			@sequence = PriorityHeap.new
+			@queue = []
+		end
+		
+		# Add an event at the given time.
+		def schedule(time, callback)
+			flush!
+			
+			handle = Handle.new(time.to_f, callback)
+			
+			@queue << handle
+			
+			return handle
+		end
+		
+		# Returns the first non-cancelled handle.
+		def first
+			merge!
+			
+			while (handle = @sequence.peek)
+				return handle unless handle.cancelled?
+				@sequence.pop
+			end
+		end
+		
+		# Returns the number of pending (possibly cancelled) events.
+		def size
+			@sequence.size + @queue.size
+		end
+		
+		# Fire all handles for which Handle#time is less than the given time.
+		def fire(time)
+			merge!
+			
+			while handle = @sequence.peek and handle.time <= time
+				@sequence.pop
+				handle.fire(time)
+			end
+		end
+		
+		private
+		
+		# Move all non-cancelled timers from the pending queue to the priority heap
+		def merge!
+			while handle = @queue.pop
+				next if handle.cancelled?
+				
+				@sequence.push(handle)
+			end
+		end
+		
+		def flush!
+			while @queue.last&.cancelled?
+				@queue.pop
+			end
+		end
+	end
 end

data/lib/timers/group.rb

@@ -1,127 +1,133 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2016, by Tony Arcieri.
+# Copyright, 2015, by Donovan Keme.
+# Copyright, 2015, by Tommy Ong Gia Phu.
+
 require "set"
 require "forwardable"
-require "hitimes"
 
-require "timers/timer"
-require "timers/events"
+require_relative "interval"
+require_relative "timer"
+require_relative "events"
 
 module Timers
-  # A collection of timers which may fire at different times
-  class Group
-    include Enumerable
-
-    extend Forwardable
-    def_delegators :@timers, :each, :empty?
-
-    def initialize
-      @events = Events.new
-
-      @timers = Set.new
-      @paused_timers = Set.new
-
-      @interval = Hitimes::Interval.new
-      @interval.start
-    end
-
-    # Scheduled events:
-    attr_reader :events
-
-    # Active timers:
-    attr_reader :timers
-
-    # Paused timers:
-    attr_reader :paused_timers
-
-    # Call the given block after the given interval. The first argument will be
-    # the time at which the group was asked to fire timers for.
-    def after(interval, &block)
-      Timer.new(self, interval, false, &block)
-    end
-
-    # Call the given block immediately, and then after the given interval. The first
-    # argument will be the time at which the group was asked to fire timers for.
-    def now_and_after(interval, &block)
-      yield
-      after(interval, &block)
-    end
-
-    # Call the given block periodically at the given interval. The first
-    # argument will be the time at which the group was asked to fire timers for.
-    def every(interval, recur = true, &block)
-      Timer.new(self, interval, recur, &block)
-    end
-
-    # Call the given block immediately, and then periodically at the given interval. The first
-    # argument will be the time at which the group was asked to fire timers for.
-    def now_and_every(interval, recur = true, &block)
-      yield
-      every(interval, recur, &block)
-    end
-
-    # Wait for the next timer and fire it. Can take a block, which should behave
-    # like sleep(n), except that n may be nil (sleep forever) or a negative
-    # number (fire immediately after return).
-    def wait
-      if block_given?
-        yield wait_interval
-
-        while (interval = wait_interval) && interval > 0
-          yield interval
-        end
-      else
-        while (interval = wait_interval) && interval > 0
-          # We cannot assume that sleep will wait for the specified time, it might be +/- a bit.
-          sleep interval
-        end
-      end
-
-      fire
-    end
-
-    # Interval to wait until when the next timer will fire.
-    # - nil: no timers
-    # - -ve: timers expired already
-    # -   0: timers ready to fire
-    # - +ve: timers waiting to fire
-    def wait_interval(offset = current_offset)
-      handle = @events.first
-      handle.time - Float(offset) if handle
-    end
-
-    # Fire all timers that are ready.
-    def fire(offset = current_offset)
-      @events.fire(offset)
-    end
-
-    # Pause all timers.
-    def pause
-      @timers.dup.each(&:pause)
-    end
-
-    # Resume all timers.
-    def resume
-      @paused_timers.dup.each(&:resume)
-    end
-
-    alias continue resume
-
-    # Delay all timers.
-    def delay(seconds)
-      @timers.each do |timer|
-        timer.delay(seconds)
-      end
-    end
-
-    # Cancel all timers.
-    def cancel
-      @timers.dup.each(&:cancel)
-    end
-
-    # The group's current time.
-    def current_offset
-      @interval.to_f
-    end
-  end
+	# A collection of timers which may fire at different times
+	class Group
+		include Enumerable
+		
+		extend Forwardable
+		def_delegators :@timers, :each, :empty?
+		
+		def initialize
+			@events = Events.new
+			
+			@timers = Set.new
+			@paused_timers = Set.new
+			
+			@interval = Interval.new
+			@interval.start
+		end
+		
+		# Scheduled events:
+		attr_reader :events
+		
+		# Active timers:
+		attr_reader :timers
+		
+		# Paused timers:
+		attr_reader :paused_timers
+		
+		# Call the given block after the given interval. The first argument will be
+		# the time at which the group was asked to fire timers for.
+		def after(interval, &block)
+			Timer.new(self, interval, false, &block)
+		end
+		
+		# Call the given block immediately, and then after the given interval. The first
+		# argument will be the time at which the group was asked to fire timers for.
+		def now_and_after(interval, &block)
+			yield
+			after(interval, &block)
+		end
+		
+		# Call the given block periodically at the given interval. The first
+		# argument will be the time at which the group was asked to fire timers for.
+		def every(interval, recur = true, &block)
+			Timer.new(self, interval, recur, &block)
+		end
+		
+		# Call the given block immediately, and then periodically at the given interval. The first
+		# argument will be the time at which the group was asked to fire timers for.
+		def now_and_every(interval, recur = true, &block)
+			yield
+			every(interval, recur, &block)
+		end
+		
+		# Wait for the next timer and fire it. Can take a block, which should behave
+		# like sleep(n), except that n may be nil (sleep forever) or a negative
+		# number (fire immediately after return).
+		def wait
+			if block_given?
+				yield wait_interval
+				
+				while (interval = wait_interval) && interval > 0
+					yield interval
+				end
+			else
+				while (interval = wait_interval) && interval > 0
+					# We cannot assume that sleep will wait for the specified time, it might be +/- a bit.
+					sleep interval
+				end
+			end
+			
+			fire
+		end
+		
+		# Interval to wait until when the next timer will fire.
+		# - nil: no timers
+		# - -ve: timers expired already
+		# -   0: timers ready to fire
+		# - +ve: timers waiting to fire
+		def wait_interval(offset = current_offset)
+			handle = @events.first
+			handle.time - Float(offset) if handle
+		end
+		
+		# Fire all timers that are ready.
+		def fire(offset = current_offset)
+			@events.fire(offset)
+		end
+		
+		# Pause all timers.
+		def pause
+			@timers.dup.each(&:pause)
+		end
+		
+		# Resume all timers.
+		def resume
+			@paused_timers.dup.each(&:resume)
+		end
+		
+		alias continue resume
+		
+		# Delay all timers.
+		def delay(seconds)
+			@timers.each do |timer|
+				timer.delay(seconds)
+			end
+		end
+		
+		# Cancel all timers.
+		def cancel
+			@timers.dup.each(&:cancel)
+		end
+		
+		# The group's current time.
+		def current_offset
+			@interval.to_f
+		end
+	end
 end

data/lib/timers/interval.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2018-2022, by Samuel Williams.
+
+module Timers
+	# A collection of timers which may fire at different times
+	class Interval
+		# Get the current elapsed monotonic time.
+		def initialize
+			@total = 0.0
+			@current = nil
+		end
+		
+		def start
+			return if @current
+			
+			@current = now
+		end
+		
+		def stop
+			return unless @current
+			
+			@total += duration
+			
+			@current = nil
+		end
+		
+		def to_f
+			@total + duration
+		end
+		
+		protected def duration
+			now - @current
+		end
+		
+		protected def now
+			::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+		end
+	end
+end

data/lib/timers/priority_heap.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021, by Wander Hillen.
+# Copyright, 2021-2022, by Samuel Williams.
+
+module Timers
+	# A priority queue implementation using a standard binary minheap. It uses straight comparison
+	# of its contents to determine priority. This works because a Handle from Timers::Events implements
+	# the '<' operation by comparing the expiry time.
+	# See <https://en.wikipedia.org/wiki/Binary_heap> for explanations of the main methods.
+	class PriorityHeap
+		def initialize
+			# The heap is represented with an array containing a binary tree. See
+			# https://en.wikipedia.org/wiki/Binary_heap#Heap_implementation for how this array
+			# is built up.
+			@contents = []
+		end
+		
+		# Returns the earliest timer or nil if the heap is empty.
+		def peek
+			@contents[0]
+		end
+		
+		# Returns the number of elements in the heap
+		def size
+			@contents.size
+		end
+		
+		# Returns the earliest timer if the heap is non-empty and removes it from the heap.
+		# Returns nil if the heap is empty. (and doesn't change the heap in that case)
+		def pop
+			# If the heap is empty:
+			if @contents.empty?
+				return nil
+			end
+			
+			# If we have only one item, no swapping is required:
+			if @contents.size == 1
+				return @contents.pop
+			end
+			
+			# Take the root of the tree:
+			value = @contents[0]
+			
+			# Remove the last item in the tree:
+			last = @contents.pop
+			
+			# Overwrite the root of the tree with the item:
+			@contents[0] = last
+			
+			# Bubble it down into place:
+			bubble_down(0)
+			
+			# validate!
+			
+			return value
+		end
+		
+		# Inserts a new timer into the heap, then rearranges elements until the heap invariant is true again.
+		def push(element)
+			# Insert the item at the end of the heap:
+			@contents.push(element)
+			
+			# Bubble it up into position:
+			bubble_up(@contents.size - 1)
+			
+			# validate!
+			
+			return self
+		end
+		
+		# Empties out the heap, discarding all elements
+		def clear!
+			@contents = []
+		end
+
+		# Validate the heap invariant. Every element except the root must not be smaller than
+		# its parent element. Note that it MAY be equal.
+		def valid?
+			# notice we skip index 0 on purpose, because it has no parent
+			(1..(@contents.size - 1)).all? { |e| @contents[e] >= @contents[(e - 1) / 2] }
+		end
+
+		private
+		
+		def swap(i, j)
+			@contents[i], @contents[j] = @contents[j], @contents[i]
+		end
+		
+		def bubble_up(index)
+			parent_index = (index - 1) / 2 # watch out, integer division!
+			
+			while index > 0 && @contents[index] < @contents[parent_index]
+				# if the node has a smaller value than its parent, swap these nodes
+				# to uphold the minheap invariant and update the index of the 'current'
+				# node. If the node is already at index 0, we can also stop because that
+				# is the root of the heap.
+				# swap(index, parent_index)
+				@contents[index], @contents[parent_index] = @contents[parent_index], @contents[index]
+				
+				index = parent_index
+				parent_index = (index - 1) / 2 # watch out, integer division!
+			end
+		end
+		
+		def bubble_down(index)
+			swap_value = 0
+			swap_index = nil
+			
+			while true
+				left_index = (2 * index) + 1
+				left_value = @contents[left_index]
+				
+				if left_value.nil?
+					# This node has no children so it can't bubble down any further.
+					# We're done here!
+					return
+				end
+				
+				# Determine which of the child nodes has the smallest value:
+				right_index = left_index + 1
+				right_value = @contents[right_index]
+				
+				if right_value.nil? or right_value > left_value
+					swap_value = left_value
+					swap_index = left_index
+				else
+					swap_value = right_value
+					swap_index = right_index
+				end
+				
+				if @contents[index] < swap_value
+					# No need to swap, the minheap invariant is already satisfied:
+					return
+				else
+					# At least one of the child node has a smaller value than the current node, swap current node with that child and update current node for if it might need to bubble down even further:
+					# swap(index, swap_index)
+					@contents[index], @contents[swap_index] = @contents[swap_index], @contents[index]
+					
+					index = swap_index
+				end
+			end
+		end
+	end
+end