unified-queues 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/CHANGES.txt

@@ -0,0 +1,3 @@
+
+0.1.0 (2011-09-23) 
+* initial version

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+  gem "abstract", ">= 1.0.0"
+  gem "hash-utils", ">= 0.18.1"
+  gem "lookup-hash", ">= 0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", ">= 1.0.0"
+  gem "jeweler2", ">= 2.0.0"
+  gem "riot", ">= 0.12.3"
+  gem "PriorityQueue", ">= 0"
+  gem "algorithms", ">= 0"
+  gem "depq", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    PriorityQueue (0.1.2)
+    abstract (1.0.0)
+    algorithms (0.3.0)
+    depq (0.6)
+    git (1.2.5)
+    hash-utils (1.0.0)
+      ruby-version
+    jeweler2 (2.0.9)
+      git (>= 1.2.5)
+    lookup-hash (0.2.0)
+      hash-utils (>= 0.11.0)
+    riot (0.12.5)
+      rr
+    rr (1.0.4)
+    ruby-version (0.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  PriorityQueue
+  abstract (>= 1.0.0)
+  algorithms
+  bundler (>= 1.0.0)
+  depq
+  hash-utils (>= 0.18.1)
+  jeweler2 (>= 2.0.0)
+  lookup-hash
+  riot (>= 0.12.3)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 - 2012 Martin Kozák (martinkozak@martinkozak.net)
+
+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,88 @@
+Ruby Unified Queues
+===================
+
+**unified-queues** is an unified queue interface which unifies 
+several both normal and priority queue implementations to the single 
+queue API. Usage is simple: 
+
+    require "unified-queues"
+    
+    # Depq
+    require "depq"
+    depq_queue = UnifiedQueues::Single::new(Depq)
+
+    # Ruby Array
+    array_queue = UnifiedQueues::Single::new(Array)
+
+    # ...the same API!
+    depq_queue.push(:foo)
+    depq_queue.pop!    # will return :foo
+
+    array_queue.push(:foo)
+    array_queue.pop!   # will return :foo
+
+Evented queues are also supported by transparent way; simply provide 
+blocks to calls instead of expecting return values. Currently, the 
+following classes are supported:
+
+* `Queue` and `Array` (from Ruby),
+* `Depq` (from `depq` gem),
+* `Containers::Heap` (from `algorithms` gem),
+* `CPriorityQueue`, `PoorPriorityQueue` and `RubyPriorityQueue` (from `priority_queue` gem),
+* `EventedQueue` (from `evented-queue` gem).
+    
+And for multiqueues:
+  
+* `UnifiedQueues::Single` (from `unified-queues` gem),
+* `EMJack::Connection` (from `em-jack` beanstalk gem)
+
+### Multiqueue Support
+
+*Multiqueue* is a queue which is composed of more queues and single 
+queue can be selected for writing into or reading from. An example 
+of this type of queues are for example some queue servers which 
+typically contain more than one queue. By this way, an unified queue 
+interface can be implemented for more queue servers too.
+
+Reasonable example isn't available, but see the [QRPC][1] project 
+where unified multiqueues are implemented.
+
+Multiqueue driver for single unified queue interface is also 
+implemented, so it's possible to build a multiqueue interface from 
+the common datatypes or Ruby priority queues implementations by 
+an universal and transparent way.
+
+##### Hardcore example
+
+Hardcore example can by for example following (bonus points for 
+decoding what it does):
+    
+    UnifiedQueues::Multi::new UnifiedQueues::Single, ::EM::Wrapper::new(REUQ),  UnifiedQueues::Single, CPriorityQueue
+
+Well, it creates an unified queue interface from the `CPriorityQueue`
+library, wraps it to an evented interface (converts standard 
+interface to the evented one), converts it to the evented unified 
+queue interface again and creates a multiqueue interface from it. It 
+may sounds difficulty, but it simply *creates an evented unified 
+multiqueue interface from non-evented proprietary library*. Cool.
+
+Contributing
+------------
+
+1. Fork it.
+2. Create a branch (`git checkout -b 20101220-my-change`).
+3. Commit your changes (`git commit -am "Added something"`).
+4. Push to the branch (`git push origin 20101220-my-change`).
+5. Create an [Issue][9] with a link to your branch.
+6. Enjoy a refreshing Diet Coke and wait.
+
+
+Copyright
+---------
+
+Copyright © 2011 - 2012 [Martin Kozák][10]. See `LICENSE.txt` for
+further details.
+
+[1]: http://github.com/martinkozak/qrpc
+[9]: http://github.com/martinkozak/unified-queues/issues
+[10]: http://www.martinkozak.net/

data/Rakefile

@@ -0,0 +1,29 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'jeweler2'
+
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "unified-queues"
+  gem.homepage = "http://github.com/martinkozak/unified-queue"
+  gem.license = "MIT"
+  gem.summary = 'Unifies many queue implementations under the single interface. Includes both single queue libraries and multiple queue libraries.'
+  gem.email = "martinkozak@martinkozak.net"
+  gem.authors = ["Martin Kozák"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/debug

@@ -0,0 +1,33 @@
+#!/usr/bin/ruby
+# encoding: utf-8
+# (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+$:.push("./lib")
+$:.unshift("./lib")
+
+require "em-jack"
+require "unified-queues"
+require "em-batch"
+
+EM::run do
+    q = UnifiedQueues::Multi::new(EMJack::Connection)
+    
+    queue = EM::Sequencer::new(q)
+    queue.use(:xxx)
+    queue.push("x", 2)
+    queue.push("y", 1)
+    queue.subscribe(:xxx)
+    
+    queue.execute do
+        queue = EM::Sequencer::new(q)
+        queue.pop
+        queue.pop
+        queue.pop
+          
+        queue.execute do
+            p queue.results
+            
+            #q.pop 
+        end
+    end
+end

data/lib/unified-queues.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+# (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+require "unified-queues/single"
+require "unified-queues/multi"

data/lib/unified-queues/multi.rb

@@ -0,0 +1,209 @@
+# encoding: utf-8
+# (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+require "unified-queues/multi/driver"
+require "hash-utils/module"
+
+##
+# Base 9Unified Queues+ module.
+#
+
+module UnifiedQueues
+      
+    ##
+    # More queues single interface.
+    #
+    
+    class Multi
+        
+        ##
+        # Contains assignment of classnames to drivers.
+        # @return [Hash] 
+        #
+          
+        DRIVERS = Hash[
+            :"UnifiedQueues::Single" => "unified-queues.rb",
+            :"EMJack::Connection" => "em-jack.rb"
+        ]
+
+        ##
+        # Contains driver for specific class instance.
+        # @return [UnifiedQueues::Multi::Driver] driver instance
+        #
+
+        attr_accessor :driver
+        @driver
+        
+        ##
+        # Constructor.
+        #
+        # @param [Class|UnifiedQueues::Multi::Driver] cls  required class object or driver instance
+        # @param [Array] *args  array of arguments for the queue constructor
+        # @param [Proc] &block  block for the queue constructor
+        #
+        
+        def initialize(cls, *args, &block)
+            if cls.kind_of? UnifiedQueues::Multi::Driver
+                @driver = cls
+            else
+                self.assign_driver(cls, args, block)
+            end
+        end
+        
+        ##
+        # Assigns driver to interface according to given class name.
+        #
+        # @param [Class] cls  required class
+        # @param [Array] args  array of arguments for the queue constructor
+        # @param [Proc] block  block for the queue constructor
+        # @return [UnifiedQueues::Multi::Driver] new driver instance
+        # 
+        
+        def assign_driver(cls, args, block)
+            _cls = cls
+            if not _cls.kind_of? Class
+                _cls = cls.class
+            end
+
+            driver = nil
+            name = nil
+            
+            self.class::DRIVERS.each_pair do |_name, _driver|
+                begin
+                    _module = Module::get_module(_name.to_s)
+                rescue NameError
+                    next
+                end
+                
+                if _cls <= _module
+                    driver = _driver
+                    name = _name
+                    break
+                end
+            end
+            
+            ###
+            
+            require "unified-queues/multi/driver/" << driver
+            
+            path = name.to_s.split("::")
+            classname = path.shift << 'Driver::' << path.join('::')
+            _module = Module::get_module("UnifiedQueues::Multi::Driver::" << classname)
+            
+            args = [cls] + args
+            @driver = _module::new(*args, &block)
+            return @driver
+        end
+        
+        ##
+        # Pushes value to the currently used queue.
+        #
+        # @param [Object] value
+        # @param [Object] key key for priority purposes
+        #
+        
+        def push(value, key = value, &block)
+            @driver.push(value, key, &block)
+        end
+        
+        ##
+        # Pops value from the queue. In contrast to default Queue library,
+        # blocks or returns +nil+ if empty.
+        # 
+        # @param [Boolean|Integer] blocking  +true+ or timeout if it should block, +false+ otherwise
+        # @return [Object|nil] 
+        #
+        
+        def pop(blocking = false, &block)
+            @driver.pop(blocking, &block)
+        end
+        
+        ##
+        # Sets queue with given name as used. So marks it as target 
+        # for {#push}.
+        #
+        # @param [Object] name name of the required queue 
+        #
+        
+        def use(name, &block)
+            @driver.use(name, &block)
+        end
+        
+        ##
+        # Subscribes to the queue. So marks it as target for {#pop}.
+        # Note, than only single queue usally can be subscribed at 
+        # one time.
+        #
+        # @param [Object] name  name of the required queue
+        #
+        
+        def subscribe(name, &block)
+            @driver.subscribe(name, &block)
+        end
+        
+        ##
+        # Unsubscribes from the queue.
+        # @param [Object] name  name of the required queue
+        #
+        
+        def unsubscribe(name, &block)
+            @driver.unsubscribe(name, &block)
+        end
+        
+        ##
+        # Currently used queue.
+        # @return [Queue]
+        #
+         
+        def used(&block)
+            @driver.used(&block)
+        end
+        
+        ##
+        # Currently subscribed queue.
+        # @return [Queue]
+        #
+            
+        def subscribed(&block)
+            @driver.subscribed(&block)
+        end
+            
+        ##
+        # Lists names of all available queues.
+        # @return [Array]
+        #
+        
+        def list(&block)
+            @driver.list(&block)
+        end
+        
+        ##
+        # Lists all used queues.
+        # @return [Array]
+        #
+        
+        def list_used(&block)
+            @driver.list_used(&block)
+        end
+    
+        ##
+        # Lists all subscribed queues.
+        # @return [Array]
+        #
+            
+        def list_subscribed(&block)
+            @driver.list_subscribed(&block)
+        end
+        
+        ##
+        # Closes the session.
+        #
+        
+        def close(&block)
+            @driver.close(&block)  
+        end
+        
+        alias :close! :close
+        
+    end
+end