d_heap 0.3.0 → 0.7.0

data/docs/profile.txt

@@ -0,0 +1,358 @@
+Profiling run at 2021-02-01 00:43:34 -0500
+ruby v2.7.2, DHeap v0.6.1
+
+~~~~~~ filling @dheap_bm_random_vals with 1.0M ~~~~~~
+########################################################################
+# Profile w/ N=10 (i=1000000)
+# (n.b. RubyProf & tracepoint can change relative performance.
+#       A sampling profiler can provide more accurate relative metrics.
+########################################################################
+
+Filling   ruby binary heap ---------------------------
+Profiling ruby binary heap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 5.194751
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 41.50      2.156     2.156     0.000     0.000  1000000   DHeap::Benchmarks::RbHeap#<<   /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:107
+ 36.37      2.137     1.889     0.000     0.247  1000000   DHeap::Benchmarks::RbHeap#pop  /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:121
+ 14.92      5.195     0.775     0.000     4.420        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+  2.46      0.128     0.128     0.000     0.000  1000000   Array#fetch
+  2.41      0.125     0.125     0.000     0.000  1000000   Array#pop
+  2.35      0.122     0.122     0.000     0.000  1000000   Array#first
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+Filling   quaternary DHeap ---------------------------
+Profiling quaternary DHeap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 1.103473
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 64.92      1.103     0.716     0.000     0.387        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+ 12.09      0.133     0.133     0.000     0.000  1000000   DHeap#<<
+ 11.82      0.130     0.130     0.000     0.000  1000000   DHeap#pop
+ 11.16      0.123     0.123     0.000     0.000  1000000   Array#fetch
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+########################################################################
+# Profile w/ N=100 (i=1000000)
+# (n.b. RubyProf & tracepoint can change relative performance.
+#       A sampling profiler can provide more accurate relative metrics.
+########################################################################
+
+Filling   ruby binary heap ---------------------------
+Profiling ruby binary heap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 7.422039
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 47.72      3.542     3.542     0.000     0.000  1000000   DHeap::Benchmarks::RbHeap#<<   /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:107
+ 36.82      2.984     2.733     0.000     0.251  1000000   DHeap::Benchmarks::RbHeap#pop  /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:121
+ 10.39      7.422     0.771     0.000     6.651        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+  1.71      0.127     0.127     0.000     0.000  1000000   Array#pop
+  1.69      0.125     0.125     0.000     0.000  1000000   Array#fetch
+  1.67      0.124     0.124     0.000     0.000  1000000   Array#first
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+Filling   quaternary DHeap ---------------------------
+Profiling quaternary DHeap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 1.163539
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 64.38      1.164     0.749     0.000     0.414        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+ 12.52      0.146     0.146     0.000     0.000  1000000   DHeap#<<
+ 12.43      0.145     0.145     0.000     0.000  1000000   DHeap#pop
+ 10.67      0.124     0.124     0.000     0.000  1000000   Array#fetch
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+########################################################################
+# Profile w/ N=1000 (i=1000000)
+# (n.b. RubyProf & tracepoint can change relative performance.
+#       A sampling profiler can provide more accurate relative metrics.
+########################################################################
+
+Filling   ruby binary heap ---------------------------
+Profiling ruby binary heap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 9.693127
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 52.28      5.068     5.068     0.000     0.000  1000000   DHeap::Benchmarks::RbHeap#<<   /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:107
+ 35.52      3.702     3.443     0.000     0.259  1000000   DHeap::Benchmarks::RbHeap#pop  /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:121
+  8.18      9.693     0.793     0.000     8.900        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+  1.36      0.131     0.131     0.000     0.000  1000000   Array#pop
+  1.35      0.131     0.131     0.000     0.000  1000000   Array#fetch
+  1.32      0.128     0.128     0.000     0.000  1000000   Array#first
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+Filling   quaternary DHeap ---------------------------
+Profiling quaternary DHeap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 1.125575
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 64.22      1.126     0.723     0.000     0.403        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+ 13.16      0.148     0.148     0.000     0.000  1000000   DHeap#<<
+ 12.01      0.135     0.135     0.000     0.000  1000000   DHeap#pop
+ 10.62      0.119     0.119     0.000     0.000  1000000   Array#fetch
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+########################################################################
+# Profile w/ N=10000 (i=1000000)
+# (n.b. RubyProf & tracepoint can change relative performance.
+#       A sampling profiler can provide more accurate relative metrics.
+########################################################################
+
+Filling   ruby binary heap ---------------------------
+Profiling ruby binary heap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 13.737007
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 49.46      6.794     6.794     0.000     0.000  1000000   DHeap::Benchmarks::RbHeap#<<   /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:107
+ 41.97      6.017     5.765     0.000     0.251  1000000   DHeap::Benchmarks::RbHeap#pop  /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:121
+  5.80     13.737     0.796     0.000    12.941        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+Filling   quaternary DHeap ---------------------------
+Profiling quaternary DHeap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 1.179968
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 62.48      1.180     0.737     0.000     0.443        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+ 13.86      0.164     0.164     0.000     0.000  1000000   DHeap#<<
+ 13.46      0.159     0.159     0.000     0.000  1000000   DHeap#pop
+ 10.20      0.120     0.120     0.000     0.000  1000000   Array#fetch
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+########################################################################
+# Profile w/ N=100000 (i=1000000)
+# (n.b. RubyProf & tracepoint can change relative performance.
+#       A sampling profiler can provide more accurate relative metrics.
+########################################################################
+
+Filling   ruby binary heap ---------------------------
+Profiling ruby binary heap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 16.425915
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 50.99      8.623     8.376     0.000     0.247  1000000   DHeap::Benchmarks::RbHeap#pop  /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:121
+ 41.82      6.869     6.869     0.000     0.000  1000000   DHeap::Benchmarks::RbHeap#<<   /home/nick/src/d_heap/lib/d_heap/benchmarks/implementations.rb:107
+  4.89     16.426     0.803     0.000    15.623        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+
+Filling   quaternary DHeap ---------------------------
+Profiling quaternary DHeap ---------------------------
+Measure Mode: wall_time
+Thread ID: 1400
+Fiber ID: 1380
+Total: 1.205573
+Sort by: self_time
+
+ %self      total      self      wait     child     calls  name                           location
+ 59.14      1.206     0.713     0.000     0.493        1   DHeap::Benchmarks::Scenarios#repeated_push_pop /home/nick/src/d_heap/lib/d_heap/benchmarks.rb:81
+ 16.93      0.204     0.204     0.000     0.000  1000000   DHeap#pop
+ 13.88      0.167     0.167     0.000     0.000  1000000   DHeap#<<
+ 10.05      0.121     0.121     0.000     0.000  1000000   Array#fetch
+
+* recursively called methods
+
+Columns are:
+
+  %self     - The percentage of time spent in this method, derived from self_time/total_time.
+  total     - The time spent in this method and its children.
+  self      - The time spent in this method.
+  wait      - The amount of time this method waited for other threads.
+  child     - The time spent in this method's children.
+  calls     - The number of times this method was called.
+  name      - The name of the method.
+  location  - The location of the method.
+
+The interpretation of method names is:
+
+  * MyObject#test - An instance method "test" of the class "MyObject"
+  * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+

data/ext/d_heap/.rubocop.yml

@@ -0,0 +1,7 @@
+---
+inherit_from:
+  - "../../.rubocop.yml"
+
+Style/GlobalVars:
+  AllowedVariables:
+    - "$defs"

data/ext/d_heap/d_heap.c

