circular_queue 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+doc
+.yardoc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in circular_queue.gemspec
+gemspec

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/circular_queue.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "circular_queue"
+  s.version     = "0.0.1"
+  s.authors     = ["Andy Lindeman"]
+  s.email       = ["alindeman@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Data structure that uses a single, fixed-size buffer as if it were connected end-to-end}
+  s.description = %q{A circular queue (also called a circular buffer or ring buffer) is useful when buffering data streams}
+
+  s.rubyforge_project = "circular_queue"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec", "~>2.7.0"
+  s.add_development_dependency "rake", "~>0.9.2"
+  s.add_development_dependency "yard"
+end

data/lib/circular_queue.rb

@@ -0,0 +1,149 @@
+require "thread"
+
+# A thread-safe queue with a size limitation. When more elements than the
+# capacity are added, the queue either loops back on itself (removing the
+# oldest elements first) or raises an error (if `enq!` is used).
+#
+# Useful for streaming data where keeping up with real-time is more important
+# than consuming every message if load rises and the queue backs up.
+#
+# Exposes the same interface as the `Queue` from the Ruby stdlib.
+#
+# Example:
+#
+#     # Capacity of 3
+#     q = CircularQueue.new(3)
+#
+#     q << 1 # => [1]
+#     q << 2 # => [1, 2]
+#     q << 3 # => [1, 2, 3]
+#
+#     # Elements are replaced when the queue reaches capacity
+#     q << 4 # => [4, 2, 3]
+#     q << 5 # => [4, 5, 3]
+class CircularQueue
+  # Returns the maximum number of elements that can be enqueued
+  # @return [Integer]
+  attr_reader :capacity
+
+  # Returns the number of elements in the queue
+  # @return [Integer]
+  attr_reader :size
+  alias length size
+
+  # Creates a new queue of the specified capacity
+  # @param [Integer] the maximum capacity of the queue
+  def initialize(capacity)
+    @capacity = capacity
+    @data     = Array.new(capacity)
+
+    @mutex    = Mutex.new
+    @waiting  = Array.new
+
+    clear
+  end
+
+  # Adds an item to the queue
+  # @param [Object] item to add
+  def enq(item)
+    @mutex.synchronize do
+      enq_item(item)
+      wakeup_next_waiter
+    end
+  end
+  alias <<   enq
+  alias push enq
+
+  # Adds an item to the queue, raising an error if the queue is full
+  # @param [Object] item to add
+  # @raise [ThreadError] queue is full
+  def enq!(item)
+    @mutex.synchronize do
+      raise ThreadError.new("Queue is full") if full?
+
+      enq_item(item)
+      wakeup_next_waiter
+    end
+  end
+  alias push! enq!
+
+  # Removes an item from the queue
+  # @param [Boolean] true to raise an error if the queue is empty; otherwise,
+  #                  waits for an item to arrive from another thread
+  # @raise [ThreadError] non_block was true and the queue was empty
+  def deq(non_block = false)
+    @mutex.synchronize do
+      while true
+        if empty?
+          raise ThreadError.new("Queue is empty") if non_block
+
+          @waiting.push(Thread.current) unless @waiting.include?(Thread.current)
+          @mutex.sleep
+        else
+          return deq_item
+        end
+      end
+    end
+  end
+  alias shift deq
+  alias pop   deq
+
+  # Removes all items from the queue
+  def clear
+    @mutex.synchronize do
+      @size  = 0
+      @front = 0
+      @back  = 0
+    end
+  end
+
+  # Returns whether the queue is empty
+  # @return [Boolean] queue is empty
+  def empty?
+    @size == 0
+  end
+
+  # Returns whether the queue is full
+  # @return [Boolean] queue is full
+  def full?
+    @size == @capacity
+  end
+
+  # Returns the number of threads waiting for items to arrive in the queue
+  # @return [Integer] number of threads waiting
+  def num_waiting
+    @waiting.length
+  end
+
+  private
+
+  def enq_item(item)
+    @data[@back] = item
+
+    @size += 1 unless full?
+
+    @back += 1
+    @back %= @capacity
+  end
+
+  def deq_item
+    item = @data[@front]
+
+    @size  -= 1
+
+    @front += 1
+    @front %= @capacity
+
+    item
+  end
+
+  def wakeup_next_waiter
+    begin
+      if thread = @waiting.shift
+        thread.wakeup
+      end
+    rescue ThreadError
+      retry
+    end
+  end
+end

data/spec/circular_queue_spec.rb

@@ -0,0 +1,97 @@
+require "spec_helper"
+
+describe CircularQueue do
+  let(:capacity) { 5 }
+  subject        { described_class.new(capacity) }
+
+  describe "initialization" do
+    it "can be initialized with a capacity" do
+      subject.capacity.should == capacity
+    end
+  end
+
+  describe "adding items" do
+    it "accepts new items" do
+      subject.enq(1234)
+      subject.deq.should == 1234
+    end
+
+    it "increases its size when a new item is added" do
+      subject.enq(1234)
+      subject.size.should == 1
+    end
+
+    it "presents the appearance of accepting infinite items" do
+      1.upto(capacity * 2) { |i| subject.enq(i) }
+
+      1.upto(capacity) do |i|
+        subject.deq.should == i + capacity
+      end
+
+      subject.size.should be_zero
+    end
+
+    it "raises an error if the queue is full and enq! is used to add items" do
+      1.upto(capacity) { |i| subject.enq(i) }
+
+      expect {
+        subject.enq!(1)
+      }.to raise_error(ThreadError)
+    end
+  end
+
+  describe "removing items" do
+    it "removes items from the queue until the queue is empty" do
+      1.upto(capacity) { |i| subject.enq(i) }
+
+      1.upto(capacity) do |i|
+        subject.deq.should == i
+      end
+
+      subject.size.should be_zero
+    end
+
+    context "when empty" do
+      context "non-blocking" do
+        it "raises a ThreadError if the queue is empty" do
+          subject.clear
+
+          expect {
+            subject.deq(true)
+          }.to raise_error(ThreadError)
+        end
+      end
+
+      context "blocking" do
+        it "waits for another thread to add an item" do
+          # Another queue that is doing work is required or a deadlock will
+          # be detected
+          enqueue = false
+          done    = false
+
+          enqueue_thread = Thread.new do
+            until done
+              subject.enq(1) if enqueue
+            end
+          end
+
+          begin
+            enqueue = true
+            subject.deq.should == 1
+          ensure
+            done = true
+          end
+        end
+      end
+    end
+  end
+
+  describe "clearing the queue" do
+    it "removes all items from the queue" do
+      subject.enq(1)
+      subject.clear
+
+      subject.size.should be_zero
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require File.expand_path("../lib/circular_queue", File.dirname(__FILE__))

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: circular_queue
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andy Lindeman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-17 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2156106760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :development
+  prerelease: false
+  version_requirements: *2156106760
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2156106060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: *2156106060
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &2156105200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2156105200
+description: A circular queue (also called a circular buffer or ring buffer) is useful
+  when buffering data streams
+email:
+- alindeman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Rakefile
+- circular_queue.gemspec
+- lib/circular_queue.rb
+- spec/circular_queue_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -2375285051311577887
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -2375285051311577887
+requirements: []
+rubyforge_project: circular_queue
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Data structure that uses a single, fixed-size buffer as if it were connected
+  end-to-end
+test_files:
+- spec/circular_queue_spec.rb
+- spec/spec_helper.rb
+has_rdoc: