d_heap 0.5.0 → 0.6.0

data/benchmarks/push_n.yml

@@ -5,27 +5,31 @@ prelude: |
   include DHeap::Benchmarks
   fill_random_vals
 
-  n = ENV.fetch("BENCH_N", 1000).to_i
+  N = ENV.fetch("BENCH_N", 1000).to_i
 
 benchmark:
   - script: &script |
-       q.clear
-       i = 0
-       while i < n
-         q << random_val
-         i += 1
+       if __bmdv_i % N == 0
+         q.clear
        end
+
+       q << random_val
     name:    "push N (findmin)"
     prelude: "q = initq FindMin"
+    loop_count: 24000000
   - script: *script
     name:    "push N (bsearch)"
     prelude: "q = initq BSearch"
+    loop_count:  2300000
   - script: *script
     name:    "push N (rb_heap)"
     prelude: "q = initq RbHeap"
+    loop_count:  9800000
   - script: *script
     name:    "push N (c++ stl)"
     prelude: "q = initq CppSTL"
+    loop_count: 18700000
   - script: *script
     name:    "push N (c_dheap)"
     prelude: "q = initq DHeap"
+    loop_count: 25100000

data/benchmarks/push_n_pop_n.yml

@@ -5,31 +5,48 @@ prelude: |
   include DHeap::Benchmarks
   fill_random_vals
 
-  n = ENV.fetch("BENCH_N", 1000).to_i
+  N = ENV.fetch("BENCH_N", 1000).to_i
+  N2 = N * 2
 
-  i = 0
+  i = j = 0
 
 benchmark:
   - script: &script |
-       while i < n
-         q << random_val
-         i += 1
-       end
-       while 0 < i
-         q.pop
-         i -= 1
-       end
+      if i < N
+        q.clear if __bmdv_i == 0
+        q << random_val
+        i += 1
+
+      elsif j < N
+        q.pop
+        j += 1
+
+      elsif q.empty?
+        i = 1
+        j = 0
+        q.clear
+        q << random_val
+
+      else
+        raise "q not empty!"
+      end
+
     name:    "push N + pop N (findmin)"
     prelude: "q = initq FindMin"
+    loop_count:   200000
   - script: *script
     name:    "push N + pop N (bsearch)"
     prelude: "q = initq BSearch"
+    loop_count:  4000000
   - script: *script
     name:    "push N + pop N (rb_heap)"
     prelude: "q = initq RbHeap"
+    loop_count:  4000000
   - script: *script
     name:    "push N + pop N (c++ stl)"
     prelude: "q = initq CppSTL"
+    loop_count: 16000000
   - script: *script
     name:    "push N + pop N (c_dheap)"
     prelude: "q = initq DHeap"
+    loop_count: 16000000

data/benchmarks/push_pop.yml

@@ -13,15 +13,20 @@ benchmark:
        q.pop
     name:    "push + pop (findmin)"
     prelude: "q = FindMin.new(n) { random_val }"
+    loop_count:   250000
   - script: *script
     name:    "push + pop (bsearch)"
     prelude: "q = BSearch.new(n) { random_val }"
+    loop_count:  5000000
   - script: *script
     name:    "push + pop (rb_heap)"
     prelude: "q = RbHeap.new(n) { random_val }"
+    loop_count:  2000000
   - script: *script
     name:    "push + pop (c++ stl)"
     prelude: "q = initq CppSTL, n"
+    loop_count: 13000000
   - script: *script
     name:    "push + pop (c_dheap)"
     prelude: "q = initq DHeap, n"
+    loop_count: 20000000

data/bin/bench_charts

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -eu
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" > /dev/null; pwd -P)
+PROJECT_DIR=$(cd "$SCRIPT_DIR" > /dev/null; cd .. > /dev/null; pwd -P)
+cd "$PROJECT_DIR"
+
+opts=( --bundle -e 'N 100000;N 10000;N 1000;N 100;N 10' -o gruff )
+
+for bm in push_n push_n_pop_n push_pop; do
+  bin/benchmark-driver "${opts[@]}" "benchmarks/${bm}.yml"
+  mv graph.png "images/${bm}.png"
+done
+

data/d_heap.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   DESC
   spec.homepage      = "https://github.com/nevans/#{spec.name}"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

data/ext/d_heap/d_heap.c

@@ -1,36 +1,96 @@
 #include <float.h>
-#include "d_heap.h"
+#include <math.h>
+#include "ruby.h"
 
