dijkstra_fast 1.4.2 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0806b283afa40238d914c51d06c587a4dc053d65431bb68c55b6a06a827bb245'
-  data.tar.gz: c070c8d2f5bfb38b3fe25469190ef460ca1581a3c670b1715cb3696b6e46373b
+  metadata.gz: 30660dd68011ab507e8372a955f1d90ece8747671e14fa93bddf94c56e1ef3f3
+  data.tar.gz: ff92f18155e77f8d027ae4a25d94110f43e1b6d819618314391ac54cd1e6cbe7
 SHA512:
-  metadata.gz: 04640eac7496a7fd98dae710d4582f27397b86f4782e9c6fec3eb4a4ef4d46aff809c33a7295dee419c56f09a276214937b09beb1a03220bcbcf3c65d977e2d6
-  data.tar.gz: ee26aad2a4a9ab681754e4b8682f8b465e94bc36797da88f3d2ef62de260f4e69e9f2c80dd6856962f3e80a88f3e31cc3e871d9ac9d5d0146a6cfb10906856c7
+  metadata.gz: 370902a6b3e98b591544ccd46db0cfb42b8aa5f839013110314cd3502edb55272baf69d6e50bddb890ed84e94127d642fbe127efd3906ebecb04ede6fb699fb8
+  data.tar.gz: d0f633f8875acad390fa3ecc4e0f4b55379a7a407160672f2a971a04944e4ac5019b144483bebe061b24c07a3d7ac13e0b4756c31b4f658da1261ff4c977b0a2

data/.yardopts

@@ -0,0 +1,7 @@
+--readme README.md
+--title 'Dijkstra (Fast!) Documentation'
+--charset utf-8
+--markup-provider=redcarpet
+--markup markdown
+--exclude lib/dijkstra_fast/native.rb
+'lib/**/*.rb' - '*.md'

data/README.md