@@ -1,99 +1,286 @@
-#include "d_heap.h"
-
-ID id_cmp; // <=>
-ID id_ivar_values;
-ID id_ivar_scores;
-ID id_ivar_d;
-
-#define Get_DHeap(hobj, hstruct) ((hstruct) = get_dheap_struct(hobj))
-
-#define DHEAP_IDX_LAST(heap) (DHEAP_SIZE(heap) - 1)
-#define DHEAP_IDX_PARENT(heap, idx) ((idx - 1) / heap->d)
-#define DHEAP_IDX_CHILD0(heap, idx) ((idx * heap->d) + 1)
-
-#define DHEAP_SIZE(heap) (RARRAY_LEN((heap)->scores))
-#define DHEAP_VALUE(heap, idx) RARRAY_AREF((heap)->values, idx)
-#define DHEAP_SCORE(heap, idx) RARRAY_AREF((heap)->scores, idx)
-#define DHEAP_ASSIGN(heap, idx, scr, val) \
-    rb_ary_store(heap->scores, idx, scr); \
-    rb_ary_store(heap->values, idx, val);
-#define DHEAP_APPEND(heap, scr, val) \
-    rb_ary_push((heap)->scores, scr); \
-    rb_ary_push((heap)->values, val);
-#define DHEAP_DROP_LAST(heap) ( \
-        rb_ary_pop(heap->scores), \
-        rb_ary_pop(heap->values) \
-    ) // score, value
-
-#define DHEAP_Check_d_size(d) \
-    if (d < 2) { \
-        rb_raise(rb_eArgError, "DHeap d=%d is too small", d); \
-    } \
-    if (d > DHEAP_MAX_D) { \
-        rb_raise(rb_eArgError, "DHeap d=%d is too large", d); \
-    }
+#include "ruby.h"
+#include <float.h>
+#include <math.h>
 
-#define DHEAP_Check_Index(index, last_index) \
-    if (index < 0) { \
-        rb_raise(rb_eIndexError, "DHeap index %ld too small", index); \
-    } \
-    else if (last_index < index) { \
-        rb_raise(rb_eIndexError, "DHeap index %ld too large", index); \
-    }
+#if CHAR_BIT != 8
+#    error "DHeap assumes 8-bit bytes"
+#endif
+
+#if SIZE_MAX != ULONG_MAX
+#    error "DHeap assumes 'size_t' is 'unsigned long'"
+#endif
+
+#if LDBL_MANT_DIG < SIZEOF_UNSIGNED_LONG_LONG * 8
+#    error "DHeap assumes 'long double' mantissa can store 'unsigned long long'"
+#endif
+
+// TODO: test this code on a 32 bit system (it MUST have some bugs!)
+// TODO: perhaps just convert from "unsigned long long" to "uint64_t"!
+#if SIZEOF_UNSIGNED_LONG_LONG * 8 != 64
+#    error "DHeap assumes 64-bit 'unsigned long long'"
+#endif
+
+/********************************************************************
+ *
+ * Type definitions
+ *
+ ********************************************************************/
 
-struct dheap_struct {
-    int d;
-    VALUE scores;
-    VALUE values;
-};
 typedef struct dheap_struct dheap_t;
