hash_queue 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@hash-queue --create

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1
+
++ Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Michal Krejčí
+
+MIT License
+
+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,285 @@
+# HashQueue
+
+Simple namespaced Queue for highly concurrent environments. Maintains separate queues for different keys accessible from numerous threads without a trouble. Think of it as an extension to stdlib's Queue class. It could be even used as its replacement. Features nice locking capabilities, read on.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hash_queue', '~> 0.1'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hash_queue
+    
+For those living on the edge:
+
+    gem 'hash_queue', git: 'git@github.com:mikekreeki/hash_queue.git'
+    
+..with Bundler 1.1 or newer:
+
+    gem 'mimi', github: 'mikekreeki/hash_queue'
+
+## Usage
+
+To initialize new HashQueue just simply do:
+
+```ruby
+require 'hash_queue'
+
+hash_queue = HashQueue.new
+```
+
+### Queueing
+
+To queue stuff it's just as easy as:
+
+```ruby
+hash_queue[:my_queue].queue Stuff.new
+
+# or
+
+hash_queue.queue :my_queue, Stuff.new
+```
+
+Keys (or namespaces if you prefer) can be anything you want. Usually those will be symbols or strings but don't need to be. Objects, classes, numbers or even `true` or `nil` will work. Same applies for queued items.
+
+`#queue` is aliased as `#enqueue` and `#push` for convenience on both hash_queue and individual queues.
+
+### Working with hash_queue as a whole
+
+HashQueue instances offer some handy methods.
+
+##### size 
+
+Returns combined sizes of all queues managed.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue.queue :animals, "tenderlove's cat"
+hash_queue.queue :favourite_rubies, 'rubinius'
+hash_queue.size  # => 2
+```
+
+##### empty?
+
+Returns `true` or `false` whether hash_queue is empty or not.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue.empty? # => true
+hash_queue.queue :animals, "tenderlove's cat"
+hash_queue.empty? # => false
+```
+
+##### clear
+
+Removes all managed queues.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue.queue :animals, "tenderlove's cat"
+hash_queue.empty? # => false
+hash_queue.clear
+hash_queue.empty? # => true
+```
+
+##### clean
+
+When using lots of different keys (e.g. hostnames) your HashQueue instance will eventually grow in size. `#clean` removes empty queues to save precious RAM and speed things up. It's just a maintenance method, it won't break anything, you can use individual queues later the same way you're doing now, they will be automatically redeclared when you touch them.
+
+##### keys 
+
+Returns maintained keys.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue.queue :foo, 'Now or never.' 
+hash_queue.keys # => [:foo]
+```
+
+Not very interesting but comes handy, for interesting stuff check Popping and Locking section down below.
+
+### Working with individual queues
+
+To get a specific queue you want to put your hands on, just do:
+
+```ruby
+hash_queue[:my_queue]
+```
+
+It also features some not that fancy methods like `#size`, `#empty?` and `#clear`. 
+
+It's also possible to bypass namespacing capabilities and use HashQueue's individual queue directly as a replacement for stdlib's Queue. Just initialize new queue:
+
+```ruby
+queue = HashQueue::Queue.new
+queue.push :foo
+queue.size # => 1
+queue.pop # => :foo
+queue.empty? # => true
+```
+
+### Popping stuff out of the queues
+
+There are two way to pop stuff from HashQueue instance. One way is to pop from all the queues at once. When you call `pop` on HashQueue instance it will pop one item from each individual queue it manages (unless it's locked). Always returns an Array.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue.queue :animals, :cat
+hash_queue.queue :animals, :dog
+hash_queue.queue :rubyists, :tenderlove
+hash_queue.queue :rubyists, :yehuda
+hash_queue.queue :rubyists, :matz
+
+hash_queue.pop # => [:cat, :tenderlove]
+hash_queue.pop # => [:dog, :yehuda]
+hash_queue.pop # => [:matz]
+```
+
+`#pop` method takes optional `:size` option with which you can specify how many items you want to pop out of each queue.
+
+```ruby
+hash_queue = HashQueue.new
+
+10.times { |i| hash_queue.queue :queue_1, i }
+10.times { |i| hash_queue.queue :queue_2, i + 100 }
+
+hash_queue.pop(size: 2) # => [0, 1, 100, 101]
+```
+
+Or you can provide `:blocking` option. When called with `blocking: true` it won't return until there's something to return. When there's nothing to be returned (either all individual queues are empty, locked or there aren't any) the call holds until something is queued from a background thread or some queue is unlocked. 
+
+```ruby
+hash_queue = HashQueue.new
+
+Thread.new {
+  sleep 1
+  @hash_queue[:foo].queue :bar
+}   
+     
+@hash_queue.pop(blocking: true) # waits until a background thread queues something and then returns, [:bar] in this case
+```
+
+You can also pop items from individual queues:
+
+```ruby
+hash_queue = HashQueue.new
+3.times { hash_queue[:foo].queue Object.new }
+
+hash_queue[:foo].pop # => #<Object:0x000001008d4658>
+hash_queue[:foo].pop(size: 2) # => [#<Object:0x000001008ae228>, #<Object:0x000001008ae200>]
+```
+
+You can use same options as mentioned above.
+
+### Locking capabilities
+
+HashQueue was designed for a specific use case and for that it provides a flexible locking facility.
+
+You can lock a specific queue so you won't be able to pop until you unlock it.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue[:foo].queue Object.new
+hash_queue[:foo].lock
+hash_queue[:foo].pop # => nil
+hash_queue[:foo].unlock
+hash_queue[:foo].pop # => #<Object:0x000001008a5bf0>
+```
+
+And you can place multiple locks on a queue and then you'll need to unlock them all to be able to pop stuff out again.
+
+```ruby
+hash_queue = HashQueue.new
+hash_queue[:foo].queue Object.new
+hash_queue[:foo].lock(3)
+hash_queue[:foo].pop # => nil
+hash_queue[:foo].unlock
+hash_queue[:foo].pop # => nil
+hash_queue[:foo].unlock
+hash_queue[:foo].unlock
+hash_queue[:foo].pop # => #<Object:0x000001008a5bf0>
+```
+
+Both `#lock` and `#unlock` take as an argument number of locks you want to put or remove from the queue. Defaults to `1`. There's even a convenient `#unlock_all` method and `#count_locks` that returns current number of locks placed on the queue. You can always check whether a specific queue is locked with `#locked?`.
+
+```ruby
+hash_queue[:foo].lock
+hash_queue[:foo].locked? # => true
+hash_queue[:foo].unlock
+hash_queue[:foo].locked? # => false
+```
+
+Here it gets a little bit tricky. When popping stuff out of a queue you can specify `lock: true` option. That means while popping it will place the same number of locks on the queue as the number of items it pops out. 
+
+```ruby
+hash_queue[:foo].locked? # => false
+hash_queue[:foo].pop(size: 2, lock: true)
+hash_queue[:foo].locked? # => true
+hash_queue[:foo].count_locks # => 2
+```
+
+While it seems complicated the use case is fairly simple. Locking facility ensures that only a certain number of items could be out of a specific queue at one time. Imagine a crawler, you have opened 200 parallel connections but want to make sure you won't open more than 10 connections to one server at the time. You can use HashQueue as a local queue for URLs to be crawled, hostnames using as a key to keep separate queues for each hostname. You pop out 10 URLs placing 10 locks on a hostname, when a page is processed then unlock one lock. 
+
+You may see a flaw in this schema, because I lied a little. The issue with this example is that you can't pop new URLs to process until all previous 10 have been processed, right? You would have to wait until all locks have been unlocked. Well, HashQueue got this covered - You can pop from a queue while the queue is locked! 
+
+Imagine a queue with a lot of items in it. When you tell a queue to pop X items but the queue has Y locks on it, it just pops `X-Y` items. When you look in specs you'll find something like this:
+
+```ruby
+it 'should allow you to pop items even if locked when you want more items then there are locks but taking existing locks into account' do        
+  @hash_queue[:foo].lock(2)
+  @hash_queue[:foo].pop(size: 10).size.must_equal 8
+end
+```
+
+## Acknowledgements
+
+Requires Ruby 1.9. Tested under MRI 1.9.3 and JRuby.
+
+## TODO
+
++ Someone please check and correct my grammar in readme. English is not my native language. I will send you my love and hug over Twitter.
+
+## Specs
+
+To run the specs just run:
+
+    rake
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+This library is released under the MIT license.
+
+```
+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/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/lib')
+
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+end
+
+desc "Run tests"
+task :default => :test

data/hash_queue.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/hash_queue/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Michal Krejčí"]
+  gem.email         = ["mikekreeki@gmail.com"]
+  gem.description   = %q{Threadsafe namespaced Queue with locking capabilities.}
+  gem.summary       = %q{Threadsafe namespaced Queue with locking capabilities.}
+  gem.homepage      = "http://github.com/mikekreeki/hash_queue"
+
+  gem.add_development_dependency('minitest')
+  gem.add_development_dependency('turn')
+  gem.add_development_dependency('term-ansicolor')
+  
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "hash_queue"
+  gem.require_paths = ["lib"]
+  gem.version       = HashQueue::VERSION
+end

data/lib/hash_queue/hash.rb

@@ -0,0 +1,109 @@
+module HashQueue
+  class Hash
+    
+    def initialize
+      @hash_queue = {}
+      @mutex = Mutex.new
+    end
+    
+    def [](key)
+      QueueProxy.new(self, key)
+    end
+    
+    def queue(key, obj)
+      get_queue(key).queue obj      
+    end
+    alias_method :enqueue, :queue
+    alias_method :push, :queue
+    
+    def pop(options = {})
+      loop do
+        results = pop_from_queues(options)
+        
+        if options[:blocking] 
+          return results unless results.empty?
+          sleep 0.01
+        else
+          return results
+        end
+      end
+    end
+    alias_method :shift, :pop
+    
+    def size
+      @mutex.synchronize do
+        @hash_queue.each_value.inject(0) do |sum, queue|
+          sum += queue.size
+        end 
+      end
+    end
+    alias_method :count, :size
+    alias_method :length, :size
+    
+    def empty?
+      size.zero?
+    end
+    
+    def keys
+      @mutex.synchronize do 
+        @hash_queue.keys
+      end
+    end
+    
+    def clean
+      @mutex.synchronize do 
+        @hash_queue.reject! do |key, queue|
+          queue.empty?
+        end
+      end
+    end
+    
+    def clear
+      @mutex.synchronize do 
+        @hash_queue.clear
+      end
+    end
+    
+    def get_queue(key)
+      @mutex.synchronize do 
+        @hash_queue.fetch(key) do
+          @hash_queue[key] = Queue.new
+        end
+      end
+    end
+    
+    private
+    
+    def pop_from_queues(options)
+      options = options.dup
+      options.delete(:blocking)
+      
+      @mutex.synchronize do
+        @hash_queue.each_value.each_with_object([]) do |queue, results|
+          queue.pop(options,results)
+        end
+      end
+    end
+       
+  end
+  
+  class QueueProxy
+    
+    [ :queue, :enqueue, :push, :<<, :pop, :shift, :size, :count, :length, :empty?, :clear, :lock, :unlock, 
+     :locked?, :unlock_all, :count_locks, :locks_count].each do |m|
+      define_method m do |*args|
+        subject.send m, *args
+      end
+    end
+
+    def initialize(parent, key)
+      @parent = parent
+      @key = key
+    end
+    
+    def subject
+      @parent.get_queue(@key)
+    end
+
+  end
+end

data/lib/hash_queue/queue/lockable.rb

@@ -0,0 +1,50 @@
+module HashQueue
+  module Lockable
+    
+    def lock(n = 1)
+      @mutex.synchronize do
+        _lock(n)
+      end
+    end
+    
+    def unlock(n = 1)
+      @mutex.synchronize do
+        @locks.shift(n)
+      end
+    end
+    
+    def locked?
+      @mutex.synchronize do
+        _locked?
+      end
+    end
+    
+    def unlock_all
+      @mutex.synchronize do
+        @locks.clear
+      end
+    end
+    
+    def count_locks
+      @mutex.synchronize do
+        _count_locks
+      end
+    end
+    alias_method :locks_count, :count_locks
+    
+    private
+    
+    def _lock(n = 1)
+      n.times { @locks.push true }
+    end
+    
+    def _locked?
+      not @locks.empty?
+    end
+    
+    def _count_locks
+      @locks.count
+    end 
+    
+  end
+end

data/lib/hash_queue/queue.rb

@@ -0,0 +1,89 @@
+require 'hash_queue/queue/lockable'
+
+module HashQueue
+  class Queue
+    include Lockable
+    
+    def initialize
+      @mutex = Mutex.new 
+      @queue = []
+      @locks = []
+    end
+    
+    def queue(obj)
+      @mutex.synchronize do
+        @queue.push obj
+      end
+    end
+    alias_method :enqueue, :queue
+    alias_method :push, :queue
+    alias_method :<<, :queue
+    
+    def pop(options = {}, results = [])
+      if options[:blocking] 
+        loop do 
+          result = _pop(options, results)
+          
+          return result unless result.nil? or result == [] 
+          sleep 0.01
+        end
+      else
+        _pop(options,results)
+      end
+    end
+    alias_method :shift, :pop
+    
+    def size
+      @mutex.synchronize do
+        @queue.size
+      end
+    end
+    alias_method :count, :size
+    alias_method :length, :size
+    
+    def empty?
+      @mutex.synchronize do
+        _empty?
+      end
+    end
+    
+    def clear
+      @mutex.synchronize do
+        @queue.clear
+      end
+    end
+    
+    private
+    
+    def _pop(options,results)
+      @mutex.synchronize do
+        size = options.fetch(:size, 1)
+        
+        if _locked? and _count_locks >= size
+          if options.key? :size
+            return [] 
+          else
+            return nil
+          end
+        end
+              
+        (size - _count_locks).times do
+          break if _empty?
+          results.push @queue.shift
+          _lock if options[:lock]
+        end
+        
+        if options.key? :size 
+          results
+        else
+          results[0]
+        end
+      end      
+    end 
+    
+    def _empty?
+      @queue.empty?
+    end
+      
+  end
+end

data/lib/hash_queue/version.rb

@@ -0,0 +1,3 @@
+module HashQueue  
+  VERSION = "0.1.0"
+end

data/lib/hash_queue.rb

@@ -0,0 +1,10 @@
+require 'hash_queue/hash'
+require 'hash_queue/queue'
+
+module HashQueue
+  extend self
+    
+  def new
+    Hash.new
+  end
+end

data/spec/hash_queue/hash_queue_spec.rb

@@ -0,0 +1,167 @@
+require 'spec_helper'
+#require 'timeout'
+
+describe HashQueue do
+  it 'should be able to create new HashQueue instance' do
+    HashQueue.new.must_be_instance_of HashQueue::Hash
+  end
+end
+
+describe HashQueue::Hash do
+  
+  describe 'when initialized' do 
+    before do
+      @hash_queue = HashQueue::Hash.new
+    end
+    
+    it 'should be empty' do
+      @hash_queue.empty?.must_equal true
+    end
+    
+    it 'should return correct size' do
+      @hash_queue.size.must_equal 0
+    end
+  
+    it 'should create Queues on the fly' do
+      @hash_queue[:foo].queue 1
+      @hash_queue.keys.size.must_equal 1
+    end
+    
+    it 'should be able to queue stuff' do
+      @hash_queue.queue :foo, 1
+      @hash_queue.size.must_equal 1    
+    end
+    
+    it 'should be able to get Queue object when asked with a key' do
+      @hash_queue.get_queue(:foo).must_be_instance_of HashQueue::Queue
+      @hash_queue.get_queue(:non_existent).must_be_instance_of HashQueue::Queue
+    end
+  end
+  
+  
+  describe 'when we queue stuff' do
+    before do
+      @hash_queue = HashQueue::Hash.new
+      @hash_queue.queue :foo, true
+      @hash_queue.queue :bar, false
+    end
+    
+    it 'shouldnt be empty' do
+      @hash_queue.empty?.must_equal false
+    end
+  
+    it 'should return correct size' do
+      @hash_queue.size.must_equal 2
+    end
+    
+    it 'should return maintained keys' do
+      @hash_queue.keys.sort.must_equal [:foo, :bar].sort
+    end
+    
+    it 'should be able to clear itself' do
+      @hash_queue.clear
+      @hash_queue.size.must_equal 0
+      @hash_queue.keys.must_equal []
+    end
+    
+    it 'should be able to clean itself' do
+      @hash_queue[:foo].pop
+      @hash_queue.clean
+      @hash_queue.size.must_equal 1
+      @hash_queue.keys.must_equal [:bar]
+    end
+  end
+  
+  
+  describe 'when we queue an array' do
+    before do
+      @hash_queue = HashQueue::Hash.new
+      @hash_queue.queue :foo, [1]
+      @hash_queue.queue :bar, [2]
+    end
+    
+    it 'should return array values' do
+      @hash_queue.pop.sort.must_equal [[1],[2]].sort
+    end
+  end
+  
+  describe 'when we queue weird stuff' do
+    before do
+      @hash_queue = HashQueue::Hash.new
+    end
+    
+    describe 'like nil' do
+      before do
+        @hash_queue.queue :foo, nil
+      end
+      
+      it 'should return nil when popping' do
+        @hash_queue.pop.must_equal [nil]
+      end
+    end
+    
+    describe 'like an empty array' do
+      before do
+        @hash_queue.queue :foo, []
+      end
+      
+      it 'should return an empty array when popping' do
+        @hash_queue.pop.must_equal [[]]
+      end
+    end
+  
+  end
+  
+  describe 'when popping' do
+    
+    describe 'from empty HashQueue instance' do
+      before do
+        @hash_queue = HashQueue::Hash.new
+      end
+      
+      it 'should return empty array' do
+        @hash_queue.pop.must_equal []
+      end
+    end
+  
+  
+    describe 'from non-empty HashQueue instance' do
+      before do
+        @hash_queue = HashQueue::Hash.new
+        @hash_queue[:foo].queue 1
+        @hash_queue[:foo].queue 2
+        @hash_queue[:bar].queue 3
+        @hash_queue[:bar].queue 4
+      end
+      
+      it 'should return array of items, one from each queue' do
+        @hash_queue.pop.sort.must_equal [1,3].sort
+      end
+      
+      it 'should return appropriate number of items from each queue when size option specified' do
+        @hash_queue.pop(size: 2).sort.must_equal [1,2,3,4]
+      end
+      
+    end
+  
+    
+    describe 'with blocking option' do
+      before do
+        @hash_queue = HashQueue::Hash.new
+      end
+      
+      it 'should wait until some results are available' do
+        Thread.new {
+          sleep 0.5
+          @hash_queue[:foo].queue :bar
+        }   
+             
+        @hash_queue.pop(blocking: true).wont_be_empty
+      end
+      
+    end
+  
+  end
+  
+end
+

data/spec/hash_queue/queue_proxy_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe HashQueue::QueueProxy do
+  before do
+    hash_queue = HashQueue.new
+    @proxy = HashQueue::QueueProxy.new(hash_queue, :foo)
+  end
+  
+  it 'should proxy public methods of Queue and modules included to Queue object itself in sane matter' do
+    methods = [HashQueue::Queue, HashQueue::Lockable].map{ |k| k.instance_methods(false) }.flatten
+    methods.each do |m|
+      @proxy.must_respond_to m
+    end
+  end
+  
+  it 'should return the subject, Queue object itself (but really never use it directly, misbehaves in edge cases)' do
+    @proxy.subject.must_be_instance_of HashQueue::Queue
+  end
+end
+

data/spec/hash_queue/queue_spec.rb

@@ -0,0 +1,152 @@
+require 'spec_helper'
+
+describe HashQueue::Queue do
+  before do
+    @queue = HashQueue::Queue.new
+  end
+  
+  describe 'when initialized' do
+    
+    it 'should be empty' do
+      @queue.empty?.must_equal true
+      @queue.size.must_equal 0
+    end
+    
+  end
+  
+  describe 'when queued stuff' do
+    before do
+      @queue.queue 1
+      @queue.queue 2
+    end
+    
+    it 'shouldnt be empty' do
+      @queue.empty?.must_equal false
+      @queue.size.must_equal 2
+    end
+    
+    it 'should be able to clear itself' do
+      @queue.clear
+      @queue.empty?.must_equal true
+    end
+    
+    it 'should be able to pop the stuff in right order' do
+      @queue.pop.must_equal 1
+      @queue.pop.must_equal 2
+    end
+    
+    it 'should be empty when you pop all the stuff' do
+      @queue.pop
+      @queue.empty?.must_equal false
+      @queue.pop
+      @queue.empty?.must_equal true
+    end
+    
+    it 'should be able to pop more stuff if you tell it how much stuff do you want' do
+      @queue.pop(size: 2).must_equal [1, 2]
+    end
+    
+    it 'should return an array every time when size option specified' do
+     @queue.pop(size: 1).must_equal [1]
+     
+     @queue.clear
+     @queue.pop(size: 1).must_equal []
+    end
+  end
+  
+  describe 'when we queue weird stuff' do
+     describe 'like nil' do
+       before do
+         3.times { @queue.queue nil }
+       end
+
+       it 'should return nil when popping' do
+         @queue.pop.must_equal nil
+         @queue.pop(size: 2).must_equal [nil, nil]
+       end
+     end
+
+     describe 'like an empty array' do
+       before do
+         3.times { @queue.queue [] }
+       end
+
+       it 'should return an empty array when popping' do
+         @queue.pop.must_equal []
+         @queue.pop(size: 2).must_equal [[], []]
+       end
+     end
+
+   end
+  
+  describe 'when popping with blocking option' do
+    it 'should wait until some results are available' do
+      Thread.new {
+        sleep 0.5
+        @queue.queue 1
+      }   
+           
+      @queue.pop(blocking: true, size: 1).wont_be_empty
+    end
+    
+  end
+  
+  describe 'locking' do
+    
+    it 'should be unlocked when initialized' do
+      @queue.locked?.must_equal false
+    end
+    
+    it 'should be able to be locked' do
+      @queue.lock
+      @queue.locked?.must_equal true
+      @queue.count_locks.must_equal 1
+    end
+    
+    it 'should be able to be unloacked when locked' do
+      @queue.lock
+      @queue.unlock
+      @queue.locked?.must_equal false
+      @queue.count_locks.must_equal 0
+    end
+    
+    
+    it 'should be able to specify how much locks you want to apply' do
+      @queue.lock(2)
+      @queue.count_locks.must_equal 2
+      @queue.unlock(2)
+      @queue.count_locks.must_equal 0
+    end
+    
+    it 'should be able to unlock all locks' do
+      @queue.lock(2)
+      @queue.unlock_all
+      @queue.locked?.must_equal false
+      @queue.count_locks.must_equal 0
+    end
+    
+    describe 'when popping with lock option' do
+      before do
+        10.times { @queue.queue :foo }
+      end
+      
+      it 'should place lock on the queue' do
+        @queue.pop(lock: true)
+        @queue.locked?.must_equal true
+        @queue.count_locks.must_equal 1
+      end
+      
+      it 'should put appropriate amount of locks on the queue when custom pop size is specified' do
+        @queue.pop(size: 2, lock: true)
+        @queue.locked?.must_equal true
+        @queue.count_locks.must_equal 2 
+      end
+      
+      it 'should allow you to pop items even if locked when you want more items then there are locks but taking existing locks into account' do        
+        @queue.lock(2)
+        @queue.pop(size: 10).size.must_equal 8
+      end
+    end
+    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'bundler/setup'
+
+require 'minitest/autorun'
+require 'turn/autorun'
+
+require 'hash_queue'
+

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: hash_queue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Michal Krejčí
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: turn
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: term-ansicolor
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Threadsafe namespaced Queue with locking capabilities.
+email:
+- mikekreeki@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- hash_queue.gemspec
+- lib/hash_queue.rb
+- lib/hash_queue/hash.rb
+- lib/hash_queue/queue.rb
+- lib/hash_queue/queue/lockable.rb
+- lib/hash_queue/version.rb
+- spec/hash_queue/hash_queue_spec.rb
+- spec/hash_queue/queue_proxy_spec.rb
+- spec/hash_queue/queue_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/mikekreeki/hash_queue
+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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Threadsafe namespaced Queue with locking capabilities.
+test_files:
+- spec/hash_queue/hash_queue_spec.rb
+- spec/hash_queue/queue_proxy_spec.rb
+- spec/hash_queue/queue_spec.rb
+- spec/spec_helper.rb