throttle-queue 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 602c620f6b090b5696a141185d5e1d65c8240c07
+  data.tar.gz: 852eec61c6d3d3c1200e83b63a202d03d57a4842
+SHA512:
+  metadata.gz: 53b009d91bafd808374a49e10a98e19fd926f98bee250e163f77bf9da7ffad395528ec33df9855e57b75f338dd3579c7ce5234b1a6954df8769470700511a6e3
+  data.tar.gz: a430b7bb92bde90fe9bf937198b2337171bf98292d4ae72fbc3924998b827d9298c33020c3fa939bffaad021107533992110aebc8c11fbe8ca15e39e42f7cfe3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Ryan Calhoun
+
+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.

data/README.md

@@ -0,0 +1,48 @@
+[![Gem Version](https://badge.fury.io/rb/throttle-queue.svg)](http://badge.fury.io/rb/throttle-queue)
+
+# ThrottleQueue
+
+	A thread-safe rate-limited work queue, with foreground and background operations
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'throttle-queue'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install throttle-queue
+
+## Usage
+
+Create a queue and add background work
+
+	q = ThrottleQueue.new 3
+	files.each {|file|
+		q.background(file) {
+			fetch file
+		}
+	}
+
+Get user input and take action right away
+
+	q.foreground(user_file) {
+		fetch user_file
+	}
+
+Wait for everything to finish
+
+	q.wait
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new {|t|
+	t.test_files = FileList['test/**/*est.rb']
+}
+
+desc 'Run tests'
+task :default => :test

data/lib/throttle-queue.rb

@@ -0,0 +1,222 @@
+require 'thread'
+# ThrottleQueue is a thread-safe rate-limited work queue. It allows both
+# background and foreground operations.
+#
+# Example:
+#   q = ThrottleQueue 3
+#   files.each {|file|
+#     q.background(file) {|id|
+#       fetch file
+#     }
+#   }
+class ThrottleQueue
+	# Creates a new ThrottleQueue with the given rate limit (per second).
+	def initialize(limit)
+		raise "refusing to do zero work per second" if limit <= 0
+		@limit = limit
+
+		@queue = PriorityQueue.new
+
+		@mutex = Mutex.new
+		@pausing = ConditionVariable.new
+		@idle = ConditionVariable.new
+		@in_flight = nil
+		@processing_thread = nil
+		@items = {}
+
+		@throttling = nil
+		@state = :idle
+		@t0 = Time.now
+	end
+	# Signals the queue to stop processing and shutdown.
+	#
+	# Items still in the queue are dropped. Any item
+	# currently in flight will finish.
+	def shutdown
+		@queue.shutdown
+		@pausing.signal
+	end
+	# Returns true if there is nothing queued and no
+	# threads are running
+	def idle?
+		@state == :idle
+	end
+	# Blocks the calling thread while the queue processes work.
+	#
+	# Returns after the timeout has expired, or after the
+	# queue returns to the idle state.
+	def wait(timeout = nil)
+		@mutex.synchronize {
+			@idle.wait(@mutex, timeout) unless idle?
+		}
+	end
+	# Adds work to the queue to run in the background, and
+	# returns immediately.
+	#
+	# If the block takes an argument, it will be passed the
+	# same id used to queue the work.
+	def background(id, &block)
+		@mutex.synchronize {
+			if id != @in_flight
+				@items[id] = block
+				@queue.background id
+				run
+			end
+		}
+	end
+	# Adds work to the queue ahead of all background work, and
+	# blocks until the given block has been called.
+	#
+	# Will preempt an id of the same value in either the
+	# background or foreground queues.
+	#
+	# If the block takes an argument, it will be passed the
+	# same id used to queue the work.
+	def foreground(id, &block)
+		t = nil
+		@mutex.synchronize {
+			if id == @in_flight
+				t = @processing_thread unless @processing_thread == Thread.current
+			else
+				b = @items[id]
+				b.kill if b.is_a? FG
+
+				t = @items[id] = FG.new block, self
+
+				@queue.foreground id
+				run
+			end
+		}
+		t.join if t
+	end
+
+	private
+	def run
+		return unless @state == :idle
+		@state = :running
+		@throttling = Thread.new {
+			loop {
+				break if @queue.shutdown? or @queue.empty?
+
+				elapsed = Time.now - @t0
+				wait_time = 1.0 / @limit + 0.01
+				if @processing_thread and elapsed < wait_time
+					@mutex.synchronize {
+						@pausing.wait @mutex, wait_time - elapsed
+					}
+				end
+
+				if id = @queue.pop
+					@mutex.synchronize {
+						@in_flight = id
+						@processing_thread = Thread.new {
+							block = @items[@in_flight]
+							if block.arity == 0
+								block.call
+							else
+								block.call @in_flight
+							end
+						}
+					}
+					@processing_thread.join if @processing_thread
+				end
+
+				@t0 = Time.now
+			}
+
+			@mutex.synchronize {
+				@state = :idle
+				if @queue.shutdown? or @queue.empty?
+					@idle.signal
+				else
+					# Restart to prevent a join deadlock
+					send :run
+				end
+			}
+		}
+	end
+	class FG #:nodoc: all
+		def initialize(block, h)
+			@block = block
+			@thread = Thread.new {
+				Thread.stop
+				@block.call *@args
+			}
+			@h = h
+		end
+		def arity
+			@block.arity
+		end
+		def call(*args)
+			@args = args
+			@thread.run
+		end
+		def kill
+			@thread.kill
+		end
+		def join
+			@thread.join
+		end
+	end
+	class PriorityQueue #:nodoc: all
+		def initialize
+			@mutex = Mutex.new
+			@fg = []
+			@bg = []
+			@received = ConditionVariable.new
+			@shutdown = false
+		end
+
+		def shutdown
+			@shutdown = true
+			@received.signal
+		end
+
+		def shutdown?
+			@shutdown
+		end
+
+		def empty?
+			@mutex.synchronize {
+				@fg.empty? and @bg.empty?
+			}
+		end
+
+		def background(id)
+			@mutex.synchronize {
+				unless @shutdown || @bg.include?(id)
+					@bg << id
+					@received.signal
+				end
+			}
+		end
+
+		def foreground(id)
+			@mutex.synchronize {
+				unless @shutdown || @fg.include?(id)
+					@fg << id
+					if @bg.include?(id)
+						@bg.delete id
+					else
+						@received.signal
+					end
+				end
+			}
+		end
+
+		def pop
+			@mutex.synchronize {
+				if @fg.empty? and @bg.empty?
+					@received.wait(@mutex) unless @shutdown
+				end
+
+				if @shutdown
+				elsif ! @fg.empty?
+					@fg.shift
+				else
+					@bg.shift
+				end
+			}
+		end
+	end
+end

data/test/throttle-queue-test.rb

@@ -0,0 +1,141 @@
+require_relative '../lib/throttle-queue'
+require 'test/unit'
+
+class ThrottleQueueTest < Test::Unit::TestCase
+
+	def setup
+		@t = ThrottleQueue.new 10
+	end
+
+	def teardown
+		@t.shutdown
+	end
+
+	def testBackground
+		results = []
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+			}
+		}
+		@t.wait
+		assert_equal %w(Apple Banana Cake Donut Egg), results
+	end
+	def testForeground
+		results = []
+		%w(apple banana cake donut egg).each_with_index {|w,i|
+			@t.foreground(w) {
+				results << w.capitalize
+			}
+			assert_equal %w(Apple Banana Cake Donut Egg)[0..i], results
+		}
+		@t.wait
+	end
+	def testBackgroundInFlight
+		results = []
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					@t.background('banana') {
+						results << 'BANANAYO'
+					}
+				end
+			}
+		}
+
+		@t.wait
+		assert_equal %w(Apple Banana Cake Donut Egg), results
+	end
+	def testBackgroundQueued
+		results = []
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					@t.background('cake') {
+						results << 'CAKEYO'
+					}
+				end
+			}
+		}
+
+		@t.wait
+		assert_equal %w(Apple Banana CAKEYO Donut Egg), results
+	end
+	def testForegroundInFlight
+		results = []
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					@t.foreground('banana') {
+						results << 'BANANAYO'
+					}
+				end
+			}
+		}
+
+		@t.wait
+		assert_equal %w(Apple Banana Cake Donut Egg), results
+	end
+	def testForegroundQueued
+		results = []
+
+		t = Thread.new {
+			Thread.stop
+			@t.foreground('cake') {
+				results << 'CAKEYO'
+			}
+		}
+
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					t.run
+				end
+			}
+		}
+
+		@t.wait
+		assert_equal %w(Apple Banana CAKEYO Donut Egg), results
+	end
+	def testForegroundPreemptBackground
+		results = []
+
+		t = Thread.new {
+			Thread.stop
+			%w(fish grape).each {|w|
+				@t.foreground(w) {
+					results << w.capitalize
+				}
+			}
+		}
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					t.run
+				end
+			}
+		}
+
+		@t.wait
+		assert_equal %w(Apple Banana Fish Grape Cake Donut Egg), results
+	end
+	def testShutdownWithoutWaiting
+		results = []
+		%w(apple banana cake donut egg).each {|w|
+			@t.background(w) {
+				results << w.capitalize
+				if w == 'banana'
+					@t.shutdown
+				end
+			}
+		}
+		@t.wait
+		assert_equal %w(Apple Banana), results
+	end
+
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: throttle-queue
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ryan Calhoun
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-20 00:00:00.000000000 Z
+dependencies: []
+description: A thread-safe rate-limited work queue, which allows for background and
+  foreground operations.
+email:
+- ryanjamescalhoun@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/throttle-queue.rb
+- test/throttle-queue-test.rb
+homepage: https://github.com/theryan/throttle-queue
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A thread-safe rate-limited work queue
+test_files:
+- test/throttle-queue-test.rb
+- Rakefile