-ID id_cmp; // <=>
-ID id_abs; // abs
+/********************************************************************
+ *
+ * Type definitions
+ *
+ ********************************************************************/
+
+typedef struct dheap_struct dheap_t;
+typedef struct dheap_entry ENTRY;
+
+// TODO: convert SCORE to a union, and use an ENTRY flag for its type
+typedef long double SCORE;
 
-typedef struct dheap_struct {
+#if LDBL_MANT_DIG < SIZEOF_UNSIGNED_LONG_LONG * 8
+#error 'unsigned long long' must fit into 'long double' mantissa
+#endif
+
+// TODO: test this code on a 32 bit system (it MUST have some bugs!)
+#if SIZEOF_UNSIGNED_LONG_LONG * 8 != 64
+#error 'unsigned long long' must be 64bits
+#endif
+
+/********************************************************************
+ *
+ * Struct definitions
+ *
+ ********************************************************************/
+
+struct dheap_struct {
     int d;
     long size;
     long capa;
     ENTRY *entries;
-} dheap_t;
+};
 
-#define DHEAP_SCORE(heap, idx) ((heap)->entries[idx].score)
-#define DHEAP_VALUE(heap, idx) ((heap)->entries[idx].value)
-#define DHEAP_IDX_LAST(heap) (DHEAP_SIZE((heap)) - 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)
+struct dheap_entry {
+    SCORE score;
+    VALUE value;
+};
 
-#define DHEAP_SIZE(heap) ((heap)->size)
+/********************************************************************
+ *
+ * Constant definitions
+ *
+ ********************************************************************/
 
-#define CMP_LT(a, b)  ((a) <  (b))
-#define CMP_LTE(a, b) ((a) <= (b))
-#define CMP_GT(a, b)  ((a) >  (b))
-#define CMP_GTE(a, b) ((a) >= (b))
+#define DHEAP_DEFAULT_D 4
+#define DHEAP_MAX_D INT_MAX
 
-#if LDBL_MANT_DIG < SIZEOF_UNSIGNED_LONG_LONG * 8
-#error 'unsigned long long' should fit into 'long double' mantissa
-#endif
+// sizeof(ENTRY) => 32 bytes
+// one kilobyte = 32 * 32 bytes
+#define DHEAP_DEFAULT_CAPA 32
+#define DHEAP_MAX_CAPA (LONG_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_unary_minus; // -@
+static const ENTRY EmptyDheapEntry; // 0 value for safety overwrite after pop
+static const rb_data_type_t dheap_data_type;
+
+/********************************************************************
+ *
+ * SCORE: casting to and from VALUE
+ *    adapted from similar methods in ruby's object.c
+ *
+ ********************************************************************/
+
+// ruby doesn't have a LDBL2NUM. :(
+// So this only accomplishes a subset of what that ought to do.
+static inline VALUE
+SCORE2NUM(SCORE s)
+{
+    if (floorl((long double) s) == s) {
+        if (s < 0) {
+            unsigned long long ull = (unsigned long long)(-s);
+            return rb_funcall(ULL2NUM(ull), id_unary_minus, 0, Qundef);
+        }
+        return ULL2NUM((unsigned long long)(s));
+    }
+    return rb_float_new((double)(s));
+}
+
+static inline SCORE
+FIX2SCORE(VALUE x)
+{
+    return (long double)FIX2LONG(x);
+}
 
-// copied and modified from ruby's object.c
-#define FIX2SCORE(x) (long double)FIX2LONG(x)
 // We could translate a much wider range of values to long double by
 // implementing a new `rb_big2ldbl(x)` function. But requires reaching into
 // T_BIGNUM internals.
@@ -43,18 +103,27 @@ BIG2SCORE(VALUE x)
     } else {
         unsigned long long ull;
         long double ldbl;
-        x = rb_funcall(x, id_abs, 0);
+        x = rb_funcall(x, id_abs, 0, Qundef);
         ull  = rb_big2ull(x);
         ldbl = (long double) ull;
         return -ldbl;
     }
 }
