improved-queue 1.0

data/lib/improved-queue.rb

@@ -0,0 +1,469 @@
+require 'thread'
+
+#
+# A simple elaboration on Ruby's native SizedQueue which allows using the queue
+# object to re-awaken a blocked thread and cause it to abandon its blocking
+# enqueue/dequeue operation. Useful for simplifying program logic, reducing the
+# need for external flags/Muteces (yes, I said Muteces), and for cleanly
+# resolving queues on program termination without risk of data loss or deadlock.
+#
+# Why use this queue? There are two reasons. For one thing, under several
+# circumstances it is _considerably_ faster than Ruby's native SizedQueue. I
+# admit I'm not entirely sure why, but I have tested this on multiple platforms
+# and it seems to hold true as a generality. You can feel free to confirm or
+# dispel that this advantage holds for your use case at your own leisure.
+#
+# The second reason is the aforementioned simplification of program logic.
+# In the case that all data passing through the queues must be preserved on
+# program termination, SizedQueue can require some elaborate trickery to ensure
+# that even the most remote possibility of deadlock is removed.
+# ImprovedSizedQueue solves this problem by making it possible to use the queue
+# to pass control messages between threads, irrespective of the queue's actual
+# content.
+#
+# Version::   1.0
+# Author::    Lincoln McCormick (mailto:iamtheiconoclast@gmail.com)
+# Copyright:: Copyright (c) 2013 Lincoln McCormick
+# License::   GNU General Public License version 3
+# Requires::  Ruby 1.9
+#--
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#++
+#
+#:title:ImprovedQueue
+#
+module ImprovedQueue
+
+  #
+  # The queue will raise this class of error within each waiting thread you wish
+  # to unblock, upon calling the #unblock_deq, #unblock_enq or #unblock_waiting
+  # methods. It inherits from StopIteration, so you can take advantage of the
+  # implicit rescue clause in Kernel.loop if you wish, like so:
+  #
+  #   queue = ImprovedQueue.new 10
+  #   
+  #   thread1 = Thread.new do
+  #     loop do
+  #       queue.pop
+  #     end
+  #   end
+  #   
+  #   thread2 = Thread.new do
+  #     queue.unblock_deq thread1
+  #   end
+  #
+  class UnblockError < StopIteration; end
+
+  #
+  # In most respects this class can be used identically to SizedQueue. It
+  # implements all of the methods which are usually available, but bears the
+  # important distinction that any thread blocking on a dequeue or enqueue
+  # operation can be "woken up" by calling the unblock methods and passing a
+  # thread object or an array of thread objects.
+  #
+  # This can be done independently of the status of the queue (full, empty,
+  # etc.), so it is superior to makeshift resolution mechanisms such as passing
+  # a custom message or dummy item into the queue, because there is no need to
+  # maintain flags or Mutex objects in your program to ensure that such an
+  # operation is not at risk of causing deadlock.
+  #
+  # When a blocking thread receives the unblock signal, it will abandon its
+  # planned operation and raise UnblockError. As UnblockError inherits from
+  # StopIteration, it can be rescued in a variety of ways, including implicitly
+  # through Kernel.loop, allowing you to further simplify your program logic:
+  #
+  #   queue = ImprovedQueue.new 50
+  #   threads = []
+  #   
+  #   # a consumer thread
+  #   threads << Thread.new do
+  #     loop do
+  #       val = queue.pop
+  #       do_something(val)
+  #     end
+  #   end
+  #   
+  #   # another consumer
+  #   threads << Thread.new do
+  #     loop do
+  #       val = queue.pop
+  #       do_something(val)
+  #     end
+  #   end
+  #   
+  #   # a producer
+  #   threads << Thread.new do
+  #     while not_finished_yet == true
+  #       queue << some_stuff
+  #       ...
+  #     end
+  #     
+  #     queue.unblock_deq [threads[0], threads[1]]
+  #   end
+  #   
+  #   threads.each {|thr| thr.join }
+  #
+  # One important thing to note: calling #unblock_deq is *always* safe (will
+  # never lose data), but when calling #unblock_enq, it is your responsibility
+  # to decide what is to be done with an item which failed to enqueue:
+  #
+  #   queue = ImprovedQueue.new 10
+  #   
+  #   1.upto(11) do |x|
+  #     begin
+  #       queue << x
+  #     rescue ImprovedQueue::UnblockError
+  #       dont_lose_things(x)
+  #     end
+  #   end
+  #
+  class ImprovedSizedQueue
+
+    #
+    # Returns a new instance of ImprovedQueue::ImprovedSizedQueue. Argument to
+    # ImprovedSizedQueue.new must be an integer value greater than 1.
+    #
+    def initialize(size)
+      raise TypeError unless size.is_a? Integer and size > 1
+      @que = []
+      @max = size
+      @mutex = Mutex.new
+      @kill_enq = []
+      @kill_deq = []
+      @deq_waiting = []
+      @enq_waiting = []
+      @unblock = UnblockError.new
+    end
+
+    #
+    # Returns the current maximum size of the queue.
+    #
+    attr_reader :max
+    
+    #
+    # Removes and returns the next item from the queue. Will block if the queue
+    # is empty, until an item becomes available to dequeue, or until
+    # #unblock_deq is called, in which case it will abandon the dequeue and
+    # raise UnblockError.
+    #
+    def deq
+      @mutex.lock
+      if @que.size > 0
+        val = @que.shift
+        if next_waiting = @enq_waiting.shift
+          @que << next_waiting[:value]
+          next_waiting[:pipe] << true
+        end
+        @mutex.unlock
+      else
+        if @kill_deq == true or @kill_deq.include? Thread.current
+          @mutex.unlock
+          raise UnblockError
+        end
+        pipe = Queue.new
+        @deq_waiting << {thread: Thread.current, pipe: pipe}
+        @mutex.unlock
+        val = pipe.pop
+        raise UnblockError if @unblock.equal? val
+      end
+      val
+    end
+
+    alias :pop :deq
+    alias :shift :deq
+    
+    #
+    # Adds an item to the queue. Will block if the queue is full, until an item
+    # is removed from the queue, or until #unblock_enq is called, in which case
+    # it will abandon the enqueue and raise an UnblockError. *Important:* If
+    # data integrity is important, you will need to include any code to deal
+    # with the orphaned item in your rescue clause.
+    #
+    def enq(val)
+      @mutex.lock
+      if @que.size < @max
+        if next_waiting = @deq_waiting.shift
+          next_waiting[:pipe] << val
+        else
+          @que << val
+        end
+        @mutex.unlock
+      else
+        if @kill_enq == true or @kill_enq.include? Thread.current
+          @mutex.unlock
+          raise UnblockError
+        end
+        pipe = Queue.new
+        @enq_waiting << {thread: Thread.current, pipe: pipe, value: val}
+        @mutex.unlock
+        answer = pipe.pop
+        raise UnblockError if @unblock.equal? answer
+      end
+      nil
+    end
+
+    alias :<< :enq
+    alias :push :enq
+    
+    #
+    # Call this method to notify blocking threads that they should no longer
+    # wait to enqueue:
+    #
+    #   queue.unblock_enq([thread1, thread2, ...])
+    #   queue.unblock_enq thread3
+    #   queue.unblock_enq  # unblock all threads
+    #
+    # Note that the effect is permanent; once a thread has been unblocked, it is
+    # blacklisted and can no longer wait on this queue. To clear the enqueue
+    # blacklist, see the #clear_blacklists and #clear_enq methods.
+    #
+    def unblock_enq(thrs=nil)
+      @mutex.synchronize { enq_shutdown thrs }
+    end
+    
+    #
+    # Call this method to notify blocking threads that they should no longer
+    # wait to dequeue:
+    #
+    #   queue.unblock_deq([thread1, thread2, ...])
+    #   queue.unblock_deq thread3
+    #   queue.unblock_deq  # unblock all threads
+    #
+    # Note that the effect is permanent; once a thread has been unblocked, it is
+    # blacklisted and can no longer wait on this queue. To clear the dequeue
+    # blacklist, see the #clear_blacklists and #clear_deq methods.
+    #
+    def unblock_deq(thrs=nil)
+      @mutex.synchronize { deq_shutdown thrs }
+    end
+    
+    #
+    # Stops a thread from blocking on either enqueue or dequeue. Equivalent to
+    # calling:
+    #
+    #   queue.unblock_deq thread1
+    #   queue.unblock_enq thread1
+    #
+    def unblock_waiting(thrs=nil)
+      @mutex.synchronize do
+        enq_shutdown thrs
+        deq_shutdown thrs
+      end
+    end
+
+    #
+    # Clear the enqueue blacklist or remove specified threads to allow them to
+    # block on enqueue once again:
+    #
+    #   queue.clear_enq([thread1, thread2, ...])
+    #   queue.clear_enq thread3
+    #   queue.clear_enq  # allow all threads to block on enqueue
+    #
+    # *Note:* raises a TypeError if you attempt to remove specific
+    # threads from the blacklist after unblocking all. i.e. this is okay:
+    #
+    #   queue.unblock_enq [thread1, thread2]
+    #   queue.clear_enq thread2
+    #
+    # ... but this is not:
+    #
+    #   queue.unblock_enq
+    #   queue.clear_enq thread2
+    #
+    def clear_enq(thrs=nil)
+      @mutex.synchronize { enq_allow thrs }
+    end
+
+    #
+    # Clear the dequeue blacklist or remove specified threads to allow them to
+    # block on dequeue once again:
+    #
+    #   queue.clear_deq([thread1, thread2, ...])
+    #   queue.clear_deq thread3
+    #   queue.clear_deq  # allow all threads to block on dequeue
+    #
+    # *Note:* raises a TypeError if you attempt to remove specific
+    # threads from the blacklist after unblocking all. i.e. this is okay:
+    #
+    #   queue.unblock_deq [thread1, thread2]
+    #   queue.clear_deq thread2
+    #
+    # ... but this is not:
+    #
+    #   queue.unblock_deq
+    #   queue.clear_deq thread2
+    #
+    def clear_deq(thrs=nil)
+      @mutex.synchronize { deq_allow thrs }
+    end
+
+    #
+    # Removes a thread or threads from both blacklists and allows them to block
+    # on either enqueue or dequeue. Equivalent to calling:
+    #
+    #   queue.clear_deq thread1
+    #   queue.clear_enq thread1
+    #
+    def clear_blacklists(thrs=nil)
+      @mutex.synchronize do
+        enq_allow thrs
+        deq_allow thrs
+      end
+    end
+    
+    #
+    # Returns the total number of items currently in the queue.
+    #
+    def length
+      @mutex.synchronize { @que.size }
+    end
+
+    alias :size :length
+    
+    #
+    # Returns true if the queue is empty; false otherwise.
+    #
+    def empty?
+      @mutex.synchronize { @que.size == 0 }
+    end
+
+    #
+    # Returns the number of threads currently waiting on the queue.
+    #
+    def num_waiting
+      @mutex.synchronize { @enq_waiting.size + @deq_waiting.size }
+    end
+
+    #
+    # Deletes all items from the queue. Threads waiting to dequeue will continue
+    # waiting; threads waiting to enqueue will be allowed to proceed (until the
+    # queue is full again).
+    #
+    def clear
+      @mutex.synchronize do
+        @que.clear
+        enqueue_multiple_waiting
+      end
+    end
+
+    #
+    # Completely resets the queue: deletes all queue contents, raises
+    # UnblockError in any waiting threads, and clears all blacklists, such that
+    # all threads can once again block on enqueue or dequeue.
+    #
+    def reset
+      @mutex.synchronize do
+        @que.clear
+        @kill_enq = []
+        @kill_deq = []
+        @enq_waiting.each {|waiting| waiting[:pipe] << @unblock }.clear
+        @deq_waiting.each {|waiting| waiting[:pipe] << @unblock }.clear
+      end
+    end
+
+    #
+    # Sets a new maximum size for the queue. If the new size is larger than the
+    # existing size, any threads blocking on enqueue will be allowed to proceed
+    # (until the queue is full again). *Important:* if the new size is smaller
+    # than the existing size, the queue will _not_ be truncated. Rather, it will
+    # remain oversized until dequeue operations have normalized it to the new,
+    # reduced maximum, and will not be allowed to grow beyond the new size
+    # again. This may result in a brief window where #size reports a value
+    # greater than #max.
+    #
+    def max=(new_max)
+      @mutex.synchronize do
+        raise TypeError unless new_max.is_a? Integer and new_max > 1
+        old_max, @max = @max, new_max
+        enqueue_multiple_waiting if new_max > old_max
+      end
+      new_max
+    end
+    
+    private
+    
+    def enq_shutdown(thrs)
+      if thrs
+        thrs = [thrs] unless thrs.respond_to? :each
+        thrs.each do |thr|
+          @kill_enq << thr
+          @enq_waiting.delete_if do |waiting|
+            if waiting[:thread] == thr
+              waiting[:pipe] << @unblock
+            end
+          end
+        end
+      else
+        @kill_enq = true
+        @enq_waiting.each {|waiting| waiting[:pipe] << @unblock }.clear
+      end
+    end
+
+    def deq_shutdown(thrs)
+      if thrs
+        thrs = [thrs] unless thrs.respond_to? :each
+        thrs.each do |thr|
+          @kill_deq << thr
+          @deq_waiting.delete_if do |waiting|
+            if waiting[:thread] == thr
+              waiting[:pipe] << @unblock
+            end
+          end
+        end
+      else
+        @kill_deq = true
+        @deq_waiting.each {|waiting| waiting[:pipe] << @unblock }.clear
+      end
+    end
+
+    def enq_allow(thrs)
+      if thrs
+        raise TypeError unless @kill_enq.respond_to? :each
+        thrs = [thrs] unless thrs.respond_to? :each
+        thrs.each {|thr| @kill_enq.delete thr }
+      else
+        @kill_enq = []
+      end
+    end
+
+    def deq_allow(thrs)
+      if thrs
+        raise TypeError unless @kill_deq.respond_to? :each
+        thrs = [thrs] unless thrs.respond_to? :each
+        thrs.each {|thr| @kill_deq.delete thr }
+      else
+        @kill_deq = []
+      end
+    end
+
+    def enqueue_multiple_waiting
+      while @que.size < @max and waiting = @enq_waiting.shift
+        @que << waiting[:value]
+        waiting[:pipe] << true
+      end
+    end
+
+  end  # class ImprovedSizedQueue
+
+  module_function
+  
+  #
+  # Returns a new instance of ImprovedQueue::ImprovedSizedQueue. *Note*:
+  # size must be a positive integer >= 2
+  #
+  def new(size)
+    ImprovedSizedQueue.new size
+  end
+
+end  # module ImprovedQueue

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: improved-queue
+version: !ruby/object:Gem::Version
+  version: '1.0'
+  prerelease: 
+platform: ruby
+authors:
+- Lincoln McCormick
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-30 00:00:00.000000000 Z
+dependencies: []
+description: ! 'A simple elaboration on Ruby''s native SizedQueue which allows using
+  the queue
+
+  object to re-awaken a blocked thread and cause it to abandon its blocking
+
+  enqueue/dequeue operation. Useful for simplifying program logic, reducing the
+
+  need for external flags/Muteces (yes, I said Muteces), and for cleanly
+
+  resolving queues on program termination without risk of data loss or deadlock.
+
+
+  Why use this queue? There are two reasons. For one thing, under several
+
+  circumstances it is _considerably_ faster than Ruby''s native SizedQueue. I
+
+  admit I''m not entirely sure why, but I have tested this on multiple platforms
+
+  and it seems to hold true as a generality. You can feel free to confirm or
+
+  dispel that this advantage holds for your use case at your own leisure.
+
+
+  The second reason is the aforementioned simplification of program logic.
+
+  In the case that all data passing through the queues must be preserved on
+
+  program termination, SizedQueue can require some elaborate trickery to ensure
+
+  that even the most remote possibility of deadlock is removed.
+
+  ImprovedSizedQueue solves this problem by making it possible to use the queue
+
+  to pass control messages between threads, irrespective of the queue''s actual
+
+  content.'
+email: iamtheiconoclast@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/improved-queue.rb
+homepage: http://rubygems.org/gems/improved-queue
+licenses:
+- GPL v3
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Improved Sized Queue
+test_files: []