timers 4.3.0 → 4.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccf7aa14dc18086e3a47fb44eb3a12569ba6752e6f7d22aecf7486684a594331
-  data.tar.gz: 0c37cdab96fc3ae8a1fbd0deb07b69800260b32118c7d1b37d2a4114258c32e8
+  metadata.gz: e7c61c9db77955d85c69ca83499add3629c71628af3a825d78978b2383182b4a
+  data.tar.gz: 27f570753d83d4b4a98ee6ede089908d571347df8ba411edb56fe4ae965e703c
 SHA512:
-  metadata.gz: dcb1826464d594d78d0a67bf18f89bb3137ffdbdcb36306176bbaa961aab387b93442c4827f5a8e331b90de056dbc9f9f63dbdeb22671dcdd35203741f415967
-  data.tar.gz: 43dcaccab4fab882ca498ec196f08d47beb2636044b62103640406e5a0411d1eb6d837363eae50266c11642a59880179eca6a9f4053aefab1b4daf11a28319bd
+  metadata.gz: a7bac196cc0e3e1a784f7ba961c4a09539c875f80ac366da0b0d091d9f6ad1a505fb0a86a0c9d61d44a3495342029d003749b3ac072904b37f667d8e6e90b356
+  data.tar.gz: 4fa05113f72aef3abe63804a097e7fd9322c5b84a2a9ad14d590906e3ca59754857378a085388c52f9eb7ef1beb934b6b75789c3c087eee0b900f3446ace7207

data/lib/timers/events.rb

@@ -1,128 +1,111 @@
 # frozen_string_literal: true
-#
-# This file is part of the "timers" project and released under the MIT license.
-#
-# Copyright, 2018, by Samuel Williams. All rights reserved.
-#
+
+# 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_relative "timer"
+require_relative "priority_heap"
 
 module Timers
-	# Maintains an ordered list of events, which can be cancelled.
+	# 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.to_f
-			end
-
-			def >= other
-				@time >= other.to_f
-			end
-
-			def to_f
-				@time
+			
+			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 = []
+			@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.last)
+			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.last and handle.time <= time
+			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?
 				
-				index = bisect_right(@sequence, handle)
-				
-				if current_handle = @sequence[index] and current_handle.cancelled?
-					# puts "Replacing handle at index: #{index} due to cancellation in array containing #{@sequence.size} item(s)."
-					@sequence[index] = handle
-				else
-					# puts "Inserting handle at index: #{index} in array containing #{@sequence.size} item(s)."
-					@sequence.insert(index, handle)
-				end
+				@sequence.push(handle)
 			end
 		end