-#define INT2SCORE(x) \
-    (FIXNUM_P(x) ? FIX2SCORE(x) : BIG2SCORE(x))
-#define NUM2SCORE(x)                                                     \
-    (FIXNUM_P(x) ? FIX2SCORE(x) :                                        \
-     RB_TYPE_P(x, T_BIGNUM) ? BIG2SCORE(x) :                             \
-     (Check_Type(x, T_FLOAT), (long double)RFLOAT_VALUE(x)))
+
+static inline SCORE
+INT2SCORE(VALUE x)
+{
+    return (FIXNUM_P(x) ? FIX2SCORE(x) : BIG2SCORE(x));
+}
+
+static inline SCORE
+NUM2SCORE(VALUE x)
+{
+    return (FIXNUM_P(x) ? FIX2SCORE(x) :
+            RB_TYPE_P(x, T_BIGNUM) ? BIG2SCORE(x) :
+            (Check_Type(x, T_FLOAT), (long double)RFLOAT_VALUE(x)));
+}
+
 static inline long double
 RAT2SCORE(VALUE x)
 {
@@ -73,14 +142,13 @@ RAT2SCORE(VALUE x)
  * * reduced to long double (should be 80 or 128 bit) if it is Rational
  * * reduced to double precision if the value is convertable by Float(x)
  */
-static inline long double
+static inline SCORE
 VAL2SCORE(VALUE score)
 {
     // assert that long double can hold 'unsigned long long':
     // static_assert(sizeof(unsigned long long) * 8 <= LDBL_MANT_DIG);
     // assert that long double can hold T_FLOAT
     // static_assert(sizeof(double) <= sizeof(long double));
-
     switch (TYPE(score)) {
         case T_FIXNUM:
             return FIX2SCORE(score);
@@ -93,59 +161,37 @@ VAL2SCORE(VALUE score)
     }
 }
 
-#ifdef ORIG_SCORE_CMP_CODE
-
-#define VAL2SCORE(score) (score)
-
-#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)
-
-// from internal/compar.h
-#define STRING_P(s) (RB_TYPE_P((s), T_STRING) && CLASS_OF(s) == rb_cString)
-/*
- * 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(SCORE a, SCORE 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);
+ * DHeap ENTRY accessors
+ *
+ ********************************************************************/
+
+#define DHEAP_SCORE(heap, idx) ((heap)->entries[idx].score)
+#define DHEAP_VALUE(heap, idx) ((heap)->entries[idx].value)
 
-    // give up on an optimized version and just call (a <=> b)
-    return rb_cmpint(rb_funcallv(a, id_cmp, 1, &b), a, b);
+static inline VALUE
+DHEAP_ENTRY_ARY(dheap_t *heap, long idx)
+{
+    if (idx < 0 || heap->size <= idx) { return Qnil; }
+    return rb_ary_new_from_args(2,
+            DHEAP_VALUE(heap, 0),
+            SCORE2NUM(DHEAP_SCORE(heap, 0)));
 }
 
-#endif
+/********************************************************************
+ *
+ * DHeap index math
+ *
+ ********************************************************************/
 
-#define DHEAP_Check_d_size(d) do {                            \
-    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); \
-    }                                                         \
-} while (0)
+#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 __D_HEAP_DEBUG
-#define ASSERT_DHEAP_INDEX(heap, index) do {                           \
+#define ASSERT_DHEAP_IDX_OK(heap, index) do {                          \
     if (index < 0) {                                                  \
         rb_raise(rb_eIndexError, "DHeap index %ld too small", index); \
     }                                                                 \
@@ -154,18 +200,28 @@ optimized_cmp(SCORE a, SCORE b) {
     }                                                                 \
 } while (0)
 #else
-#define ASSERT_DHEAP_INDEX(heap, index)
+#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;
     for (long i = 0; i < heap->size; ++i) {
         if (DHEAP_VALUE(heap, i))
-            dheap_gc_location(DHEAP_VALUE(heap, i));
+            rb_gc_location(DHEAP_VALUE(heap, i));
     }
 }
+#else
+#define rb_gc_mark_movable(x) rb_gc_mark(x)
+#endif
 
 static void
 dheap_mark(void *ptr)
@@ -200,25 +256,88 @@ dheap_memsize(const void *ptr)
     return size;
 }
 