+typedef struct dheap_entry  ENTRY;
+
+typedef double SCORE;
+
+/********************************************************************
+ *
+ * Struct definitions
+ *
+ ********************************************************************/
+
+struct dheap_struct
+{
+    int    d;
+    size_t size;
+    size_t capa;
+    ENTRY *entries;
+#ifdef DHEAP_MAP
+    VALUE indexes; // Hash
+#endif
+};
+
+struct dheap_entry
+{
+    SCORE score;
+    VALUE value;
+};
+
+#define DHEAPMAP_P(heap) UNLIKELY(RTEST((heap)->indexes))
+
+/********************************************************************
+ *
+ * Constant definitions
+ *
+ ********************************************************************/
+
+#define DHEAP_DEFAULT_D 6
+#define DHEAP_MAX_D     INT_MAX
+
+// sizeof(ENTRY) => 16 bytes, 128-bits
+// one kilobyte = 32 * 32 bytes
+#define DHEAP_DEFAULT_CAPA  32
+#define DHEAP_MAX_CAPA      (SIZE_MAX / (int)sizeof(ENTRY))
+#define DHEAP_CAPA_INCR_MAX (10 * 1024 * 1024 / (int)sizeof(ENTRY))
+
+static ID id_cmp;    // <=>
+static ID id_abs;    // abs
+static ID id_lshift; // <<
+static ID id_uminus; // -@
+
+static const rb_data_type_t dheap_data_type;
+
+/********************************************************************
+ *
+ * Metaprogramming macros
+ *
+ ********************************************************************/
+
+#define LIKELY   RB_LIKELY
+#define UNLIKELY RB_UNLIKELY
+
+#ifdef DHEAP_MAP
+#    define DHEAP_DISPATCH_EXPR(func, heap, ...)                               \
+        (DHEAPMAP_P(heap) ? dheapmap_##func(heap, __VA_ARGS__)                 \
+                          : dheap_##func(heap, __VA_ARGS__))
+#else
+#    define DHEAP_DISPATCH_EXPR(func, heap, ...)                               \
+        dheap_##func(heap, __VA_ARGS__);
+#endif
+
+#ifdef DHEAP_MAP
+#    define DHEAP_DISPATCH_STMT(heap, macro, ...)                              \
+        do {                                                                   \
+            if (DHEAPMAP_P(heap)) {                                            \
+                macro(dheapmap, heap, __VA_ARGS__);                            \
+            } else {                                                           \
+                macro(dheap, heap, __VA_ARGS__);                               \
+            }                                                                  \
+        } while (0)
+#else
+#    define DHEAP_DISPATCH_STMT(heap, macro, ...)                              \
+        macro(dheap, heap, __VA_ARGS__)
+#endif
+
+/********************************************************************
+ *
+ * SCORE: casting to and from VALUE
+ *    adapted from similar methods in ruby's object.c
+ *
+ ********************************************************************/
+
+#define SCORE2NUM(score) rb_float_new(score)
+#define VAL2SCORE(val)   NUM2DBL(RB_FLOAT_TYPE_P(val) ? val : rb_Float(val))
+#define CMP_LT(a, b)     ((a) < (b))
+#define CMP_LTE(a, b)    ((a) <= (b))
+
+/********************************************************************
+ *
+ * DHeap ENTRY accessors
+ *
+ ********************************************************************/
 
+#define DHEAP_SCORE(heap, idx) (DHEAP_GET(heap, idx).score)
+#define DHEAP_VALUE(heap, idx) (DHEAP_GET(heap, idx).value)
+
+#define DHEAP_ENTRY_ARY(heap, idx)                                             \
+    (((heap)->size <= (idx))                                                   \
+       ? Qnil                                                                  \
+       : rb_ary_new_from_args(                                                 \
+           2, DHEAP_VALUE(heap, idx), SCORE2NUM(DHEAP_SCORE(heap, idx))))
+
+#define DHEAP_GET(heap, idx) ((heap)->entries[idx])
+#define DHEAP_SET(T, heap, index, entry)                                       \
+    do {                                                                       \
+        DHEAP_GET(heap, index) = (entry);                                      \
+        DHEAP_SET_##T(heap, index, entry);                                     \
+    } while (0)
+
+#define DHEAP_SET_dheap(heap, index, entry) /* noop */
+
+#ifdef DHEAP_MAP
+#    define DHEAP_SET_dheapmap(heap, index, entry)                             \
+        rb_hash_aset((heap)->indexes, (entry).value, ULONG2NUM(index))
+#endif
+
+/********************************************************************
+ *
+ * DHeap index math
+ *
+ ********************************************************************/
+
+#define DHEAP_IDX_LAST(heap)         ((heap)->size - 1)
+#define DHEAP_IDX_PARENT(heap, idx)  (((idx)-1) / (heap)->d)
+#define DHEAP_IDX_CHILD_0(heap, idx) (((idx) * (heap)->d) + 1)
+#define DHEAP_IDX_CHILD_D(heap, idx) (((idx) * (heap)->d) + (heap)->d)
+
+#ifdef DEBUG
+#    define ASSERT_DHEAP_IDX_OK(heap, index)                                   \
+        do {                                                                   \
+            if (DHEAP_IDX_LAST(heap) < index) {                                \
+                rb_raise(rb_eIndexError, "DHeap index %ld too large", index);  \
+            }                                                                  \
+        } while (0)
+#else
+#    define ASSERT_DHEAP_IDX_OK(heap, index)
+#endif
+
+/********************************************************************
+ *
+ * rb_data_type_t definitions
+ *
+ ********************************************************************/
+
+#ifdef HAVE_RB_GC_MARK_MOVABLE
 static void
 dheap_compact(void *ptr)
 {
     dheap_t *heap = ptr;
-    if (heap->scores) dheap_gc_location( heap->scores );
-    if (heap->values) dheap_gc_location( heap->values );
+    for (size_t i = 0; i < heap->size; ++i) {
+        if (DHEAP_VALUE(heap, i))
+            DHEAP_VALUE(heap, i) = rb_gc_location(DHEAP_VALUE(heap, i));
+    }
+#    ifdef DHEAP_MAP
+    if (DHEAPMAP_P(heap)) heap->indexes = rb_gc_location(heap->indexes);
+#    endif
 }
+#else
+#    define rb_gc_mark_movable(x) rb_gc_mark(x)
+#endif
 
 static void
 dheap_mark(void *ptr)
 {
     dheap_t *heap = ptr;
-    if (heap->scores) rb_gc_mark_movable(heap->scores);
-    if (heap->values) rb_gc_mark_movable(heap->values);
+    for (size_t i = 0; i < heap->size; ++i) {
+        if (DHEAP_VALUE(heap, i)) rb_gc_mark_movable(DHEAP_VALUE(heap, i));
+    }
+#ifdef DHEAP_MAP
+    if (DHEAPMAP_P(heap)) rb_gc_mark_movable(heap->indexes);
+#endif
+}
+
+static void
+dheap_free(void *ptr)
+{
+    dheap_t *heap = ptr;
+    heap->size    = 0;
+    if (heap->entries) {
+        xfree(heap->entries);
+        heap->entries = NULL;
+    }
+    heap->capa = 0;
+    xfree(ptr);
+#ifdef DHEAP_MAP
+    heap->indexes = Qnil;
+#endif
 }
 
 static size_t
 dheap_memsize(const void *ptr)
 {
     const dheap_t *heap = ptr;
-    size_t size = sizeof(*heap);
+    size_t         size = 0;
+    size += sizeof(*heap);
+    size += sizeof(ENTRY) * heap->capa;
     return size;
 }
 
 static const rb_data_type_t dheap_data_type = {
     "DHeap",
-    {
-        (void (*)(void*))dheap_mark,
-        (void (*)(void*))RUBY_DEFAULT_FREE,
-        (size_t (*)(const void *))dheap_memsize,
-        dheap_compact_callback(dheap_compact),
+    { (void (*)(void *))dheap_mark,
+      (void (*)(void *))dheap_free,
+      (size_t(*)(const void *))dheap_memsize,
+#ifdef HAVE_RB_GC_MARK_MOVABLE
+      (void (*)(void *))dheap_compact,
+      { 0 }
+#else
+      { 0 }
+#endif
     },
-    0, 0,
+    0,
+    0,
     RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
+/********************************************************************
+ *
+ * DHeap comparisons
+ *
+ ********************************************************************/
+
+/********************************************************************
+ *
+ * DHeap allocation and initialization and resizing
+ *
+ ********************************************************************/
+
 static VALUE
 dheap_s_alloc(VALUE klass)
 {
-    VALUE obj;
+    VALUE    obj;
     dheap_t *heap;
 
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpedantic"
+    // TypedData_Make_Struct uses a non-std "statement expression"
     obj = TypedData_Make_Struct(klass, dheap_t, &dheap_data_type, heap);
-    heap->d = DHEAP_DEFAULT_D;
-    heap->scores = Qnil;
-    heap->values = Qnil;
+#pragma GCC diagnostic pop
+    heap->d       = DHEAP_DEFAULT_D;
+    heap->size    = 0;
+    heap->capa    = 0;
+    heap->entries = NULL;
+#ifdef DHEAP_MAP
+    heap->indexes = Qnil;
+#endif
 
     return obj;
 }
@@ -103,168 +290,183 @@ get_dheap_struct(VALUE self)
 {
     dheap_t *heap;
     TypedData_Get_Struct(self, dheap_t, &dheap_data_type, heap);
-    Check_Type(heap->scores, T_ARRAY);
     return heap;
 }
 
-/*
- * @overload initialize(d = DHeap::DEFAULT_D)
- *   Initialize a _d_-ary min-heap.
- *
- *   @param d [Integer] maximum number of children per parent
- */
-static VALUE
-dheap_initialize(int argc, VALUE *argv, VALUE self) {
-    rb_check_arity(argc, 0, 1);
-    dheap_t *heap;
-    TypedData_Get_Struct(self, dheap_t, &dheap_data_type, heap);
+static inline dheap_t *
+get_dheap_struct_unfrozen(VALUE self)
+{
+    rb_check_frozen(self);
+    return get_dheap_struct(self);
+}
 
-    int d = DHEAP_DEFAULT_D;
-    if (argc) {
-        d = NUM2INT(argv[0]);
+void
+dheap_set_capa(dheap_t *heap, size_t new_capa)
+{
+    // Do nothing if we already have the capacity or are resizing too small
+    if (new_capa <= heap->capa || new_capa <= heap->size) return;
+
+    // allocate
+    if (heap->entries) {
+        RB_REALLOC_N(heap->entries, ENTRY, new_capa);
+    } else {
+        heap->entries = RB_ZALLOC_N(ENTRY, new_capa);
     }
-    DHEAP_Check_d_size(d);
-    heap->d = d;
-
-    heap->scores = rb_ary_new_capa(10000);
-    heap->values = rb_ary_new_capa(10000);
+    heap->capa = new_capa;
+}
 
-    return self;
+static void
+dheap_incr_capa(dheap_t *heap, size_t new_size)
+{
+    size_t new_capa = heap->capa;
+    while (new_capa < new_size) {
+        if (new_capa <= DHEAP_CAPA_INCR_MAX) {
+            // double it... up to DHEAP_CAPA_INCR_MAX
+            new_capa *= 2;
+        } else if (DHEAP_MAX_CAPA - DHEAP_CAPA_INCR_MAX < heap->capa) {
+            // avoid overflow
+            new_capa = DHEAP_MAX_CAPA;
+        } else {
+            new_capa += DHEAP_CAPA_INCR_MAX;
+        }
+    }
+    dheap_set_capa(heap, new_capa);
 }
 
-/*
-static inline VALUE
-make_dheap_element(VALUE score, VALUE value)
-{
-    elem_t *elem;
-    VALUE obj = TypedData_Make_Struct(
-            rb_cObject,
-            elem_t,
-            &dheap_elem_type,
-            elem);
-    elem->score = score;
-    elem->value = value;
-    return obj;
+static void
+dheap_ensure_room_for_push(dheap_t *heap, size_t incr_by)
+{
+    // check for overflow of new_size
+    if (DHEAP_MAX_CAPA - incr_by < heap->size) {
+        rb_raise(rb_eIndexError,
+                 "size increase overflow: %zu + %zu",
+                 heap->size,
+                 incr_by);
+    } else {
+        size_t new_size = heap->size + incr_by;
+        // if existing capacity is too small
+        if (heap->capa < new_size) dheap_incr_capa(heap, new_size);
+    }
 }
 
-#define IsDHeapElem(value) rb_typeddata_is_kind_of((value), &dheap_elem_type)
-#define Get_DHeap_Elem(value) \
-    TypedData_Get_Struct((obj), elem_t, &dheap_elem_type, (elem))
+static inline int
+dheap_value_to_int_d(VALUE num)
+{
+    int d = NUM2INT(num);
+    if (d < 2) rb_raise(rb_eArgError, "DHeap d=%u is too small", d);
+    if (d > DHEAP_MAX_D) rb_raise(rb_eArgError, "DHeap d=%u is too large", d);
+    return d;
+}
 
-static inline elem_t *
-get_dheap_element(VALUE obj)
+static inline size_t
+dheap_value_to_capa(VALUE num)
 {
-    elem_t *elem;
-    TypedData_Get_Struct((obj), elem_t, &dheap_elem_type, (elem));
-    return elem;
+    size_t capa = NUM2ULONG(num);
+    if (capa < 1) {
+        rb_raise(rb_eArgError, "DHeap capa=%zu must be positive", capa);
+    }
+    return capa;
 }
 
-*/
+static VALUE
+dheap_init(VALUE self, VALUE d, VALUE capa, VALUE map)
+{
+    dheap_t *heap = get_dheap_struct(self);
 
-#define CMP_LT(a, b)  (optimized_cmp(a, b) <  0)
-#define CMP_LTE(a, b) (optimized_cmp(a, b) <= 0)
-#define CMP_GT(a, b)  (optimized_cmp(a, b) >  0)
-#define CMP_GTE(a, b) (optimized_cmp(a, b) >= 0)
+    if (heap->entries || heap->size || heap->capa)
+        rb_raise(rb_eScriptError, "DHeap already initialized.");
 
-/*
- * short-circuit evaluation for a few basic types.
- *
- * Only Integer, Float, and String are optimized,
- * and only when both arguments are the same type.
- */
-static inline int
-optimized_cmp(VALUE a, VALUE b) {
-    if (a == b) // Fixnum equality and object equality
-        return 0;
-    if (FIXNUM_P(a) && FIXNUM_P(b))
-        return (FIX2LONG(a) < FIX2LONG(b)) ? -1 : 1;
-    if (RB_FLOAT_TYPE_P(a) && RB_FLOAT_TYPE_P(b))
-    {
-        double x, y;
-        x = RFLOAT_VALUE(a);
-        y = RFLOAT_VALUE(b);
-        if (isnan(x) || isnan(y)) rb_cmperr(a, b); // raise ArgumentError
-        return (x < y) ? -1 : ((x == y) ? 0 : 1);
-    }
-    if (RB_TYPE_P(a, T_BIGNUM) && RB_TYPE_P(b, T_BIGNUM))
-        return FIX2INT(rb_big_cmp(a, b));
-    if (STRING_P(a) && STRING_P(b))
-        return rb_str_cmp(a, b);
+    heap->d = dheap_value_to_int_d(d);
+    dheap_set_capa(heap, dheap_value_to_capa(capa));
+#ifdef DHEAP_MAP
+    if (RTEST(map)) heap->indexes = rb_hash_new();
+#endif
 
-    // give up on an optimized version and just call (a <=> b)
-    return rb_cmpint(rb_funcallv(a, id_cmp, 1, &b), a, b);
+    return self;
 }
 
-VALUE
-dheap_ary_sift_up(dheap_t *heap, long sift_index) {
-    long last_index = DHEAP_IDX_LAST(heap);
-    DHEAP_Check_Index(sift_index, last_index);
-
-    VALUE sift_value = DHEAP_VALUE(heap, sift_index);
-    VALUE sift_score = DHEAP_SCORE(heap, sift_index);
+/* @!visibility private */
+static VALUE
+dheap_initialize_copy(VALUE copy, VALUE orig)
+{
+    dheap_t *heap_copy = get_dheap_struct_unfrozen(copy);
+    dheap_t *heap_orig = get_dheap_struct(orig);
 
-    // sift it up to where it belongs
-    for (long parent_index; 0 < sift_index; sift_index = parent_index) {
-        debug(rb_sprintf("sift up(%"PRIsVALUE", %d, %ld)", heap->values, heap->d, sift_index));
-        parent_index = DHEAP_IDX_PARENT(heap, sift_index);
-        VALUE parent_score = DHEAP_SCORE(heap, parent_index);
+    heap_copy->d = heap_orig->d;
 
-        // parent is smaller: heap is restored
-        if (CMP_LTE(parent_score, sift_score)) break;
+    dheap_set_capa(heap_copy, heap_orig->capa);
+    heap_copy->size = heap_orig->size;
+    if (heap_copy->size)
+        MEMCPY(heap_copy->entries, heap_orig->entries, ENTRY, heap_orig->size);
+#ifdef DHEAP_MAP
+    if (RTEST(heap_orig->indexes))
+        heap_copy->indexes = rb_hash_dup(heap_orig->indexes);
+#endif
 
-        // parent is larger: swap and continue sifting up
-        VALUE parent_value = DHEAP_VALUE(heap, parent_index);
-        DHEAP_ASSIGN(heap, sift_index, parent_score, parent_value);
-        DHEAP_ASSIGN(heap, parent_index, sift_score, sift_value);
-    }
-    debug(rb_sprintf("sifted (%"PRIsVALUE", %d, %ld)", heap->values, heap->d, sift_index));
-    return LONG2NUM(sift_index);
-}
-
-VALUE
-dheap_ary_sift_down(dheap_t *heap, long sift_index) {
-    long last_index = DHEAP_IDX_LAST(heap);
-    DHEAP_Check_Index(sift_index, last_index);
-
-    VALUE sift_value = DHEAP_VALUE(heap, sift_index);
-    VALUE sift_score = DHEAP_SCORE(heap, sift_index);
-
-     // iteratively sift it down to where it belongs
-    for (long child_index; sift_index < last_index; sift_index = child_index) {
-        debug(rb_sprintf("sift dn(%"PRIsVALUE", %d, %ld)", heap->values, heap->d, sift_index));
-        // find first child index, and break if we've reached the last layer
-        long child_idx0 = child_index = DHEAP_IDX_CHILD0(heap, sift_index);
-        if (last_index < child_idx0) break;
-
-        // find the min child (and its child_index)
-        // requires "d" comparisons to find min child and compare to sift_score
-        long last_sibidx = child_idx0 + heap->d - 1;
-        if (last_index < last_sibidx) last_sibidx = last_index;
-        VALUE child_score = DHEAP_SCORE(heap, child_idx0);
-        child_index = child_idx0;
-        for (long sibling_index = child_idx0 + 1;
-                sibling_index <= last_sibidx;
-                ++sibling_index) {
-            VALUE sibling_score = DHEAP_SCORE(heap, sibling_index);
-
-            if (CMP_LT(sibling_score, child_score)) {
-                child_score = sibling_score;
-                child_index = sibling_index;
-            }
-        }
+    return copy;
+}
 
-        // child is larger: heap is restored
-        if (CMP_LTE(sift_score, child_score)) break;
+/********************************************************************
+ *
+ * DHeap sift up/down
+ *
+ ********************************************************************/
+
+#define DHEAP_SIFT_UP(T, heap, i)                                              \
+    do {                                                                       \
+        size_t sift_idx = i;                                                   \
+        ENTRY  entry    = DHEAP_GET(heap, sift_idx);                           \
+        ASSERT_DHEAP_IDX_OK(heap, sift_idx);                                   \
+        for (size_t parent_idx; 0 < sift_idx; sift_idx = parent_idx) {         \
+            parent_idx = DHEAP_IDX_PARENT(heap, sift_idx);                     \
+            if (CMP_LTE(DHEAP_SCORE((heap), parent_idx), entry.score)) break;  \
+            DHEAP_SET(T, heap, sift_idx, DHEAP_GET(heap, parent_idx));         \
+        }                                                                      \
+        DHEAP_SET(T, heap, sift_idx, entry);                                   \
+    } while (0)
+
+static inline size_t
+dheap_min_child(dheap_t *heap, size_t parent, size_t last_index)
+{
+    size_t min_child = DHEAP_IDX_CHILD_0(heap, parent);
+    size_t last_sib  = DHEAP_IDX_CHILD_D(heap, parent);
+    if (UNLIKELY(last_index < last_sib)) last_sib = last_index;
 
-        // child is smaller: swap and continue sifting down
-        VALUE child_value = DHEAP_VALUE(heap, child_index);
-        DHEAP_ASSIGN(heap, sift_index, child_score, child_value);
-        DHEAP_ASSIGN(heap, child_index, sift_score, sift_value);
+    for (size_t sibidx = min_child + 1; sibidx <= last_sib; ++sibidx) {
+        if (CMP_LT(DHEAP_SCORE(heap, sibidx), DHEAP_SCORE(heap, min_child))) {
+            min_child = sibidx;
+        }
     }
-    debug(rb_sprintf("sifted (%"PRIsVALUE", %d, %ld)", heap->values, heap->d, sift_index));
-    return LONG2NUM(sift_index);
+    return min_child;
 }
 
+#define DHEAP_CAN_SIFT_DOWN(heap, index, last_index)                           \
+    (LIKELY(1 <= last_index && index <= DHEAP_IDX_PARENT(heap, last_index)))
+
+#define DHEAP_SIFT_DOWN(T, heap, i)                                            \
+    do {                                                                       \
+        size_t sift_idx = i;                                                   \
+        size_t last_idx = DHEAP_IDX_LAST(heap);                                \
+        ASSERT_DHEAP_IDX_OK(heap, sift_idx);                                   \
+        if (DHEAP_CAN_SIFT_DOWN(heap, sift_idx, last_idx)) {                   \
+            ENTRY  entry       = heap->entries[sift_idx];                      \
+            size_t last_parent = DHEAP_IDX_PARENT(heap, last_idx);             \
+            while (sift_idx <= last_parent) {                                  \
+                size_t min_child = dheap_min_child(heap, sift_idx, last_idx);  \
+                if (CMP_LTE(entry.score, DHEAP_SCORE(heap, min_child))) break; \
+                DHEAP_SET(T, heap, sift_idx, (heap)->entries[min_child]);      \
+                sift_idx = min_child;                                          \
+            }                                                                  \
+            DHEAP_SET(T, heap, sift_idx, entry);                               \
+        }                                                                      \
+    } while (0)
+
+/********************************************************************
+ *
+ * DHeap attributes
+ *
+ ********************************************************************/
+
 /*
  * @return [Integer] the number of elements in the heap
  */
@@ -272,19 +474,19 @@ static VALUE
 dheap_size(VALUE self)
 {
     dheap_t *heap = get_dheap_struct(self);
-    long size = DHEAP_SIZE(heap);
-    return LONG2NUM(size);
+    return ULONG2NUM(heap->size);
 }
 
+#define DHEAP_EMPTY_P(heap) UNLIKELY((heap)->size <= 0)
+
 /*
- * @return [Boolean] is the heap empty?
+ * @return [Boolean] if the heap is empty
  */
 static VALUE
 dheap_empty_p(VALUE self)
 {
     dheap_t *heap = get_dheap_struct(self);
-    long size = DHEAP_SIZE(heap);
-    return size == 0 ? Qtrue : Qfalse;
+    return DHEAP_EMPTY_P(heap) ? Qtrue : Qfalse;
 }
 
 /*
@@ -297,188 +499,608 @@ dheap_attr_d(VALUE self)
     return INT2FIX(heap->d);
 }
 
+/********************************************************************
+ *
+ * DHeap push
+ *
+ ********************************************************************/
+
+#define DHEAP_PUSH(T, heap, entry)                                             \
+    do {                                                                       \
+        dheap_ensure_room_for_push(heap, 1);                                   \
+        DHEAP_SET(T, heap, (heap)->size, *(entry));                            \
+        ++heap->size;                                                          \
+        DHEAP_SIFT_UP(T, heap, DHEAP_IDX_LAST(heap));                          \
+    } while (0)
+
+static inline void
+dheap_push_entry(VALUE self, ENTRY *entry)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    DHEAP_PUSH(dheap, heap, entry);
+}
+
+#ifdef DHEAP_MAP
+static inline void
+dheapmap_update_entry(dheap_t *heap, size_t index, ENTRY *entry)
+{
+    SCORE prev = DHEAP_SCORE(heap, index);
+    DHEAP_SET(dheapmap, heap, index, *entry);
+    if (CMP_LT(prev, entry->score)) {
+        DHEAP_SIFT_DOWN(dheapmap, heap, index);
+    } else {
+        DHEAP_SIFT_UP(dheapmap, heap, index);
+    }
+}
+
+static inline void
+dheapmap_push_entry(VALUE self, ENTRY *entry)
+{
+    dheap_t *heap   = get_dheap_struct_unfrozen(self);
+    VALUE    idxval = rb_hash_lookup2(heap->indexes, entry->value, Qfalse);
+    if (idxval) {
+        size_t index = NUM2ULONG(idxval);
+        dheapmap_update_entry(heap, index, entry);
+        return;
+    }
+    DHEAP_PUSH(dheapmap, heap, entry);
+}
+#endif
+
 /*
- * Freezes the heap as well as its underlying array, but does <i>not</i>
- * deep-freeze the elements in the heap.
+ * Inserts a value into the heap, using a score to determine sort-order.
+ *
+ * Score comes first, as an analogy with the +Array#insert+ index.
+ *
+ * Time complexity: <b>O(log n / log d)</b> <i>(worst-case)</i>
+ *
+ * @param score [Integer,Float,#to_f] a score to compare against other scores.
+ * @param value [Object] an object that is associated with the score.
  *
  * @return [self]
  */
 static VALUE
-dheap_freeze(VALUE self) {
-    dheap_t *heap = get_dheap_struct(self);
-    ID id_freeze = rb_intern("freeze");
-    rb_funcall(heap->scores, id_freeze, 0);
-    rb_funcall(heap->values, id_freeze, 0);
-    return rb_call_super(0, NULL);
+dheap_insert(VALUE self, VALUE score, VALUE value)
+{
+    ENTRY entry = { VAL2SCORE(score), value };
+    dheap_push_entry(self, &entry);
+    return self;
+}
+
+#ifdef DHEAP_MAP
+/* (see DHeap#insert) */
+static VALUE
+dheapmap_insert(VALUE self, VALUE score, VALUE value)
+{
+    ENTRY entry = { VAL2SCORE(score), value };
+    dheapmap_push_entry(self, &entry);
+    return self;
+}
+#endif
+
+static inline ENTRY
+dheap_push_args_to_entry(int argc, VALUE *argv)
+{
+    ENTRY entry;
+    rb_check_arity(argc, 1, 2);
+    entry.value = argv[0];
+    entry.score = VAL2SCORE(argc < 2 ? entry.value : argv[1]);
+    return entry;
 }
 
 /*
- * @overload push(score, value = score)
+ * @overload push(value, score = value)
  *
  * Push a value onto heap, using a score to determine sort-order.
  *
- * Ideally, the score should be a frozen value that can be efficiently compared
- * to other scores, e.g. an Integer or Float or (maybe) a String
+ * Value comes first because the separate score is optional, and because it
+ * feels like a more natural variation on +Array#push+ or +Queue#enq+.  If a
+ * score isn't provided, the value must be an Integer or can be cast with
+ * +Float(value)+.
  *
  * Time complexity: <b>O(log n / log d)</b> <i>(worst-case)</i>
  *
- * @param score [#<=>] a value that can be compared to other scores.
  * @param value [Object] an object that is associated with the score.
+ * @param score [Integer,Float,#to_f] a score to compare against other scores.
  *
- * @return [Integer] the index of the value's final position.
+ * @return [self]
  */
 static VALUE
-dheap_push(int argc, VALUE *argv, VALUE self) {
-    rb_check_arity(argc, 1, 2);
-    VALUE scr  = argv[0];
-    VALUE val  = argc < 2 ? scr : argv[1];
-
-    dheap_t *heap = get_dheap_struct(self);
+dheap_push(int argc, VALUE *argv, VALUE self)
+{
+    ENTRY entry = dheap_push_args_to_entry(argc, argv);
+    dheap_push_entry(self, &entry);
+    return self;
+}
 
-    DHEAP_APPEND(heap, scr, val);
-    long last_index = DHEAP_IDX_LAST(heap);
-    return dheap_ary_sift_up(heap, last_index);
+#ifdef DHEAP_MAP
+/* (see DHeap#push) */
+static VALUE
+dheapmap_push(int argc, VALUE *argv, VALUE self)
+{
+    ENTRY entry = dheap_push_args_to_entry(argc, argv);
+    dheapmap_push_entry(self, &entry);
+    return self;
 }
+#endif
 
 /*
- * Pushes a comparable value onto the heap.
+ * Pushes a value onto the heap.
  *
- * The value will be its own score.
+ * The score will be derived from the value, by using the value itself if it is
+ * an Integer, otherwise by casting it with +Float(value)+.
  *
  * Time complexity: <b>O(log n / log d)</b> <i>(worst-case)</i>
  *
- * @param value [#<=>] a value that can be compared to other heap members.
+ * @param value [Integer,#to_f] a value with an intrinsic numeric score
  * @return [self]
  */
 static VALUE
-dheap_left_shift(VALUE self, VALUE value) {
-    dheap_push(1, &value, self);
+dheap_lshift(VALUE self, VALUE value)
+{
+    ENTRY entry = { VAL2SCORE(value), value };
+    dheap_push_entry(self, &entry);
+    return self;
+}
+
+#ifdef DHEAP_MAP
+/* (see DHeap#<<) */
+static VALUE
+dheapmap_lshift(VALUE self, VALUE value)
+{
+    ENTRY entry = { VAL2SCORE(value), value };
+    dheapmap_push_entry(self, &entry);
     return self;
 }
+#endif
+
+/********************************************************************
+ *
+ * DHeap pop and peek
+ *
+ ********************************************************************/
+
+#define PEEK_VALUE(heap)            DHEAP_VALUE(heap, 0)
+#define PEEK_SCORE(heap)            DHEAP_SCORE(heap, 0)
+#define PEEK_WITH_SCORE(heap)       DHEAP_ENTRY_ARY(heap, 0)
+#define PEEK_LT_P(heap, max_score)  _PEEK_CMP_P(heap, CMP_LT, max_score)
+#define PEEK_LTE_P(heap, max_score) _PEEK_CMP_P(heap, CMP_LTE, max_score)
+#define _PEEK_CMP_P(heap, cmp, score)                                          \
+    ((!DHEAP_EMPTY_P(heap) && cmp(PEEK_SCORE(heap), (score)))                  \
+       ? PEEK_VALUE(heap)                                                      \
+       : 0)
 
 /*
-    dheap_t hstruct; \
-    Get_DHeap(self, hstruct); \
-    VALUE values = hstruct.values; \
-    VALUE scores = hstruct.scores; \
-    VALUE dval = INT2FIX(hstruct.d); \
-*/
+ * Returns the next value on the heap, and its score, without popping it
+ *
+ * Time complexity: <b>O(1)</b> <i>(worst-case)</i>
+ * @return [nil,Array<(Object, Numeric)>] the next value and its score
+ *
+ * @see #peek
+ * @see #peek_score
+ */
+static VALUE
+dheap_peek_with_score(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct(self);
+    return PEEK_WITH_SCORE(heap);
+}
 
-static inline void
-dheap_pop_swap_last_and_sift_down(dheap_t *heap, long last_index)
+/*
+ * Returns the next score on the heap, without the value and without popping
+ * it.
+ *
+ * Time complexity: <b>O(1)</b> <i>(worst-case)</i>
+ * @return [nil, Numeric] the next score, if there is one
+ *
+ * @see #peek
+ * @see #peek_with_score
+ */
+static VALUE
+dheap_peek_score(VALUE self)
 {
-    if (last_index == 0) {
-        DHEAP_DROP_LAST(heap);
-    }
-    else
-    {
-        VALUE sift_value = DHEAP_VALUE(heap, last_index);
-        VALUE sift_score = DHEAP_SCORE(heap, last_index);
-        DHEAP_ASSIGN(heap, 0, sift_score, sift_value);
-        DHEAP_DROP_LAST(heap);
-        dheap_ary_sift_down(heap, 0);
-    }
+    dheap_t *heap = get_dheap_struct(self);
+    if (DHEAP_EMPTY_P(heap)) return Qnil;
+    return SCORE2NUM(PEEK_SCORE(heap));
 }
 
 /*
  * Returns the next value on the heap to be popped without popping it.
  *
  * Time complexity: <b>O(1)</b> <i>(worst-case)</i>
- * @return [Object] the next value to be popped without popping it.
+ * @return [nil, Object] the next value to be popped without popping it.
+ *
+ * @see #peek_score
+ * @see #peek_with_score
  */
 static VALUE
-dheap_peek(VALUE self) {
+dheap_peek(VALUE self)
+{
     dheap_t *heap = get_dheap_struct(self);
-    if (DHEAP_IDX_LAST(heap) < 0) return Qnil;
-    return DHEAP_VALUE(heap, 0);
+    if (DHEAP_EMPTY_P(heap)) return Qnil;
+    return PEEK_VALUE(heap);
 }
 
+#define DHEAP_POP_COMMON_INIT(self)                                            \
+    dheap_t *heap = get_dheap_struct_unfrozen(self);                           \
+    if (DHEAP_EMPTY_P(heap)) return Qnil;
+
+#define DHEAP_DELETE_0(T, heap)                                                \
+    do {                                                                       \
+        _DELETE_ENTRY(T, heap, 0);                                             \
+        if (0 < --(heap)->size) {                                              \
+            DHEAP_SET(T, (heap), 0, (heap)->entries[(heap)->size]);            \
+            DHEAP_SIFT_DOWN(T, (heap), 0);                                     \
+        }                                                                      \
+    } while (0)
+
+#define _DELETE_ENTRY(T, heap, idx)    _DELETE_ENTRY_##T(heap, idx)
+#define _DELETE_ENTRY_dheap(heap, idx) /* noop */
+#define _DELETE_ENTRY_dheapmap(heap, idx)                                      \
+    rb_hash_delete(heap->indexes, DHEAP_VALUE(heap, idx))
+
+#define POP(T, heap, popped)            _POP(T, VALUE, heap, popped)
+#define POP_WITH_SCORE(T, heap, popped) _POP(T, WITH_SCORE, heap, popped)
+#define POP_LT(T, heap, max, popped)    _POP_CMP(T, heap, LT, max, popped)
+#define POP_LTE(T, heap, max, popped)   _POP_CMP(T, heap, LTE, max, popped)
+
+#define _POP_CMP(T, heap, cmp, cmp_score, popped)                              \
+    do {                                                                       \
+        if ((*(popped) = PEEK_##cmp##_P(heap, cmp_score))) {                   \
+            DHEAP_DELETE_0(T, heap);                                           \
+        } else {                                                               \
+            *(popped) = Qnil;                                                  \
+        }                                                                      \
+    } while (0)
+
+#define _POP(T, peek_type, heap, popped)                                       \
+    do {                                                                       \
+        if (DHEAP_EMPTY_P(heap)) {                                             \
+            *(popped) = Qnil;                                                  \
+        } else {                                                               \
+            *(popped) = PEEK_##peek_type(heap);                                \
+            DHEAP_DELETE_0(T, heap);                                           \
+        }                                                                      \
+    } while (0)
+
 /*
  * Pops the minimum value from the top of the heap
  *
  * Time complexity: <b>O(d log n / log d)</b> <i>(worst-case)</i>
+ *
+ * @return [Object] the value with the minimum score
+ *
+ * @see #peek
+ * @see #pop_lt
+ * @see #pop_lte
+ * @see #pop_with_score
  */
 static VALUE
-dheap_pop(VALUE self) {
-    dheap_t *heap = get_dheap_struct(self);
-    long last_index = DHEAP_IDX_LAST(heap);
-
-    if (last_index < 0) return Qnil;
-    VALUE pop_value = DHEAP_VALUE(heap, 0);
+dheap_pop(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP(dheap, heap, &popped);
+    return popped;
+}
 
-    dheap_pop_swap_last_and_sift_down(heap, last_index);
-    return pop_value;
+#ifdef DHEAP_MAP
+/* (see DHeap#pop) */
+static VALUE
+dheapmap_pop(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP(dheapmap, heap, &popped);
+    return popped;
 }
+#endif
 
 /*
- * Pops the minimum value only if it is less than or equal to a max score.
+ * Pops the minimum value from the top of the heap, along with its score.
+ *
+ * Time complexity: <b>O(d log n / log d)</b> <i>(worst-case)</i>
  *
- * @param max_score [#<=>] the maximum score to be popped
+ * @return [nil,Array<(Object, Numeric)>] the next value and its score
  *
  * @see #pop
+ * @see #peek_with_score
  */
 static VALUE
-dheap_pop_lte(VALUE self, VALUE max_score) {
-    dheap_t *heap = get_dheap_struct(self);
-    long last_index = DHEAP_IDX_LAST(heap);
+dheap_pop_with_score(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_WITH_SCORE(dheap, heap, &popped);
+    return popped;
+}
 
-    if (last_index <  0) return Qnil;
-    VALUE pop_value = DHEAP_VALUE(heap, 0);
+#ifdef DHEAP_MAP
+/* (see DHeap#pop_with_score) */
+static VALUE
+dheapmap_pop_with_score(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_WITH_SCORE(dheapmap, heap, &popped);
+    return popped;
+}
+#endif
 
-    VALUE pop_score = DHEAP_SCORE(heap, 0);
-    if (max_score && !CMP_LTE(pop_score, max_score)) return Qnil;
+#define DHEAP_POP_IF(heap, cmp, max_score)                                     \
+    if (!cmp(PEEK_SCORE(heap), VAL2SCORE(max_score))) return Qnil
+
+/*
+ * Pops the minimum value only if it is less than or equal to a max score.
+ *
+ * @param max_score [Integer,#to_f] the maximum score to be popped
+ *
+ * Time complexity: <b>O(d log n / log d)</b> <i>(worst-case)</i>
+ *
+ * @return [Object] the value with the minimum score
+ *
+ * @see #peek
+ * @see #pop
+ * @see #pop_lt
+ * @see #pop_all_below
+ */
+static VALUE
+dheap_pop_lte(VALUE self, VALUE max_score)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_LTE(dheap, heap, VAL2SCORE(max_score), &popped);
+    return popped;
+}
 
-    dheap_pop_swap_last_and_sift_down(heap, last_index);
-    return pop_value;
+#ifdef DHEAP_MAP
+/* (see DHeap#pop_lte) */
+static VALUE
+dheapmap_pop_lte(VALUE self, VALUE max_score)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_LTE(dheapmap, heap, VAL2SCORE(max_score), &popped);
+    return popped;
 }
+#endif
 
 /*
  * Pops the minimum value only if it is less than a max score.
  *
- * @param max_score [#<=>] the maximum score to be popped
+ * @param max_score [Integer,#to_f] the maximum score to be popped
  *
  * Time complexity: <b>O(d log n / log d)</b> <i>(worst-case)</i>
+ *
+ * @return [Object] the value with the minimum score
+ *
+ * @see #peek
+ * @see #pop
+ * @see #pop_lte
+ * @see #pop_all_below
  */
 static VALUE
-dheap_pop_lt(VALUE self, VALUE max_score) {
-    dheap_t *heap = get_dheap_struct(self);
-    long last_index = DHEAP_IDX_LAST(heap);
+dheap_pop_lt(VALUE self, VALUE max_score)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_LT(dheap, heap, VAL2SCORE(max_score), &popped);
+    return popped;
+}
 
-    if (last_index <  0) return Qnil;
-    VALUE pop_value = DHEAP_VALUE(heap, 0);
+#ifdef DHEAP_MAP
+/* (see DHeap#pop_lt) */
+static VALUE
+dheapmap_pop_lt(VALUE self, VALUE max_score)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    VALUE    popped;
+    POP_LT(dheapmap, heap, VAL2SCORE(max_score), &popped);
+    return popped;
+}
+#endif
+
+#define POP_ALL_BELOW(T, heap, max_score, array)                               \
+    do {                                                                       \
+        VALUE val = Qnil;                                                      \
+        if (RB_TYPE_P(array, T_ARRAY)) {                                       \
+            while ((val = PEEK_LT_P(heap, max_score))) {                       \
+                DHEAP_DELETE_0(T, heap);                                       \
+                rb_ary_push(array, val);                                       \
+            }                                                                  \
+        } else {                                                               \
+            while ((val = PEEK_LT_P(heap, max_score))) {                       \
+                DHEAP_DELETE_0(T, heap);                                       \
+                rb_funcall(array, id_lshift, 1, val);                          \
+            }                                                                  \
+        }                                                                      \
+    } while (0)
+
+/*
+ * @overload pop_all_below(max_score, receiver = [])
+ *
+ * Pops all value with score less than max score.
+ *
+ * Time complexity: <b>O(m * d log n / log d)</b>, <i>m = number popped</i>
+ *
+ * @param max_score [Integer,#to_f] the maximum score to be popped
+ * @param receiver  [Array,#<<] object onto which the values will be pushed,
+ *                              in order by score.
+ *
+ * @return [Object] the object onto which the values were pushed
+ *
+ * @see #pop
+ * @see #pop_lt
+ */
+static VALUE
+dheap_pop_all_below(int argc, VALUE *argv, VALUE self)
+{
+    dheap_t *heap      = get_dheap_struct_unfrozen(self);
+    SCORE    max_score = (argc) ? VAL2SCORE(argv[0]) : 0.0;
+    VALUE    array     = (argc == 1) ? rb_ary_new() : argv[1];
+    rb_check_arity(argc, 1, 2);
+    DHEAP_DISPATCH_STMT(heap, POP_ALL_BELOW, max_score, array);
+    return array;
+}
 
-    VALUE pop_score = DHEAP_SCORE(heap, 0);
-    if (max_score && !CMP_LT(pop_score, max_score)) return Qnil;
+/********************************************************************
+ *
+ * DHeap, misc methods
+ *
+ ********************************************************************/
 
-    dheap_pop_swap_last_and_sift_down(heap, last_index);
-    return pop_value;
+static VALUE
+dheap_to_a(VALUE self)
+{
+    dheap_t *heap  = get_dheap_struct(self);
+    VALUE    array = rb_ary_new_capa(heap->size);
+    for (size_t i = 0; i < heap->size; i++) {
+        rb_ary_push(array, DHEAP_ENTRY_ARY(heap, i));
+    }
+    return array;
 }
 
+/*
+ * Clears all values from the heap, leaving it empty.
+ *
+ * @return [self]
+ */
+static VALUE
+dheap_clear(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct_unfrozen(self);
+    if (!DHEAP_EMPTY_P(heap)) {
+        heap->size = 0;
+#ifdef DHEAP_MAP
+        if (DHEAPMAP_P(heap)) rb_hash_clear(heap->indexes);
+#endif
+    }
+    return self;
+}
+
+/********************************************************************
+ *
+ * DHeap::Map methods
+ *
+ ********************************************************************/
+
+#ifdef DHEAP_MAP
+
+/*
+ * Retrieves the score that has been assigned to a heap member.
+ *
+ * Time complexity: <b>O(1)</b>
+ *
+ * @param object [Object] an object to lookup
+ * @return [Float,Integer,nil] the score associated with the object,
+ *                             or nil if the object isn't a member
+ */
+static VALUE
+dheapmap_aref(VALUE self, VALUE object)
+{
+    dheap_t *heap   = get_dheap_struct(self);
+    VALUE    idxval = rb_hash_lookup2(heap->indexes, object, Qfalse);
+    if (idxval) {
+        size_t index = NUM2ULONG(idxval);
+        return SCORE2NUM(DHEAP_SCORE(heap, index));
+    }
+    return Qnil;
+}
+
+/*
+ * Assign a score to an object, adding it to the heap or updating as necessary.
+ *
+ * Time complexity: <b>O(log n)</b> (score decrease will be faster than
+ * score increase)
+ *
+ * @param object [Object] an object to lookup
+ * @param score [Integer,#to_f] the score to set
+ * @return [Float,Integer] the score
+ */
+static VALUE
+dheapmap_aset(VALUE self, VALUE object, VALUE score)
+{
+    dheapmap_insert(self, score, object);
+    return score;
+}
+
+#endif
+
+/********************************************************************
+ *
+ * DHeap setup
+ *
+ ********************************************************************/
+
 void
 Init_d_heap(void)
 {
-    id_cmp = rb_intern_const("<=>");
-    id_ivar_values = rb_intern_const("values");
-    id_ivar_scores = rb_intern_const("scores");
-    id_ivar_d = rb_intern_const("d");
+    VALUE rb_cDHeap = rb_define_class("DHeap", rb_cObject);
+#ifdef DHEAP_MAP
+    VALUE rb_cDHeapMap = rb_define_class_under(rb_cDHeap, "Map", rb_cDHeap);
+#endif
+
+    id_cmp    = rb_intern_const("<=>");
+    id_abs    = rb_intern_const("abs");
+    id_lshift = rb_intern_const("<<");
+    id_uminus = rb_intern_const("-@");
 
-    rb_cDHeap = rb_define_class("DHeap", rb_cObject);
     rb_define_alloc_func(rb_cDHeap, dheap_s_alloc);
 
+#ifdef DHEAP_MAP
+#    define def_override_inherited(rb_name, c_name, argc)                      \
+        rb_define_method(rb_cDHeap, rb_name, dheap_##c_name, argc);            \
+        rb_define_method(rb_cDHeapMap, rb_name, dheapmap_##c_name, argc);
+#else
+#    define def_override_inherited(rb_name, c_name, argc)                      \
+        rb_define_method(rb_cDHeap, rb_name, dheap_##c_name, argc);
+#endif
+
+    /*
+     * This is based on INT_MAX. But it is very very unlikely you will want a
+     * large value for d.  The tradeoff is that higher d values give faster push
+     * and slower pop.  If you expect pushes and pops to be balanced, then just
+     * stick with the default.  If you expect more pushes than pops, it might be
+     * worthwhile to increase d.
+     */
     rb_define_const(rb_cDHeap, "MAX_D", INT2NUM(DHEAP_MAX_D));
+
+    /*
+     * d=4 uses the fewest comparisons for (worst case) insert + delete-min.
+     */
     rb_define_const(rb_cDHeap, "DEFAULT_D", INT2NUM(DHEAP_DEFAULT_D));
 
-    rb_define_method(rb_cDHeap, "initialize", dheap_initialize, -1);
-    rb_define_method(rb_cDHeap, "d", dheap_attr_d, 0);
-    rb_define_method(rb_cDHeap, "freeze", dheap_freeze, 0);
+    /*
+     * The default heap capacity.  The heap grows automatically as necessary, so
+     * you shouldn't need to worry about this.
+     */
+    rb_define_const(rb_cDHeap, "DEFAULT_CAPA", INT2NUM(DHEAP_DEFAULT_CAPA));
+
+    rb_define_private_method(rb_cDHeap, "__init_without_kw__", dheap_init, 3);
+    rb_define_method(rb_cDHeap, "initialize_copy", dheap_initialize_copy, 1);
 
+    rb_define_method(rb_cDHeap, "d", dheap_attr_d, 0);
     rb_define_method(rb_cDHeap, "size", dheap_size, 0);
     rb_define_method(rb_cDHeap, "empty?", dheap_empty_p, 0);
-
-    rb_define_method(rb_cDHeap, "peek",    dheap_peek, 0);
-    rb_define_method(rb_cDHeap, "push",    dheap_push, -1);
-    rb_define_method(rb_cDHeap, "<<",      dheap_left_shift, 1);
-    rb_define_method(rb_cDHeap, "pop",     dheap_pop, 0);
-    rb_define_method(rb_cDHeap, "pop_lt",  dheap_pop_lt, 1);
-    rb_define_method(rb_cDHeap, "pop_lte", dheap_pop_lte, 1);
+    rb_define_method(rb_cDHeap, "to_a", dheap_to_a, 0);
+
+    rb_define_method(rb_cDHeap, "clear", dheap_clear, 0);
+    rb_define_method(rb_cDHeap, "peek", dheap_peek, 0);
+    rb_define_method(rb_cDHeap, "peek_score", dheap_peek_score, 0);
+    rb_define_method(rb_cDHeap, "peek_with_score", dheap_peek_with_score, 0);
+    rb_define_method(rb_cDHeap, "pop_all_below", dheap_pop_all_below, -1);
+
+    def_override_inherited("insert", insert, 2);
+    def_override_inherited("push", push, -1);
+    def_override_inherited("<<", lshift, 1);
+
+    def_override_inherited("pop", pop, 0);
+    def_override_inherited("pop_lt", pop_lt, 1);
+    def_override_inherited("pop_lte", pop_lte, 1);
+    def_override_inherited("pop_with_score", pop_with_score, 0);
+
+#ifdef DHEAP_MAP
+    rb_define_method(rb_cDHeapMap, "[]", dheapmap_aref, 1);
+    rb_define_method(rb_cDHeapMap, "[]=", dheapmap_aset, 2);
+#endif
 }