-
-		# Return the right-most index where to insert item e, in a list a, assuming
-		# a is sorted in descending order.
-		def bisect_right(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
+		
+		def flush!
+			while @queue.last&.cancelled?
+				@queue.pop
 			end
-
-			l
 		end
 	end
 end

data/lib/timers/group.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
-#
-# This file is part of the "timers" project and released under the MIT license.
-#
-# Copyright, 2018, by Samuel Williams. All rights reserved.
-#
+
+# 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"
@@ -16,62 +17,62 @@ 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 = 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
@@ -84,7 +85,7 @@ module Timers
 			
 			fire
 		end
-
+		
 		# Interval to wait until when the next timer will fire.
 		# - nil: no timers
 		# - -ve: timers expired already
@@ -94,36 +95,36 @@ module Timers
 			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

data/lib/timers/interval.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-#
-# This file is part of the "timers" project and released under the MIT license.
-#
-# Copyright, 2018, by Samuel Williams. All rights reserved.
-#
+
+# Released under the MIT License.
+# Copyright, 2018-2022, by Samuel Williams.
 
 module Timers
 	# A collection of timers which may fire at different times

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

data/lib/timers/timer.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
-#
-# This file is part of the "timers" project and released under the MIT license.
-#
-# Copyright, 2018, by Samuel Williams. All rights reserved.
-#
+
+# Released under the MIT License.
+# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2017, by Tony Arcieri.
+# Copyright, 2014, by Utenmiki.
+# Copyright, 2014, by Lin Jen-Shin.
+# Copyright, 2017, by Vít Ondruch.
 
 module Timers
 	# An individual timer set to fire a given proc at a given time. A timer is
@@ -14,66 +16,66 @@ module Timers
 	class Timer
 		include Comparable
 		attr_reader :interval, :offset, :recurring
-
+		
 		def initialize(group, interval, recurring = false, offset = nil, &block)
 			@group = group
-
+			
 			@interval = interval
 			@recurring = recurring
 			@block = block
 			@offset = offset
-
+			
 			@handle = nil
-
+			
 			# If a start offset was supplied, use that, otherwise use the current timers offset.
 			reset(@offset || @group.current_offset)
 		end
-
+		
 		def paused?
 			@group.paused_timers.include? self
 		end
-
+		
 		def pause
 			return if paused?
-
+			
 			@group.timers.delete self
 			@group.paused_timers.add self
-
+			
 			@handle.cancel! if @handle
 			@handle = nil
 		end
-
+		
 		def resume
 			return unless paused?
-
+			
 			@group.paused_timers.delete self
-
+			
 			# This will add us back to the group:
 			reset
 		end
-
+		
 		alias continue resume
-
+		
 		# Extend this timer
 		def delay(seconds)
 			@handle.cancel! if @handle
-
+			
 			@offset += seconds
-
+			
 			@handle = @group.events.schedule(@offset, self)
 		end
-
+		
 		# Cancel this timer. Do not call while paused.
 		def cancel
 			return unless @handle
-
+			
 			@handle.cancel! if @handle
 			@handle = nil
-
+			
 			# This timer is no longer valid:
 			@group.timers.delete self if @group
 		end
-
+		
 		# Reset this timer. Do not call while paused.
 		# @param offset [Numeric] the duration to add to the timer.
 		def reset(offset = @group.current_offset)
@@ -84,12 +86,12 @@ module Timers
 			else
 				@group.timers << self
 			end
-
+			
 			@offset = Float(offset) + @interval
-
+			
 			@handle = @group.events.schedule(@offset, self)
 		end
-
+		
 		# Fire the block.
 		def fire(offset = @group.current_offset)
 			if recurring == :strict
@@ -100,36 +102,38 @@ module Timers
 			else
 				@offset = offset
 			end
-
+			
 			@block.call(offset, self)
-
+			
 			cancel unless recurring
 		end
-
+		
 		alias call fire
-
+		
 		# Number of seconds until next fire / since last fire
 		def fires_in
 			@offset - @group.current_offset if @offset
 		end
-
+		
 		# Inspect a timer
 		def inspect
-			str = "#{to_s[0..-2]} ".dup
-
+			buffer = "#{to_s[0..-2]} ".dup
+			
 			if @offset
-				str << if fires_in >= 0
-								 "fires in #{fires_in} seconds"
-							 else
-								 "fired #{fires_in.abs} seconds ago"
-							 end
-
-				str << ", recurs every #{interval}" if recurring
+				if fires_in >= 0
+					buffer << "fires in #{fires_in} seconds"
+				else
+					buffer << "fired #{fires_in.abs} seconds ago"
+				end
+				
+				buffer << ", recurs every #{interval}" if recurring
 			else
-				str << "dead"
+				buffer << "dead"
 			end
-
-			str << ">"
+			
+			buffer << ">"
+			
+			return buffer
 		end
 	end
 end

data/lib/timers/version.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
-#
-# This file is part of the "timers" project and released under the MIT license.
-#
-# Copyright, 2018, by Samuel Williams. All rights reserved.
-#
+
+# Released under the MIT License.
+# Copyright, 2012-2016, by Tony Arcieri.
+# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2015, by Donovan Keme.
 
 module Timers
-	VERSION = "4.3.0"
+	VERSION = "4.3.5"
 end