+
 static const rb_data_type_t dheap_data_type = {
     "DHeap",
     {
         (void (*)(void*))dheap_mark,
         (void (*)(void*))dheap_free,
         (size_t (*)(const void *))dheap_memsize,
-        dheap_compact_callback(dheap_compact),
+#ifdef HAVE_RB_GC_MARK_MOVABLE
+        (void (*)(void*))dheap_compact, {0}
+#else
+        {0}
+#endif
     },
     0, 0,
     RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
+/********************************************************************
+ *
+ * DHeap comparisons
+ * TODO: bring back comparisons for score types other than `long double`.
+ *
+ ********************************************************************/
+
+#define CMP_LT(a, b)  ((a) <  (b))
+#define CMP_LTE(a, b) ((a) <= (b))
+
+/* #ifdef ORIG_SCORE_CMP_CODE */
+
+/* #define CMP_LT(a, b)  (optimized_cmp(a, b) <  0) */
+/* #define CMP_LTE(a, b) (optimized_cmp(a, b) <= 0) */
+
+/* // from internal/compar.h */
+/* #define STRING_P(s) (RB_TYPE_P((s), T_STRING) && CLASS_OF(s) == rb_cString) */
+/*
+ * 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(SCORE a, SCORE 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); */
+
+/*     // give up on an optimized version and just call (a <=> b) */
+/*     return rb_cmpint(rb_funcallv(a, id_cmp, 1, &b), a, b); */
+/* } */
+
+/* #endif */
+
+/********************************************************************
+ *
+ * DHeap allocation and initialization and resizing
+ *
+ ********************************************************************/
+
 static VALUE
 dheap_s_alloc(VALUE klass)
 {
     VALUE obj;
     dheap_t *heap;
 
+// TypedData_Make_Struct uses a non-std "statement expression"
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpedantic"
     obj = TypedData_Make_Struct(klass, dheap_t, &dheap_data_type, heap);
+#pragma GCC diagnostic pop
     heap->d = DHEAP_DEFAULT_D;
 
     heap->size = 0;
@@ -257,7 +376,7 @@ dheap_ensure_room_for_push(dheap_t *heap, long incr_by)
     long new_size = heap->size + incr_by;
 
     // check for overflow of new_size
-    if (DHEAP_MAX_SIZE - incr_by < heap->size)
+    if (DHEAP_MAX_CAPA - incr_by < heap->size)
         rb_raise(rb_eIndexError, "index %ld too big", new_size);
 
     // if it existing capacity is too small
@@ -267,7 +386,7 @@ dheap_ensure_room_for_push(dheap_t *heap, long incr_by)
         if (DHEAP_CAPA_INCR_MAX < new_size)
             new_size = new_size + DHEAP_CAPA_INCR_MAX;
         // check for overflow of new_capa
-        if (DHEAP_MAX_SIZE / 2 < new_size) new_capa = DHEAP_MAX_SIZE;
+        if (DHEAP_MAX_CAPA / 2 < new_size) new_capa = DHEAP_MAX_CAPA;
         // cap max incr_by
         if (heap->capa + DHEAP_CAPA_INCR_MAX < new_capa)
             new_capa = heap->capa + DHEAP_CAPA_INCR_MAX;
@@ -276,25 +395,38 @@ dheap_ensure_room_for_push(dheap_t *heap, long incr_by)
     }
 }
 
