timers 4.2.0 → 4.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1665f074c230a801e0eb6648214a6d0248d4baada8da1f4e60abd0983bba517
-  data.tar.gz: de4eac12ecba1826d6ae5ef1d6958a451595b1a9e8e54dba7f1718d7f15182dd
+  metadata.gz: a9f471bfb9cac57f9462498ab12527eded7533318cec13604a10d32b159c6689
+  data.tar.gz: 69802b0774101037596274f2acf114c3f4234875ed8a82146e8ef1075407bf6d
 SHA512:
-  metadata.gz: c0e005f02975d324b7fbe7d8e284a2d5318be78352e129ce00abf20594d3e6a18b30103e1137b2d9fe91bd5a2251e7b22fb5cdc255f5153f219bf90bd3b6160d
-  data.tar.gz: 64210a85d0a8efe2540d9ee6da050c5d8298a5332bd2ba14758bd784a7f991ad40b1f828b47320525ab025249859ca6419f172421492fe6ced56a76e34820541
+  metadata.gz: f15934803658ec4b1d0d7b4a8ea92c9a21e2267544ec11c9619604288264c7f0add19dd12b71a0680827d6d37b853192d98266f29b06ef27cb36e53408f8c67b
+  data.tar.gz: a50a935d7b73681b4b751341c6eda0143c64beb9d469641ea68b8481cd1c36bd16ad21f7ec274f06d1389b53c5849e06b20182d3faea6497f64773d8fba2dae6

data/lib/timers.rb

@@ -1,11 +1,26 @@
 # 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.
-#
 
-require "timers/version"
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
-require "timers/group"
-require "timers/wait"
+require_relative "timers/version"
+
+require_relative "timers/group"
+require_relative "timers/wait"

data/lib/timers/events.rb

@@ -1,113 +1,115 @@
 # 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.
-#
+
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
 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 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)
 			handle = Handle.new(time.to_f, callback)
-
-			index = bisect_left(@sequence, handle)
-
-			# Maintain sorted order, O(logN) insertion time.
-			@sequence.insert(index, handle)
-
-			handle
+			
+			@queue << handle
+			
+			return handle
 		end
-
+		
 		# Returns the first non-cancelled handle.
 		def first
-			while (handle = @sequence.last)
+			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
+			@sequence.size + @queue.size
 		end
-
+		
 		# Fire all handles for which Handle#time is less than the given time.
 		def fire(time)
-			pop(time).reverse_each do |handle|
+			merge!
+			
+			while handle = @sequence.peek and handle.time <= time
+				@sequence.pop
 				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
+		
+		# 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
-
-			l
 		end
 	end
 end

data/lib/timers/group.rb

@@ -1,9 +1,24 @@
 # 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.
-#
+
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
 require "set"
 require "forwardable"
@@ -16,62 +31,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
@@ -81,10 +96,10 @@ module Timers
 					sleep interval
 				end
 			end
-
+			
 			fire
 		end
-
+		
 		# Interval to wait until when the next timer will fire.
 		# - nil: no timers
 		# - -ve: timers expired already
@@ -94,36 +109,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,24 @@
 # 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.
-#
+
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
 module Timers
 	# A collection of timers which may fire at different times

data/lib/timers/priority_heap.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Copyright, 2021, by Wander Hillen.
+# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+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
+		
+		private
+		
+		# Validate the heap invariant.
+		def validate!(index = 0)
+			if value = @contents[index]
+				left_index = index*2 + 1
+				if left_value = @contents[left_index]
+					unless value < left_value
+						raise "Invalid left index from #{index}!"
+					end
+					
+					validate!(left_index)
+				end
+				
+				right_index = left_index + 1
+				if right_value = @contents[right_index]
+					unless value < right_value
+						raise "Invalid right index from #{index}!"
+					end
+					
+					validate!(right_index)
+				end
+			end
+		end
+		
+		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