@@ -16,13 +16,25 @@
 ## Description
 
 [Dijkstra](https://en.wikipedia.org/wiki/Dijkstra's_algorithm) is a commonly
-used algorithm for finding the shortest path through a graph or network.
+used algorithm for finding the shortest path/distance between two items in an
+interconnected collection of items (such as a graph or network).
 
 
 ## Features
 
 * Native implementation of Dijkstra's algorithm intended for use on large,
-sparse graphs for which an array of arrays is inefficient.
+typically sparse graphs.
+* Allows for calculating shortest distance without requiring all nodes/edges to
+be produced. (In many applications doing this can be more expensive than
+Dijkstra's algorithm itself - or even impractical.)
+* Can be used in one of three ways:
+  * __Method 1__: Use an instance of `DijkstraFast::Graph` by adding edges to
+  it.
+  * __Method 2__: Add `shortest_path` and `shortest_distance` methods to an
+  existing class by including the `DijkstraFast::ShortestPath` module.
+  * __Method 3__: Call `DijkstraFast::ShortestPath.shortest_path` or
+  `DijkstraFast::ShortestPath.shortest_distance` directly when the `source` and
+  `dest` objects know how to find "connected" items via some method.
 
 
 ## Installation
@@ -35,27 +47,109 @@ gem install dijkstra_fast
 
 * Ruby 3.0 or higher
 
+
 ## Usage
 
-**Dijkstra**
+### Method 1: Use `DijkstraFast::Graph`
 
 ```ruby
-require 'dijkstra_fast'
-
 graph = DijkstraFast::Graph.new
 graph.add("A", "B", distance: 5)
 graph.add("A", "C", distance: 8)
 graph.add("B", "C", distance: 2)
-best_path = graph.shortest_path("A", "C")
-best_path.path
+distance, path = graph.shortest_path("A", "C")
+path
 
 => ["A", "B", "C"]
 
-best_path.distance
+distance
 
 => 7
 ```
 
+### Method 2: Include `DijkstraFast::ShortestPath`
+
+```ruby
+class MyNetwork
+  include DijkstraFast::ShortestPath
+
+  def connections(source)
+    case source
+    when "A"
+      yield "B", 3
+      yield "C", 8
+    when "B"
+      yield "C" # Default distance 1
+    end
+  end
+end
+
+distance, path = MyNetwork.new.shortest_path("A", "C")
+path
+
+=> ["A", "B", "C"]
+
+distance
+
+=> 4
+```
+
+### Method 3: Call `DijkstraFast.shortest_path` or `DijkstraFast.shortest_distance`
+
+```ruby
+Node = Struct.new(:label) do
+  def connections
+    case label
+    when "A"
+      yield Node.new("B"), 5
+      yield Node.new("C"), 8
+    when "B"
+      yield Node.new("C"), 2
+    end
+  end
+end
+
+a = Node.new("A")
+b = Node.new("B")
+c = Node.new("C")
+
+distance, path = DijkstraFast.shortest_path(a, c)
+path.map(&:label)
+
+=> ["A", "B", "C"]
+
+distance
+
+=> 7
+```
+
+
+## Additional Notes
+
+* When using arbitrary Ruby objects as graph nodes, it is important to ensure
+that [Object#hash](https://ruby-doc.org/core-3.1.0/Object.html#method-i-hash)
+and [Object#eql?](https://ruby-doc.org/core-3.1.0/Object.html#method-i-eql-3F)
+are properly implemented so that two instances which are logically the same
+will be considered as the same node.  Under the hood, this gem creates a
+bi-directional mapping between nodes and an auto-incrementing integer id so
+that Ruby objects do not have to be passed into the internals of the native
+implementation; doing so would risk problems with garbage collection and is
+otherwise frowned upon when implementing native extensions.
+* All `shortest_path` and `shortest_distance` methods provide an optional
+`progress` named argument which (when set to anything truthy) will provide
+progress as the algorithm proceeds.  The default implementation uses the
+[progressbar](https://github.com/jfelchner/ruby-progressbar/wiki) gem, but this
+is not required.
+* The maximum number of items that can be handled by this implementation is
+determined by the size of `unsigned long` which is compiler dependent.  On many
+machines this can be 18,446,744,073,709,551,615 (2^64 – 1). A
+[RuntimeError](https://ruby-doc.org/core-3.1.0/RuntimeError.html) will be
+thrown if this is surpassed; if so, congratulations on being bad ass!
+* A priority queue is used within the native Dijkstra implemenation to maintain
+the next shortest path to consider within the algorithm's main loop. It is
+possible that switching to a [Fibonacci
+heap](https://en.wikipedia.org/wiki/Fibonacci_heap) might improve performance.
+
 
 ## License
 

data/Rakefile

@@ -1,16 +1,13 @@
-require "bundler/gem_tasks"
-require "rake/extensiontask"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rake/extensiontask'
+require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec
 
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
-  rdoc.main = "README.md"
-  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
-end
+YARD::Rake::YardocTask.new
 
 Rake::ExtensionTask.new('dijkstra_fast') do |ext|
   ext.lib_dir = 'lib/dijkstra_fast'

data/dijkstra_fast.gemspec

@@ -1,4 +1,4 @@
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dijkstra_fast/version'
 
@@ -10,13 +10,13 @@ Gem::Specification.new do |spec|
 
   spec.summary       = '(Native) implementation of Dijkstra algorithm for large, sparse graphs'
   spec.description   = <<~DESCRIPTION
-Native implementation of Dijkstra algorithm for finding the shortest path
-between two vertices in a large, sparse graphs. Underlying algorithm is
-implemented in C using a priority queue.  Edges are represented using linked
-lists rather than an adjacency matrix to reduce memory footprint when operating
-on very large graphs where the average number of edges between nodes is
-relatively small (e.g. < 1/10 the number of nodes). See
-https://en.wikipedia.org/wiki/Dijkstra's_algorithm for additional information.
+    Native implementation of Dijkstra algorithm for finding the shortest path
+    between two vertices in a large, sparse graphs. Underlying algorithm is
+    implemented in C using a priority queue.  Edges are represented using linked
+    lists rather than an adjacency matrix to reduce memory footprint when operating
+    on very large graphs where the average number of edges between nodes is
+    relatively small (e.g. < 1/10 the number of nodes). See
+    https://en.wikipedia.org/wiki/Dijkstra's_algorithm for additional information.
   DESCRIPTION
   spec.homepage      = 'https://github.com/david-mccullars/dijkstra_fast'
   spec.license       = 'MIT'
@@ -26,14 +26,20 @@ https://en.wikipedia.org/wiki/Dijkstra's_algorithm for additional information.
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.extensions    = ['ext/dijkstra_fast/extconf.rb']
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.0.0'
 
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'github-markup'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rake-compiler'
+  spec.add_development_dependency 'redcarpet'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-rake'
   spec.add_development_dependency 'rubocop-rspec'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'yard'
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true',
+  }
 end

data/ext/dijkstra_fast/dijkstra_fast.c

@@ -1,5 +1,5 @@
-#include <dijkstra_graph.h>
+#include <native.h>
 
 void Init_dijkstra_fast() {
-  Init_dijkstra_graph();
+  Init_native_shortest_path();
 }

data/ext/dijkstra_fast/errors.c

@@ -0,0 +1,12 @@
+#include <ruby.h>
+#include <errors.h>
+
+void raise_max_capacity_reached_error(const char *expandable) {
+  rb_raise(rb_eRuntimeError, "Maximum capacity reached for %s", expandable);
+}
+
+void raise_no_path_error() {
+  VALUE DijkstraFastModule = rb_const_get(rb_cObject, rb_intern("DijkstraFast"));
+  VALUE NoPathExistsError = rb_const_get(DijkstraFastModule, rb_intern("NoPathExistsError"));
+  rb_raise(NoPathExistsError, "No path exists from source to destination");
+}

data/ext/dijkstra_fast/errors.h

@@ -0,0 +1,7 @@
+#ifndef ERRORS_H
+#define ERRORS_H
+
+void raise_max_capacity_reached_error(const char *expandable);
+void raise_no_path_error();
+
+#endif

data/ext/dijkstra_fast/expand_capacity.h

@@ -0,0 +1,19 @@
+#ifndef EXPAND_CAPACITY_H
+#define EXPAND_CAPACITY_H
+
+#define expand_capacity(TYPE, ITEMS, CAPACITY, INITIAL_CAPACITY, DESC) {  \
+  unsigned long prev_capacity = CAPACITY;                                 \
+  TYPE *prev_items = ITEMS;                                               \
+                                                                          \
+  if (CAPACITY == UINT_MAX) raise_max_capacity_reached_error(DESC);       \
+  CAPACITY = prev_items == NULL ? INITIAL_CAPACITY : prev_capacity * 2;   \
+  if (CAPACITY <= prev_capacity) CAPACITY = UINT_MAX;                     \
+  ITEMS = calloc(CAPACITY, sizeof(TYPE));                                 \
+                                                                          \
+  if (prev_items != NULL) {                                               \
+    memcpy(ITEMS, prev_items, prev_capacity * sizeof(TYPE));              \
+    free(prev_items);                                                     \
+  }                                                                       \
+}
+
+#endif

data/ext/dijkstra_fast/native.c

@@ -0,0 +1,80 @@
+#include <ruby.h>
+#include <native.h>
+
+const size_t NATIVE_SIZE = sizeof(NativeStruct);
+const size_t ITEM_DATA_SIZE = sizeof(ItemDataStruct);
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+Native make_native() {
+  Native n = malloc(NATIVE_SIZE);
+  n->pq = make_priority_queue();
+  n->item_data_capacity = 0;
+  n->item_data = NULL;
+  n->u = NULL_ITEM;
+  n->completed = 0;
+  expand_item_data(n);
+  return n;
+}
+
+void free_native(void *data) {
+  Native n = (Native)data;
+  free_priority_queue(n->pq);
+  for (unsigned long i = 0; i < n->item_data_capacity; i++) {
+    if (n->item_data[i] != NULL) free_item_data(n->item_data[i]);
+  }
+  free(n->item_data);
+  free(n);
+}
+
+ItemData make_item_data() {
+  ItemData id = malloc(ITEM_DATA_SIZE);
+  id->previous = 0;
+  id->distance = PRIORITY_MAX;
+  id->visited = false;
+  return id;
+}
+
+void free_item_data(ItemData id) {
+  free(id);
+}
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+ItemData get_item_data(Native n, ITEM u, bool create_if_not_exists) {
+  if (create_if_not_exists) {
+    while (n->item_data_capacity <= u) expand_item_data(n);
+    if (n->item_data[u] == NULL) n->item_data[u] = make_item_data();
+  }
+  return n->item_data_capacity <= u ? NULL : n->item_data[u];
+}
+
+PRIORITY get_distance(Native n, ITEM u) {
+  ItemData uid = get_item_data(n, u, false);
+  return uid == NULL ? PRIORITY_MAX : uid->distance;
+}
+
+void update_distance(Native n, ITEM u, PRIORITY distance) {
+  ItemData uid = get_item_data(n, u, true);
+  uid->distance = distance;
+}
+
+bool has_visited(Native n, ITEM v) {
+  ItemData vid = get_item_data(n, v, false);
+  return vid == NULL ? false : vid->visited;
+}
+
+void mark_visited(Native n, ITEM v) {
+  ItemData vid = get_item_data(n, v, true);
+  vid->visited = true;
+}
+
+ITEM get_previous(Native n, ITEM v) {
+  ItemData vid = get_item_data(n, v, false);
+  return vid == NULL ? 0 : vid->previous;
+}
+
+void update_previous(Native n, ITEM v, ITEM u) {
+  ItemData vid = get_item_data(n, v, true);
+  vid->previous = u;
+}

data/ext/dijkstra_fast/native.h

@@ -0,0 +1,57 @@
+#ifndef NATIVE_H
+#define NATIVE_H
+
+#include <ruby.h>
+#include <errors.h>
+#include <expand_capacity.h>
+#include <priority_queue.h>
+
+struct ItemDataStruct;
+typedef struct ItemDataStruct* ItemData;
+
+typedef struct ItemDataStruct {
+  ITEM previous;
+  PRIORITY distance;
+  bool visited;
+} ItemDataStruct;
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+struct NativeStruct;
+typedef struct NativeStruct* Native;
+
+typedef struct NativeStruct {
+  PriorityQueue pq;
+  ItemData *item_data;
+  unsigned long item_data_capacity;
+  ITEM u;         // current working item
+  ITEM completed; // Number of items completed (for progress)
+} NativeStruct;
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+Native make_native();
+#define expand_item_data(n) expand_capacity(ItemData, n->item_data, n->item_data_capacity, 256, "Dijkstra items")
+void free_native(void *data);
+
+ItemData make_item_data();
+void free_item_data(ItemData id);
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+void Init_native_shortest_path();
+VALUE native_allocate(VALUE self);
+VALUE native_shortest_path(VALUE self, VALUE source, VALUE dest, VALUE progress);
+VALUE with_connection(VALUE v, VALUE context, int argc, VALUE extra[]);
+VALUE to_result(Native n, ITEM source, ITEM dest);
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+PRIORITY get_distance(Native n, ITEM u);
+void update_distance(Native n, ITEM u, PRIORITY distance);
+bool has_visited(Native n, ITEM v);
+void mark_visited(Native n, ITEM v);
+ITEM get_previous(Native n, ITEM v);
+void update_previous(Native n, ITEM v, ITEM u);
+
+#endif

data/ext/dijkstra_fast/native_shortest_path.c

@@ -0,0 +1,90 @@
+#include <ruby.h>
+#include <native.h>
+
+static const rb_data_type_t native_typed_data = {
+  "DijkstraFast/Native",
+  { 0, free_native, },
+  0, 0,
+  RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+void Init_native_shortest_path() {
+  VALUE DijkstraFastModule = rb_const_get(rb_cObject, rb_intern("DijkstraFast"));
+  VALUE NativeClass = rb_const_get(DijkstraFastModule, rb_intern("Native"));
+
+  rb_define_alloc_func(NativeClass, native_allocate);
+  rb_define_private_method(NativeClass, "_shortest_path", native_shortest_path, 3);
+}
+
+VALUE native_allocate(VALUE self) {
+  Native n = make_native();
+  return TypedData_Wrap_Struct(self, &native_typed_data, n);
+}
+
+VALUE native_shortest_path(VALUE self, VALUE source_obj, VALUE dest_obj, VALUE progress) {
+  VALUE method_args[1];
+  Native n;
+
+  TypedData_Get_Struct(self, NativeStruct, &native_typed_data, n);
+
+  ITEM source = NUM2INT(source_obj);
+  ITEM dest = NUM2INT(dest_obj);
+
+  priority_queue_push(n->pq, source, 0);
+  update_distance(n, source, 0);
+
+  while (!(priority_queue_is_empty(n->pq))) {
+    n->u = priority_queue_pop(n->pq);
+
+    if (n->u == dest) break; // We're done!!!
+    if (has_visited(n, n->u)) continue;
+
+    mark_visited(n, n->u);
+    method_args[0] = INT2NUM(n->u);
+    rb_block_call(self, rb_intern("connections"), 1, method_args, RUBY_METHOD_FUNC(with_connection), (VALUE)n);
+
+    if (progress != Qnil) {
+      n->completed++;
+      rb_funcall(progress, rb_intern("call"), 2, INT2NUM(n->completed), INT2NUM(n->completed + n->pq->size));
+    }
+  }
+
+  return to_result(n, source, dest);
+}
+
+VALUE with_connection(VALUE v_obj, VALUE context, int argc, VALUE extra[]) {
+  Native n = (Native)context;
+  ITEM u = n->u;
+  ITEM v = NUM2INT(v_obj);
+
+  if (has_visited(n, v)) return Qnil;
+
+  PRIORITY distance = argc > 1 ? NUM2INT(extra[1]) : 1;
+  PRIORITY alt_distance = priority_sum(get_distance(n, u), distance);
+
+  if (alt_distance >= get_distance(n, v)) return Qnil;
+
+  priority_queue_push(n->pq, v, alt_distance);
+  update_distance(n, v, alt_distance);
+  update_previous(n, v, u);
+
+  return Qnil;
+}
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+VALUE to_result(Native n, ITEM source, ITEM dest) {
+  PRIORITY distance = get_distance(n, dest);
+  VALUE path = rb_ary_new();
+
+  if (distance == PRIORITY_MAX) raise_no_path_error();
+
+  while (dest != NULL_ITEM) {
+    rb_ary_unshift(path, INT2NUM(dest));
+    dest = dest == source ? NULL_ITEM : get_previous(n, dest);
+  }
+
+  return rb_ary_new3(2, INT2NUM(distance), path);
+}

data/ext/dijkstra_fast/priority_queue.c

@@ -0,0 +1,109 @@
+#include <ruby.h>
+#include <priority_queue.h>
+
+const size_t PRIORITY_QUEUE_SIZE = sizeof(PriorityQueueStruct);
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+void swap_prioritized_items(PrioritizedItem *items, unsigned long i, unsigned long j) {
+  PrioritizedItem tmp = items[i];
+  items[i] = items[j];
+  items[j] = tmp;
+}
+
+void reprioritize_right(PrioritizedItem *items, unsigned long i, unsigned long size) {
+  unsigned long orig_i = i;
+  PRIORITY i_priority, j_priority_left, j_priority_right;
+  unsigned long j_left, j_right;
+  i_priority = items[i]->priority;
+
+  while (true) {
+    j_left = (i << 1) + 1;
+    j_right = j_left + 1;
+
+    j_priority_left = j_left < size ? items[j_left]->priority : PRIORITY_MAX;
+    j_priority_right = j_right < size ? items[j_right]->priority : PRIORITY_MAX;
+
+    if (j_priority_right < i_priority && j_priority_right < j_priority_left) {
+      swap_prioritized_items(items, i, j_right);
+      i = j_right;
+
+    } else if (j_priority_left < i_priority) {
+      swap_prioritized_items(items, i, j_left);
+      i = j_left;
+
+    } else {
+      return;
+    } 
+  }
+}
+
+void reprioritize_left(PrioritizedItem *items, unsigned long i) {
+  PRIORITY i_priority, j_priority;
+  unsigned long j;
+  i_priority = items[i]->priority;
+
+  while (i > 0) {
+    j = (i - 1) >> 1;
+    j_priority = items[j]->priority;
+
+    if (j_priority > i_priority) {
+      swap_prioritized_items(items, i, j);
+      i = j;
+
+    } else {
+      return;
+    }
+  }
+}
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+PriorityQueue make_priority_queue() {
+  PriorityQueue pq = malloc(PRIORITY_QUEUE_SIZE);
+  pq->size = 0;
+  pq->capacity = 0;
+  pq->items = NULL;
+  expand_priority_queue(pq);
+  return pq;
+}
+
+void free_priority_queue(PriorityQueue pq) {
+  for (unsigned long i = 0; i < pq->size; i++) free(pq->items[i]);
+  free(pq->items);
+  free(pq);
+}
+
+bool priority_queue_is_empty(PriorityQueue pq) {
+  return pq->size == 0 ? Qtrue : Qfalse;
+}
+
+void priority_queue_push(PriorityQueue pq, ITEM object, PRIORITY priority) {
+  PrioritizedItem item = malloc(sizeof(PrioritizedItem));
+  item->item = object;
+  item->priority = priority;
+
+  if (pq->size == pq->capacity) expand_priority_queue(pq);
+  pq->items[pq->size] = item;
+  reprioritize_left(pq->items, pq->size);
+  pq->size++;
+}
+
+ITEM priority_queue_pop(PriorityQueue pq) {
+  if (pq->size == 0) return 0;
+
+  swap_prioritized_items(pq->items, 0, pq->size - 1);
+  pq->size--;
+  reprioritize_right(pq->items, 0, pq->size);
+
+  ITEM item = pq->items[pq->size]->item;
+  free(pq->items[pq->size]);
+
+  return item;
+}
+
+// Safely sum two priorities without overflow
+PRIORITY priority_sum(PRIORITY p1, PRIORITY p2) {
+  PRIORITY sum = p1 + p2;
+  return sum < p1 || sum < p2 ? PRIORITY_MAX : sum;
+}

data/ext/dijkstra_fast/priority_queue.h

@@ -0,0 +1,42 @@
+#ifndef PRIORITY_QUEUE_H
+#define PRIORITY_QUEUE_H
+
+#include <ruby.h>
+#include <errors.h>
+#include <expand_capacity.h>
+
+typedef unsigned long ITEM;
+typedef unsigned int PRIORITY;
+static const PRIORITY PRIORITY_MAX = UINT_MAX;
+static const ITEM NULL_ITEM = 0;
+
+struct PrioritizedItemStruct;
+typedef struct PrioritizedItemStruct* PrioritizedItem;
+
+typedef struct PrioritizedItemStruct {
+  ITEM item;
+  PRIORITY priority;
+} PrioritizedItemStruct;
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+struct PriorityQueueStruct;
+typedef struct PriorityQueueStruct* PriorityQueue;
+
+typedef struct PriorityQueueStruct {
+  PrioritizedItem *items;
+  unsigned long capacity;
+  unsigned long size;
+} PriorityQueueStruct;
+
+//////////////////////////////////////////////////////////////////////////////////////
+
+PriorityQueue make_priority_queue();
+#define expand_priority_queue(pq) expand_capacity(PrioritizedItem, pq->items, pq->capacity, 256, "Priority Queue")
+void free_priority_queue(PriorityQueue pq);
+bool priority_queue_is_empty(PriorityQueue pq);
+void priority_queue_push(PriorityQueue pq, ITEM object, PRIORITY priority);
+ITEM priority_queue_pop(PriorityQueue pq);
+PRIORITY priority_sum(PRIORITY p1, PRIORITY p2);
+
+#endif