-/*
- * @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) {
-    dheap_t *heap;
-    int d;
+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;
+}
 
-    rb_check_arity(argc, 0, 1);
-    TypedData_Get_Struct(self, dheap_t, &dheap_data_type, heap);
+static inline long
+dheap_value_to_long_capa(VALUE num)
+{
+    long capa = NUM2LONG(num);
+    if (capa < 1) {
+        rb_raise(rb_eArgError, "DHeap capa=%lu must be positive", capa);
+    }
+    return capa;
+}
 
-    d = argc ? NUM2INT(argv[0]) : DHEAP_DEFAULT_D;
-    DHEAP_Check_d_size(d);
-    heap->d = d;
+static VALUE
+dheap_initialize(VALUE self, VALUE d, VALUE capa) {
+    dheap_t *heap = get_dheap_struct(self);
+
+    if(heap->entries || heap->size || heap->capa)
+        rb_raise(rb_eScriptError, "DHeap already initialized.");
 
-    dheap_set_capa(heap, DHEAP_DEFAULT_SIZE);
+    heap->d = dheap_value_to_int_d(d);
+    dheap_set_capa(heap, dheap_value_to_long_capa(capa));
 
     return self;
 }
@@ -319,11 +451,17 @@ dheap_initialize_copy(VALUE copy, VALUE orig)
     return copy;
 }
 
+/********************************************************************
+ *
+ * DHeap sift up/down
+ *
+ ********************************************************************/
+
 VALUE
 dheap_sift_up(dheap_t *heap, long index) {
     ENTRY entry = heap->entries[index];
 
-    ASSERT_DHEAP_INDEX(heap, index);
+    ASSERT_DHEAP_IDX_OK(heap, index);
 
     // sift it up to where it belongs
     for (long parent_index; 0 < index; index = parent_index) {
@@ -370,7 +508,7 @@ dheap_sift_down(dheap_t *heap, long index, long last_index) {
 
         long last_parent = DHEAP_IDX_PARENT(heap, last_index);
 
-        ASSERT_DHEAP_INDEX(heap, index);
+        ASSERT_DHEAP_IDX_OK(heap, index);
 
         // iteratively sift it down to where it belongs
         while (index <= last_parent) {
@@ -389,6 +527,12 @@ dheap_sift_down(dheap_t *heap, long index, long last_index) {
     }
 }
 
+/********************************************************************
+ *
+ * DHeap attributes
+ *
+ ********************************************************************/
+
 /*
  * @return [Integer] the number of elements in the heap
  */
@@ -396,8 +540,7 @@ static VALUE
 dheap_size(VALUE self)
 {
     dheap_t *heap = get_dheap_struct(self);
-    long size = DHEAP_SIZE(heap);
-    return LONG2NUM(size);
+    return LONG2NUM(heap->size);
 }
 
 /*
@@ -407,8 +550,7 @@ 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 heap->size ? Qfalse : Qtrue;
 }
 
 /*
@@ -421,16 +563,11 @@ dheap_attr_d(VALUE self)
     return INT2FIX(heap->d);
 }
 
-/* @!visibility private */
-static VALUE
-dheap_init_clone(VALUE clone, VALUE orig, VALUE kwfreeze)
-{
-    dheap_initialize_copy(clone, orig);
-    if (RTEST(kwfreeze) || (kwfreeze == Qnil && OBJ_FROZEN(orig))) {
-        rb_funcall(clone, rb_intern("freeze"), 0);
-    }
-    return clone;
-}
+/********************************************************************
+ *
+ * DHeap push
+ *
+ ********************************************************************/
 
 static inline void
 dheap_push_entry(dheap_t *heap, ENTRY *entry) {
@@ -520,47 +657,77 @@ dheap_left_shift(VALUE self, VALUE value) {
     return self;
 }
 
-static const ENTRY EmptyDheapEntry;
+/********************************************************************
+ *
+ * DHeap pop and peek
+ *
+ ********************************************************************/
 
-static inline VALUE
-dheap_pop0(dheap_t *heap)
+static inline void
+dheap_del0(dheap_t *heap)
 {
-    VALUE popped = DHEAP_VALUE(heap, 0);
     if (0 < --heap->size) {
         heap->entries[0] = heap->entries[heap->size];
         heap->entries[heap->size] = EmptyDheapEntry; // unnecessary to zero?
         dheap_sift_down(heap, 0, heap->size - 1);
     }
+}
+
+static inline VALUE
+dheap_pop0(dheap_t *heap)
+{
+    VALUE popped = DHEAP_VALUE(heap, 0);
+    dheap_del0(heap);
     return popped;
 }
 
 /*
- * Clears all values from the heap, leaving it empty.
+ * Returns the next value on the heap, and its score, without popping it
  *
- * @return [self]
+ * 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_clear(VALUE self) {
+dheap_peek_with_score(VALUE self)
+{
     dheap_t *heap = get_dheap_struct(self);
-    rb_check_frozen(self);
-    if (0 < DHEAP_SIZE(heap)) {
-        heap->size = 0;
-    }
-    return self;
+    return DHEAP_ENTRY_ARY(heap, 0);
+}
+
+/*
+ * 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)
+{
+    dheap_t *heap = get_dheap_struct(self);
+    if (DHEAP_IDX_LAST(heap) < 0) return Qnil;
+    return SCORE2NUM(DHEAP_SCORE(heap, 0));
 }
 
 /*
  * 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_t *heap = get_dheap_struct(self);
-    if (DHEAP_IDX_LAST(heap) < 0) return Qnil;
-    return DHEAP_VALUE(heap, 0);
+    return heap->size ? DHEAP_VALUE(heap, 0) : Qnil;
 }
 
 /*
@@ -573,14 +740,34 @@ dheap_peek(VALUE self)
  * @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);
     rb_check_frozen(self);
-    if (DHEAP_SIZE(heap) <= 0) return Qnil;
-    return dheap_pop0(heap);
+    return heap->size ? dheap_pop0(heap) : Qnil;
+}
+
+/*
+ * 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>
+ *
+ * @return [nil,Array<(Object, Numeric)>] the next value and its score
+ *
+ * @see #pop
+ * @see #peek_with_score
+ */
+static VALUE
+dheap_pop_with_score(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct(self);
+    VALUE ary = DHEAP_ENTRY_ARY(heap, 0);
+    rb_check_frozen(self);
+    if (ary != Qnil) { dheap_pop0(heap); }
+    return ary;
 }
 
 /*
@@ -595,13 +782,14 @@ dheap_pop(VALUE self)
  * @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(self);
     rb_check_frozen(self);
-    if (DHEAP_SIZE(heap) <= 0) return Qnil;
+    if (heap->size <= 0) return Qnil;
     if (!CMP_LTE(DHEAP_SCORE(heap, 0), VAL2SCORE(max_score))) return Qnil;
     return dheap_pop0(heap);
 }
@@ -618,32 +806,132 @@ dheap_pop_lte(VALUE self, VALUE max_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);
     rb_check_frozen(self);
-    if (DHEAP_SIZE(heap) <= 0) return Qnil;
+    if (heap->size <= 0) return Qnil;
     if (!CMP_LT(DHEAP_SCORE(heap, 0), VAL2SCORE(max_score))) return Qnil;
     return dheap_pop0(heap);
 }
 
+#define DHEAP_PEEK_LT_P(heap, max_score) \
+    (heap->size && CMP_LT(DHEAP_SCORE(heap, 0), max_score))
+
+static VALUE
+dheap_pop_all_below0(dheap_t *heap, SCORE max_score, VALUE array)
+{
+    if (!RTEST(array)) { array = rb_ary_new(); }
+    if (RB_TYPE_P(array, T_ARRAY)) {
+        while (DHEAP_PEEK_LT_P(heap, max_score)) {
+            rb_ary_push(array, dheap_pop0(heap));
+        }
+    } else {
+        while (DHEAP_PEEK_LT_P(heap, max_score)) {
+            rb_funcall(array, id_lshift, 1, dheap_pop0(heap));
+        }
+    }
+    return array;
+}
+
+/*
+ * @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(self);
+    SCORE max_score;
+    VALUE array;
+    rb_check_frozen(self);
+    rb_check_arity(argc, 1, 2);
+    max_score = VAL2SCORE(argv[0]);
+    if (argc == 1) {
+        array = rb_ary_new();
+    } else {
+        array = argv[1];
+    }
+    return dheap_pop_all_below0(heap, max_score, array);
+}
+
+/********************************************************************
+ *
+ * DHeap, misc methods
+ *
+ ********************************************************************/
+
+/*
+ * Clears all values from the heap, leaving it empty.
+ *
+ * @return [self]
+ */
+static VALUE
+dheap_clear(VALUE self)
+{
+    dheap_t *heap = get_dheap_struct(self);
+    rb_check_frozen(self);
+    if (0 < heap->size) {
+        heap->size = 0;
+    }
+    return self;
+}
+
+/********************************************************************
+ *
+ * DHeap setup
+ *
+ ********************************************************************/
+
 void
 Init_d_heap(void)
 {
+    VALUE rb_cDHeap = rb_define_class("DHeap", rb_cObject);
+
     id_cmp = rb_intern_const("<=>");
     id_abs = rb_intern_const("abs");
+    id_lshift = rb_intern_const("<<");
+    id_unary_minus = rb_intern_const("-@");
 
-    rb_cDHeap = rb_define_class("DHeap", rb_cObject);
     rb_define_alloc_func(rb_cDHeap, dheap_s_alloc);
 
-    rb_define_const(rb_cDHeap, "MAX_D",     INT2NUM(DHEAP_MAX_D));
-    rb_define_const(rb_cDHeap, "DEFAULT_D", INT2NUM(DHEAP_DEFAULT_D));
-
-    rb_define_method(rb_cDHeap, "initialize", dheap_initialize, -1);
+    /*
+     * 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));
+
+    /*
+     * 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_initialize, 2);
     rb_define_method(rb_cDHeap, "initialize_copy", dheap_initialize_copy, 1);
-    rb_define_private_method(rb_cDHeap, "__init_clone__", dheap_init_clone, 2);
 
     rb_define_method(rb_cDHeap, "d",       dheap_attr_d, 0);
     rb_define_method(rb_cDHeap, "size",    dheap_size, 0);
@@ -655,6 +943,13 @@ Init_d_heap(void)
     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, "pop_lt",        dheap_pop_lt, 1);
+    rb_define_method(rb_cDHeap, "pop_lte",       dheap_pop_lte, 1);
+    rb_define_method(rb_cDHeap, "pop_all_below", dheap_pop_all_below, -1);
+
+    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_with_score",  dheap_pop_with_score, 0);
+
 }