priority_queue_cxx17 0.3.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a841223729c1f0c7642e81085763cc03b257427e01c7955c8152a97b4995c08
+  data.tar.gz: 15778f008f8589dc011b2a4f8e7adbe1906016a404f89454f01385dc6184515e
+SHA512:
+  metadata.gz: dc9b7a0d2136e36d27551c1b3042188d38c39dff9851dbfa2cd1125c3e6272a6db04a97303960188ea8db9dcebd886e8eacf43415827ca999b533c199c3c0af5
+  data.tar.gz: bacdb6ab15a1853e01bad9755d4bc78a7b99c8452b3e83433b013c0aac50250a9b0d20b55aa67f5daf44170dc693de3612490e95bb94e553708f6e08dd75df9a

data/README.md

@@ -0,0 +1,295 @@
+# PriorityQueueCxx
+
+[![Gem Version](https://badge.fury.io/rb/priority_queue_cxx.png)](http://badge.fury.io/rb/priority_queue_cxx)
+[![priority_queue_cxx API Documentation](https://www.omniref.com/ruby/gems/priority_queue_cxx.png)](https://www.omniref.com/ruby/gems/priority_queue_cxx)
+
+
+*PriorityQueueCxx* provides a fast implementation 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 to provide a number of containers that are not in the standard ruby library and are presently only available as pure ruby libraries. Presently, however, 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 I 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 other 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 in the list 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'm 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);
+  }
+}