priority_queue_cxx 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c2b5bbef541a1b74a11e959cda5b1b11020bda89
+  data.tar.gz: 15d62c6289e5d07cacafba804497305b6719c532
+SHA512:
+  metadata.gz: 7f14a5601f02ab38049968a222dd01d9403755984f0b91f6365b881cfe5af229173edf16290aa7568e15a87fd343205d965c9f8f2782cf096aed070cbd3ad934
+  data.tar.gz: 264b327c4dbc023d21a06868eebe55b76812d6f48b3a9797dd456aeb206766c936fd00ea1d1ae97ac3e58ae70a04a0b891b866ac14da513ae152f52b1ba3015f

data/README.md

@@ -0,0 +1,294 @@
+# PriorityQueueCxx
+
+[![Gem Version](https://badge.fury.io/rb/fast_containers.png)](http://badge.fury.io/rb/fast_containers)
+
+FastContainers provides a fast implementatin of priority queues for ruby. Speed is achieved by exposing  the c++ standard implementation through a light ruby wrapper. As a bigger project, the library may grow  a number of containers that are not in the standard ruby library and are presently only available as pure ruby libraries, but presently the library includes a single class named PriorityQueue. More containers will be added as necessity arises. Contributors and feature requests are most welcome.
+
+The library exposes a module named 'FastContainers' (to be required using ```require 'fc'```) which provides the PriorityQueue class.
+
+## Installation
+
+```ruby
+gem install 'priority_queue_cxx'
+```
+
+## Usage Example
+
+```ruby
+
+require 'fc'
+q = FastContainers::PriorityQueue.new(:max)
+q.push("largest", 10)
+q.push("smallest", 5)
+q.top      # =>  "largest"
+q.top_key  # => 10
+q.pop
+```
+
+## How fast is it?
+
+As far as I know, only one other library (the PriorityQueue gem) provides priority queues implemented as a C extension. This implies that the fc::PriorityQueue is a *lot* faster than most current alternatives and, as shown below, it compares favorably with the mentioned C extension as well.
+
+To get an idea about how fast it is, below we provide a comparison of the time needed to push and pop a large number of elements into a priority queue. Each experiment compares FastContainers with others priority queues implementations. Since timings varies greatly among different implementations, the number of push/pop performed is chosen so to make the experiments to run for (at most) few minutes.
+
+The following table summarizes the outputs, detailed results can be found in the next few sections. All libraries have been installed through the 'gem' command and executed using ruby v. 2.1.0.
+
+| library | avg μs per push | avg μs per pop | avg μs per op |
+|:--------|---------:|---------:|---------:|
+| *priority_queue_cxx*   | *0.456*   |  *1.138*  | *0.797* |
+| PriorityQueue     | 2.09    | 5.186   | 3.638 |
+| em-priority-queue | 3.56    | 8.32    | 5.94  |
+| pqueue            | 669.0   | 0.1     | 334.55|
+| algorithms        | 2584.6  |   29.6  |1307.1 |
+| priority_queue    | 1.4     |19134.6  |9568.0 |
+
+where: results are sorted according to "avg μs per op" (higher is better); μs stands for micro seconds; op stands for any operation (push or pop); the figures for priority_queue_cxx has been calculated with the results of experiments with PriorityQueue (the experiment with the highest number of operations).
+
+
+### Comparison with [algorithms (0.6.1)](http://rubygems.org/gems/algorithms) (50,000 push/pop)
+
+```ruby
+
+require 'fc'
+require 'algorithms'
+require 'benchmark'
+
+N = 50_000
+algo_pq = Containers::PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('algo:push') { N.times { |n| algo_pq.push(n.to_s, rand) } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('algo:pop')  { N.times { algo_pq.pop } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end
+```
+
+Output (reformatted):
+
+|         |      user|    system|     total|       real |
+|:--------|---------:|---------:|---------:|-----------:|
+|algorithms:push|122.200|  7.030|129.230|(129.173)|
+|*fc:push*  |  *0.020*|  *0.000*|  *0.020*|*(  0.020)*|
+|algorithms:pop |  1.460|  0.020|  1.480|(  1.476)|
+|*fc:pop*   |  *0.030*|  *0.000*|  *0.030*|*(  0.030)*|
+
+Summary: FastContainers::PriorityQueues (fc) are *6461.5 times faster* on pushes and *49.3 times faster* on pops.
+
+
+### Comparison with [priority_queue (0.2.0)](http://rubygems.org/gems/priority_queue) (50,000 push/pop)
+
+```ruby
+require 'fc'
+require 'priority_queue'
+require 'benchmark'
+
+N = 50_000
+pq_pq = PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq[rand] << n.to_s } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.shift } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end
+```
+
+Output (reformatted):
+
+|         |      user|    system|     total|       real |
+|:--------|---------:|---------:|---------:|-----------:|
+|priority_queue:push  | 0.060    | 0.010    | 0.070    |(  0.062593)|
+|*fc:push*  | *0.020*    | *0.000*    | *0.020*    |*(  0.018866)*|
+|priority_queue:pop   | 948.440  | 8.290    | 956.730  |(956.676601)|
+|*fc:pop*   | 0.040    | 0.000    | 0.040    |*(  0.032753)*|
+
+Summary: FastContainers::PriorityQueues (fc) are *3.5 times faster* on pushes and *23918.25 times faster* on pops.
+
+### Comparison with [em-priority-queue (1.1.2)](http://rubygems.org/gems/em-priority-queue) (500,000 push/pop)
+
+```ruby
+require 'fc'
+require 'em-priority-queue'
+require 'benchmark'
+
+N = 500_000
+em_pq = EM::PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('em:push') { N.times { |n| em_pq.push(n.to_s, rand) } }
+  bm.report('fc:push') { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('em:pop')  { N.times { em_pq.pop {} } }
+  bm.report('fc:pop')  { N.times { fc_pq.pop } }
+end
+```
+
+Output (reformatted):
+
+|         |      user|    system|     total|       real |
+|:--------|---------:|---------:|---------:|-----------:|
+|em-priority-queue:push  |1.650  |0.130  | 1.780 | (  1.895794) |
+|*fc:push*  |*0.190*  |*0.020*  | *0.210* | *(  0.224068)* |
+|em-priority-queue:pop   |3.980  |0.180  | 4.160 | (  4.360084) |
+|*fc:pop*   |*0.380*  |*0.000*  | *0.380* | *(  0.381250)* |
+
+Summary: FastContainers::PriorityQueue (fc) are *8.5 times faster* on pushes and *10.9 times faster* on pops.
+
+### Comparison with [pqueue (2.0.2)](http://rubygems.org/gems/pqueue) (100,000 push/pop)
+
+
+```ruby
+require 'fc'
+require 'pqueue'
+require 'benchmark'
+
+N = 100_000
+pq_pq = PQueue.new { |x,y| x[1] <=> y[1] }
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq.push([n,rand]) } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.pop } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end
+```
+
+Output (reformatted):
+
+|         |      user|    system|     total|       real |
+|:--------|---------:|---------:|---------:|-----------:|
+|pqueue:push  | 25.240|41.660 | 66.900| ( 66.871391)|
+|*fc:push*  | *0.040* | *0.000* |  *0.040*| *(  0.035270)*|
+|pqueue:pop   | 0.010 | 0.000 |  0.010| (  0.018718)|
+|*fc:pop*   | *0.070* | *0.000* | *0.070*| *(  0.061138)*|
+
+Summary: FastContainers::PriorityQueue (fc) are *1672.5 times faster* on pushes and *7 times slower* on pops.
+
+### Comparison with [PriorityQueue (0.1.2)](https://rubygems.org/gems/PriorityQueue) (5,000,000 push/pop)
+
+
+```ruby
+require 'fc'
+require 'priority_queue'
+require 'benchmark'
+
+N = 5_000_000
+pq_pq = CPriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq.push(n.to_s,rand) } }
+  bm.report('fc:push') { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.delete_min } }
+  bm.report('fc:pop')  { N.times { fc_pq.pop } }
+end
+```
+
+Output (reformatted):
+
+|         |      user|    system|     total|       real |
+|:--------|---------:|---------:|---------:|-----------:|
+|PriorityQueue:push  | 10.020|  0.430| 10.45|( 10.665449)|
+|*fc:push*  |  *2.110*|  *0.170*|  *2.28*|*(  2.452529)*|
+|PriorityQueue:pop   | 25.860|  0.070| 25.93|( 25.949438)|
+|*fc:pop*   |  *5.690*|  *0.000*|  *5.69*|*(  5.688552)*|
+
+Summary: FastContainers::PriorityQueue (fc) are *4.58 times faster* on pushes and *4.54 times faster* on pops.
+
+## Which is the best priority queue implementation for ruby?
+
+As it usually happens, the answer is: it depends. The evidence reported above shows that if you are only interested in the speed of push and pop methods, then priority_queue_cxx is a very good candidate. Few other important factors may make other libraries be better suited for your needs. The most glaring one is that priority_queue_cxx implementation (i.e., ```FastContainers::PriorityQueue```) does not support changes of priorities<sup><a id="backref1" href="#notes">1</a></sup>. If your problem requires this feature, the best candidate appears to be  [PriorityQueue (0.1.2)](https://rubygems.org/gems/PriorityQueue) library. Also, in making your choice, you may want to consider the fact that not all the presented libraries appear to be actively maintained (although, no one gave any problem at the time of the writing).
+
+## API
+
+Here it follows a transcription of the RDoc documentation for the library. I'm adding it here because I've having difficulties in instructing the 'gem' executable to generate the correct files on installation (everything works fine using rdoc from the command line though). Any suggestion about how to solve this problem is *very* welcome.
+
+### FastContainers::PriorityQueue
+
+#### Public Class Methods
+
+##### new(queue_kind)
+
+Create a new priority queue and returns it. queue_kind specifies whether to build a :min or a :max queue.
+
+Example:
+
+```ruby 
+  pq = FastContainers::PriorityQueue.new(:min)
+```
+
+#### Public Instance Methods
+
+##### each { |obj,priority| ... } → self
+
+Iterates through the priority queue yielding each element to the given block. The order of the yielded elements is not defined. Returns self.
+
+Example:
+
+```ruby
+
+pq.each do |obj,priority|
+  puts "Obj #{obj} has priority #{priority}"
+end
+```
+
+##### next
+
+Alias for: [top](#label-top+%E2%86%92+obj)
+
+##### next_key
+
+Alias for: [top_key](#label-top_key+%E2%86%92+float)
+
+#### second_best_key → float
+
+Returns the priority of the second best element in the priority queue.
+
+##### empty?
+
+Returns true if the queue is empty
+
+##### pop → self
+
+Pops the top most element from the priority queue. Returns self.
+
+##### pop_each { |obj, priority| ... } → self
+
+Iterates through the priority queue popping the top element and yielding it to the block. The order of yielded elements is guaranteed to be the priority order. Returns self.
+
+Example:
+
+```ruby
+ary = [100, 1, 90, 55, 6]
+ary.each { |x| pq.push(x.to_s, x)}
+ary.pop_each {|obj, priority| print(priority, ',') } # => 1,6,55,90,100,
+```
+
+##### push(obj,priority) → self
+
+Push the obj/priority pair into the queue and returns self.
+
+##### size  → num
+
+Returns the size of the priority queue
+
+##### top → obj
+
+Returns the object at the top of the priority queue.
+
+##### top_key → float
+
+Returns the priority of the object at the top of the priority queue.
+
+#### Included Modules
+
+The class Includes Enumerable, so that standard enumeration based methods (e.g., map, all?, any?, ...) can all be used with this container. Notice that Enumerable methods are based on #each, implying that the order used to iterate through the container is undefined.
+
+## Notes
+
+<sup id="ref1">1</sup> It is worth mentioning that, due to how priority queue are implemented by the C++ standard library, this implementation can't efficiently support priority changes. In any case, to support this feature would require important changes in the current API.<a href="#which-is-the-best-priority-queue-implementation-for-ruby" title="back reference">&#8617;</a>
+

data/ext/fast_containers/FastContainers.cpp

@@ -0,0 +1,272 @@
+// Copyright (c) 2014 Roberto Esposito
+//
+// 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.
+#include "ruby.h"
+#include "fc_pq.h"
+
+// Defining a space for information and references about the module to be stored internally
+static VALUE FastContainers = Qnil;
+static VALUE PriorityQueue = Qnil;
+
+// --------------------------------------------------------------------------------
+// UTILITIES 
+// --------------------------------------------------------------------------------
+
+static fc_pq::PQueue pq_from_self(VALUE self) {
+  fc_pq::PQueue queue;
+  Data_Get_Struct(self, struct fc_pq::_PQueue, queue);
+  
+  return queue;
+}
+
+static void pq_mark(void *ptr) {
+  if(ptr==NULL)
+    return;
+  
+  fc_pq::PQueueIterator it = fc_pq::iterator((fc_pq::PQueue)ptr);
+  while( !fc_pq::iterator_end(it) ) {
+    rb_gc_mark( (VALUE) fc_pq::iterator_get_value(it) );
+    it = fc_pq::iterator_next(it);
+  }
+  fc_pq::iterator_dispose(it);
+}
+
+// --------------------------------------------------------------------------------
+// METHODS 
+// --------------------------------------------------------------------------------
+
+/*
+ * call-seq:
+ *    PriorityQueue.new(queue_kind) 
+ *
+ * Create a new priority queue and returns it.
+ * +queue_kind+ specifies whether to build a :min or a :max queue.
+ */
+static VALUE pq_new(VALUE klass, VALUE queue_kind) {
+  if( TYPE(queue_kind) != T_SYMBOL ) {
+    rb_raise(rb_eTypeError, "queue_kind parameter must be a symbol");
+  }
+  
+  fc_pq::PQueueKind kind;
+  
+  if( rb_intern("max") == rb_to_id(queue_kind) )
+    kind = fc_pq::MAX_QUEUE;
+  else if( rb_intern("min") == rb_to_id(queue_kind) )
+    kind = fc_pq::MIN_QUEUE;
+  else rb_raise(rb_eTypeError, "queue_kind parameter must be either :max or :min");
+    
+  fc_pq::PQueue queue = fc_pq::create(kind);
+  VALUE data = Data_Wrap_Struct(klass, pq_mark, fc_pq::destroy, queue);
+  rb_obj_call_init(data, 0, NULL);
+  return data;
+}
+
+/*
+ * call-seq:
+ *    size -> num
+ *
+ * Returns the size of the priority queue
+ */
+
+static VALUE pq_size(VALUE self) {
+   return INT2NUM(fc_pq::size(pq_from_self(self)));
+}
+
+/*
+ * call-seq:
+ *    push(obj,priority) -> self
+ *
+ * Push the +obj+/+priority+ pair into the queue and returns self.
+ */
+static VALUE pq_push(VALUE self, VALUE obj, VALUE priority) {
+  fc_pq::push(pq_from_self(self), (void*)obj, NUM2DBL(priority));
+  return self;
+}
+
+/*
+ * call-seq:
+ *    top -> obj
+ *
+ * Returns the object at the top of the priority queue.
+ */
+static VALUE pq_top(VALUE self) {
+  fc_pq::PQueue queue = pq_from_self(self);
+  if( fc_pq::empty(queue) ) {
+    return Qnil;
+  }
+  
+  return (VALUE) fc_pq::top( queue );
+}
+
+/*
+ * call-seq:
+ *   top_key -> float
+ *
+ * Returns the priority of the object at the top of the priority queue.
+ */
+static VALUE pq_top_key(VALUE self) {
+  fc_pq::PQueue queue = pq_from_self(self);
+  if(fc_pq::empty(queue))
+    return Qnil;
+  
+  double priority = fc_pq::top_key(queue);
+  return DBL2NUM(priority);
+}
+
+/*
+ * call-seq:
+ *   second_best_key -> float
+ *
+ * Returns the priority of the second best element in the priority queue.
+ */
+static VALUE pq_second_best_key(VALUE self) {
+   fc_pq::PQueue queue = pq_from_self(self);
+   if(fc_pq::size(queue) < 2)
+      return Qnil;
+   
+   double priority = fc_pq::second_best_key(queue);
+   return DBL2NUM(priority);
+}
+
+/*
+ * call-seq:
+ *     pop -> obj
+ *
+ * Pops the top most element from the priority queue.
+ * Returns the top object (before the pop).
+ */
+static VALUE pq_pop(VALUE self) {
+  fc_pq::PQueue queue = pq_from_self(self);
+  
+  if( fc_pq::empty(queue) )
+    rb_raise(rb_eRuntimeError, "Pop called on an empty queue");
+  
+  VALUE top = (VALUE) fc_pq::top( queue );
+  fc_pq::pop(queue);
+  
+  return top;
+}
+
+/*
+ * call-seq:
+ *     empty?
+ *
+ * Returns true if the queue is empty
+ */
+
+static VALUE pq_empty(VALUE self) {
+  if( fc_pq::empty(pq_from_self(self)) )
+    return Qtrue;
+  else
+    return Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *    each { |obj,priority| ... } -> self
+ *
+ * Iterates through the priority queue yielding each element to the given block.
+ * The order of the yielded elements is not defined. The given block *must not* change
+ * the queue elements order. In case it does the iteration will be aborted and the
+ * method will return nil.
+ *
+ * Returns self.
+ */
+
+static VALUE pq_each(VALUE self) {
+  fc_pq::PQueue queue = pq_from_self(self);
+  fc_pq::PQueueIterator iterator;
+    
+  try {
+    iterator = fc_pq::iterator(queue);
+    while( !fc_pq::iterator_end(iterator) ) {
+      VALUE value = (VALUE) fc_pq::iterator_get_value(iterator);
+      VALUE num = DBL2NUM(fc_pq::iterator_get_key(iterator));
+      rb_yield_values( 2,value, num );
+      fc_pq::iterator_next(iterator);
+    }
+    fc_pq::iterator_dispose(iterator);
+  } catch (fc_pq::PQueueException& exception) {
+    fc_pq::iterator_dispose(iterator);
+    rb_raise(rb_eRuntimeError, "%s", exception.what());
+    return Qnil;
+  }
+  
+  return self;
+}
+
+/*
+ * call-seq:
+ *    pop_each { |obj, priority| ... } -> self
+ *
+ * Iterates through the priority queue popping the top element and
+ * yielding it to the block. The order of yielded elements is guaranteed
+ * to be the priority order.
+ * Returns self.
+ */
+
+static VALUE pq_pop_each(VALUE self) {
+  fc_pq::PQueue queue= pq_from_self(self);
+  while( !fc_pq::empty(queue) ) {
+    VALUE value = (VALUE) fc_pq::top(queue);
+    double key = fc_pq::top_key(queue);
+    fc_pq::pop(queue);
+    rb_yield_values(2, value, DBL2NUM(key));
+  }
+  
+  return self;
+}
+
+// --------------------------------------------------------------------------------
+// INITIALIZATION 
+// --------------------------------------------------------------------------------
+
+/*
+ * Document-module: FastContainers
+ * Exposes C++ implementation of some containers not defined in the standard ruby libraries.
+ */
+
+/*
+ * Document-class: FastContainers::PriorityQueue
+ * Implements priority queues through a C++ heap (using the standard std::priority_queue class).
+ * Includes Enumerable, so that standard enumeration based methods (e.g., map, all?, any?, ...) 
+ * can all be used with this container. Notice that Enumerable methods are based on #each, implying
+ * that the order used to iterate through the container is undefined.
+ */
+extern "C" {
+  void Init_fast_containers() {
+    FastContainers = rb_define_module("FastContainers");
+    PriorityQueue = rb_define_class_under(FastContainers, "PriorityQueue", rb_cObject);
+    rb_global_variable(&FastContainers);
+    rb_global_variable(&PriorityQueue);
+    
+    rb_define_singleton_method(PriorityQueue, "new", RUBY_METHOD_FUNC(pq_new), 1);
+    rb_define_method(PriorityQueue, "size",     RUBY_METHOD_FUNC(pq_size), 0);
+    rb_define_method(PriorityQueue, "push",     RUBY_METHOD_FUNC(pq_push), 2);
+    rb_define_method(PriorityQueue, "top",      RUBY_METHOD_FUNC(pq_top), 0);
+    rb_define_method(PriorityQueue, "top_key",  RUBY_METHOD_FUNC(pq_top_key), 0);
+    rb_define_method(PriorityQueue, "second_best_key", RUBY_METHOD_FUNC(pq_second_best_key), 0);
+    rb_define_method(PriorityQueue, "pop",      RUBY_METHOD_FUNC(pq_pop), 0);
+    rb_define_method(PriorityQueue, "empty?",    RUBY_METHOD_FUNC(pq_empty), 0);
+    rb_define_method(PriorityQueue, "each",     RUBY_METHOD_FUNC(pq_each), 0);
+    rb_define_method(PriorityQueue, "pop_each", RUBY_METHOD_FUNC(pq_pop_each), 0);
+  }
+}

data/ext/fast_containers/extconf.rb

@@ -0,0 +1,5 @@
+require 'mkmf'
+
+extension_name = 'fast_containers'
+
+create_makefile(extension_name)

data/ext/fast_containers/fc_pq.cpp

@@ -0,0 +1,158 @@
+// Copyright (c) 2014 Roberto Esposito
+//
+// 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.
+#include "fc_pq.h"
+#include <iostream>
+
+namespace fc_pq {
+  
+  typedef std::pair<void*,double> PQElem;
+ 
+  class PairsComparator
+  {
+    bool reverse;
+  public:
+    PairsComparator(PQueueKind kind) {reverse=(kind==MIN_QUEUE);}
+    bool operator() (const PQElem& lhs, const PQElem& rhs) const
+    {
+      if (reverse) return (lhs.second>rhs.second);
+      else return (lhs.second<rhs.second);
+    }
+  };
+  
+  // --------------------------------------
+  // PQueue
+  // --------------------------------------
+    
+  typedef std::vector<PQElem> PQueueStorage;
+  typedef unsigned int PQueueStorageVersion;
+  
+  typedef struct _PQueue { 
+    PQueueStorage storage;
+    PairsComparator comparator;
+    PQueueStorageVersion version;
+    
+    _PQueue(PQueueKind kind) : comparator(kind), version(0) { }
+  }* PQueue;  
+
+  void destroy(PQueue q){
+    delete q;
+  }
+  
+  PQueue create(PQueueKind kind) {
+    return new _PQueue(kind);
+  }
+  
+  /* Getting the size of the container */
+  unsigned int size(PQueue q) {
+     return q->storage.size();
+  }
+  
+  
+  void push(PQueue q, void* value, double priority) {
+    q->version++;
+    q->storage.push_back(PQElem(value, priority));
+    push_heap(q->storage.begin(), q->storage.end(), q->comparator);
+  }
+  
+  void* top(PQueue q) {
+    return q->storage.at(0).first;
+  }
+  
+  double top_key(PQueue q) {
+    return q->storage.at(0).second;
+  }
+  
+  double second_best_key(PQueue q) {
+     if(q->storage.size()==2)
+        return q->storage.at(1).second;
+     
+     double key1 = q->storage.at(1).second;
+     double key2 = q->storage.at(2).second;
+     if( key1 > key2 ) {
+        return key1;
+     } else {
+        return key2;
+     }
+  }
+  
+  void pop(PQueue q) {
+    q->version++;
+    pop_heap(q->storage.begin(), q->storage.end(), q->comparator);
+    q->storage.pop_back();
+  }
+  
+  bool empty(PQueue q) {
+    return q->storage.empty();
+  }
+  
+  // --------------------------------------
+  // Iterator
+  // --------------------------------------
+  
+  
+  typedef struct _PQueueIterator {
+    PQueueStorage::const_iterator iterator;
+    PQueue pqueue;
+    PQueueStorage* storage;
+    PQueueStorageVersion version;
+    
+    _PQueueIterator(PQueue q) : iterator(q->storage.begin()), pqueue(q), storage(&q->storage), version(q->version) 
+      { }
+    
+    void checkVersion() throw(PQueueException) {
+      if(version != pqueue->version) {
+        throw PQueueException("FastContainers::PriorityQueue - a change in the priority queue invalidated the current iterator.");
+      }
+    }
+  } PQueueImplIterator;
+  #define QIT(it) ((PQueueImplIterator*)(it))
+  
+  /* Returns a new iterator object */
+  PQueueIterator iterator(PQueue q) {
+    PQueueImplIterator* it = new PQueueImplIterator(q);
+    return it;
+  }
+  
+  void iterator_dispose(PQueueIterator it) {
+    delete it;
+  }
+  
+  /* Returns the value of the current element */
+  void* iterator_get_value(PQueueIterator it) {
+    return it->iterator->first;
+  }
+  
+  /* Returns the priority of the current  element */
+  double iterator_get_key(PQueueIterator it) {
+    return it->iterator->second;
+  }
+  
+  /* Moves on to the next element */
+  PQueueIterator iterator_next(PQueueIterator it) throw(PQueueException) {
+    it->checkVersion();
+    it->iterator++;
+    return it;
+  }
+  
+  bool iterator_end(PQueueIterator it) {
+    return it->iterator == it->storage->end();
+  }
+}

data/ext/fast_containers/fc_pq.h

@@ -0,0 +1,85 @@
+// Copyright (c) 2014 Roberto Esposito
+//
+// 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.
+#ifndef FC_QUEUE_H_KTY6FH1S
+#define FC_QUEUE_H_KTY6FH1S
+
+#include <queue>
+
+namespace fc_pq {
+  class PQueueException : public std::runtime_error {
+  public:
+    PQueueException(const char* msg) : std::runtime_error(msg) {}
+  };
+  
+  typedef struct _PQueue* PQueue;
+  typedef struct _PQueueIterator* PQueueIterator;
+  typedef enum { MIN_QUEUE, MAX_QUEUE } PQueueKind;
+  
+  /* Constructor. It defaults to construct a max queue. If true is passed
+  it construct a min queue.*/  
+  PQueue create(PQueueKind kind);
+  
+  /* Destructor */
+  void destroy(PQueue q); 
+  
+  /* Getting the size of the container */
+  unsigned int size(PQueue q);
+  
+  /* Adding elements */
+  void push(PQueue q, void* value, double priority);
+  
+  /* Inspecting the queue top (for values) */
+  void* top(PQueue q);
+  
+  /* Inspecting the queue top (for priorities) */
+  double top_key(PQueue q);
+  
+ /* Returns the priority of the next best element */
+  double second_best_key(PQueue q);
+  
+  /* Removing the queue top */
+  void pop(PQueue q);
+  
+  /* Returns true if the queue is empty */
+  bool empty(PQueue q);
+  
+  /* Returns a new iterator object */
+  PQueueIterator iterator(PQueue q);
+  
+  /* Dispose the iterator */
+  void iterator_dispose(PQueueIterator it);
+  
+  /* Returns the value of the current element */
+  void* iterator_get_value(PQueueIterator it);
+  
+  /* Returns the priority of the current  element */
+  double iterator_get_key(PQueueIterator it);
+  
+  /* Moves on to the next element */
+  PQueueIterator iterator_next(PQueueIterator it) throw(PQueueException);
+  
+  /* Return true if the iterator is already out of the container */
+  bool iterator_end(PQueueIterator it);
+}
+
+#endif /* end of include guard: FC_QUEUE_H_KTY6FH1S */
+
+

data/lib/fc.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fast_containers'
+
+module FastContainers
+  VERSION = "0.3.2"
+  
+  class PriorityQueue
+    include Enumerable
+    
+    alias_method :next, :top
+    alias_method :next_key, :top_key
+  end
+end

data/test/performance/test_fc_vs_algorithms.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fc'
+require 'algorithms'
+require 'benchmark'
+
+# Performs 50.000 pushes and pops in priority queues using the fc and
+# algorithms implementations and reports the time spent.
+
+N = 50_000
+algo_pq = Containers::PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('algo:push') { N.times { |n| algo_pq.push(n.to_s, rand) } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('algo:pop')  { N.times { algo_pq.pop } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end

data/test/performance/test_fc_vs_cpriority_queue.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fc'
+require 'priority_queue'
+require 'benchmark'
+
+# Performs 5,000,000 pushes and pops in priority queues using the fc and
+# algorithms implementations and reports the time spent.
+
+N = 5_000_000
+pq_pq = CPriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq.push(n.to_s,rand) } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.delete_min } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end

data/test/performance/test_fc_vs_em_priority_queue.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fc'
+require 'em-priority-queue'
+require 'benchmark'
+
+# Performs 50.000 pushes and pops in priority queues using the fc and
+# algorithms implementations and reports the time spent.
+
+N = 500_000
+em_pq = EM::PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('em:push') { N.times { |n| em_pq.push(n.to_s, rand) } }
+  bm.report('fc:push') { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('em:pop')  { N.times { em_pq.pop {} } }
+  bm.report('fc:pop')  { N.times { fc_pq.pop } }
+end

data/test/performance/test_fc_vs_pqueue.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fc'
+require 'pqueue'
+require 'benchmark'
+
+# Performs 50.000 pushes and pops in priority queues using the fc and
+# algorithms implementations and reports the time spent.
+
+N = 100_000
+pq_pq = PQueue.new { |x,y| x[1] <=> y[1] }
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq.push([n,rand]) } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.pop } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end

data/test/performance/test_fc_vs_priority_queue.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require 'fc'
+require 'priority_queue'
+require 'benchmark'
+
+# Performs 50.000 pushes and pops in priority queues using the fc and
+# algorithms implementations and reports the time spent.
+
+N = 50_000
+pq_pq = PriorityQueue.new
+fc_pq = FastContainers::PriorityQueue.new(:min)
+
+Benchmark.bm do |bm|
+  bm.report('pq:push') { N.times { |n| pq_pq[rand] << n.to_s } }
+  bm.report('fc:push')   { N.times { |n| fc_pq.push(n.to_s, rand) } }
+  bm.report('pq:pop')  { N.times { pq_pq.shift } }
+  bm.report('fc:pop')    { N.times { fc_pq.pop } }
+end

data/test/test_fast_containers.rb

@@ -0,0 +1,245 @@
+# Copyright (c) 2014 Roberto Esposito
+#
+# 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.
+require "minitest/autorun"
+require "fc"
+
+class TestFastContainers < MiniTest::Unit::TestCase
+  def test_new_object_creation
+    assert !FastContainers::PriorityQueue.new(:max).nil?
+  end
+  
+  def test_new_handling_of_bad_parameter
+    assert_raises(TypeError) do
+      FastContainers::PriorityQueue.new(true)
+    end
+  end
+  
+  def test_push_returns_self
+    pq = FastContainers::PriorityQueue.new(:max)
+    assert_equal pq, pq.push("test",10)
+  end
+  
+  def test_top_on_a_single_element_queue_returns_that_element
+    pq = FastContainers::PriorityQueue.new(:max);
+    pq.push("test",10)
+    assert_equal "test", pq.top
+  end
+  
+  def test_next_on_a_single_element_queue_returns_that_element
+    pq = FastContainers::PriorityQueue.new(:max);
+    pq.push("test",10)
+    assert_equal "test", pq.next
+  end
+  
+  
+  def test_top_returns_the_maximal_element_in_a_max_queue
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal "30", pq.top
+  end
+  
+  def test_next_returns_the_maximal_element_in_a_max_queue
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal "30", pq.next
+  end
+  
+
+  def test_top_returns_the_minimal_element_in_a_min_queue
+    pq = FastContainers::PriorityQueue.new(:min) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal "10", pq.top
+  end
+  
+  def test_next_returns_the_minimal_element_in_a_min_queue
+    pq = FastContainers::PriorityQueue.new(:min) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal "10", pq.next
+  end
+
+  def test_top_key_returns_the_top_priority
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal 30, pq.top_key
+  end
+  
+  def test_next_key_returns_the_top_priority
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    assert_equal 30, pq.next_key
+  end
+  
+  
+  def test_pop_removes_an_element_from_the_top
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.push("30", 30)
+    pq.push("20", 20)
+    extracted = pq.pop
+    
+    assert_equal 20, pq.top_key
+    assert_equal "30", extracted
+  end
+  
+  def test_pop_raises_an_exception_if_the_queue_is_empty
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    pq.pop
+    assert_raises(RuntimeError) {
+      pq.pop
+    }
+  end
+  
+  def test_empty_returns_false_if_the_queue_is_not_empty
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    pq.push("10", 10)
+    assert !pq.empty?
+  end
+  
+  def test_empty_returns_true_if_the_queue_is_empty
+    pq = FastContainers::PriorityQueue.new(:max) # this is a max queue
+    assert pq.empty?
+  end
+  
+  def test_size_on_empty_queue
+    pq = FastContainers::PriorityQueue.new(:max)
+    assert_equal 0, pq.size
+  end
+  
+  def test_size_on_non_empty_queue
+    pq = FastContainers::PriorityQueue.new(:max)
+    pq.push("x",10);
+    pq.push("y",20);
+    pq.push("z",30);
+    assert_equal 3, pq.size
+  end
+  
+  def test_enumerable
+    pq = FastContainers::PriorityQueue.new(:max)
+    pq.push(1,10);
+    pq.push(2,20);
+    pq.push(3,30);
+    sum_o = 0
+    sum_p = 0
+    pq.map { |o,p| sum_o+=o; sum_p+=p }
+    assert_equal 6, sum_o 
+    assert_equal 60, sum_p
+  end
+  
+  def test_top_key_on_empty_queues
+    pq = FastContainers::PriorityQueue.new(:max)
+    assert_nil pq.top_key
+  end
+  
+  def test_top_on_empty_queues
+    pq = FastContainers::PriorityQueue.new(:max)
+    assert_nil pq.top
+  end
+  
+  def test_second_best_key
+    pq = FastContainers::PriorityQueue.new(:max)
+    pq.push("x", 100);
+    pq.push("y", 80);
+    pq.push("z", 40);
+    pq.push("w", 60);
+    pq.push("i", 90);
+    pq.push("j", 95);
+    
+    assert_equal pq.second_best_key, 95
+  end
+  
+  def test_second_best_key_on_empty_pq
+    pq = FastContainers::PriorityQueue.new(:max)
+    assert_nil pq.second_best_key
+  end
+  
+  def test_second_best_key_on_size_1_pq
+    pq = FastContainers::PriorityQueue.new(:max)
+    pq.push("x", 100)
+    assert_nil pq.second_best_key
+  end
+  
+  def test_second_best_key_on_size_2_pq
+    pq = FastContainers::PriorityQueue.new(:max)
+    pq.push("x", 100)
+    pq.push("x", 80)
+    
+    assert_equal 80, pq.second_best_key
+  end
+  
+  def test_each_will_iterate_over_all_elements
+    pq = FastContainers::PriorityQueue.new(:max);
+    pq.push("x", 100);
+    pq.push("y", 80);
+    pq.push("z", 40);
+    pq.push("w", 60);
+    pq.push("i", 90);
+    pq.push("j", 95);
+    
+    objects = Set.new
+    
+    result = pq.each do |obj, priority|
+      objects << obj
+    end
+    
+    assert_equal objects, Set.new(["x","y","z","w","i","j"])
+    assert_equal pq, result
+  end
+  
+  def test_each_will_abort_and_return_nil_if_queue_changes
+    pq = FastContainers::PriorityQueue.new(:max);
+    pq.push("x", 100);
+    pq.push("y", 80);
+    pq.push("z", 40);
+    pq.push("w", 60);
+    pq.push("i", 90);
+    pq.push("j", 95);
+    
+    objects = Set.new
+    
+    exception = assert_raises RuntimeError do
+      count = 0    
+      pq.each do |obj, priority|
+        if count==3
+          pq.push("no way!", 90)
+        end
+      
+        count+=1
+        objects << obj      
+      end
+    end
+    
+    assert_match /a change in the priority queue invalidated the current iterator/, exception.message
+    assert_equal 4, objects.size
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: priority_queue_cxx
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- Roberto Esposito
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A thin wrapper around C++ priority queues
+email:
+- boborbt@gmail.com
+executables: []
+extensions:
+- ext/fast_containers/extconf.rb
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- ext/fast_containers/FastContainers.cpp
+- ext/fast_containers/extconf.rb
+- ext/fast_containers/fc_pq.cpp
+- ext/fast_containers/fc_pq.h
+- lib/fc.rb
+- test/performance/test_fc_vs_algorithms.rb
+- test/performance/test_fc_vs_cpriority_queue.rb
+- test/performance/test_fc_vs_em_priority_queue.rb
+- test/performance/test_fc_vs_pqueue.rb
+- test/performance/test_fc_vs_priority_queue.rb
+- test/test_fast_containers.rb
+homepage: https://github.com/boborbt/fast_containers
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+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: Fast (c++ wrapper) priority queue implementation for ruby.
+test_files: []
+has_rdoc: