d_heap 0.2.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89808cd668688e16b5dd1e7e6b1ce9e57651217089b0686b4aeb83d41c565020
-  data.tar.gz: 43e11d72c7143061d0b424f8290e4ef7f66dfaedc8df2f5eff11e20cce2f7796
+  metadata.gz: 35213e5ac430b07cf2b43a7f065ff5c409506022835a5326cb2bfa25daa7f210
+  data.tar.gz: e87a64fb9fd6eb8bdd281d8fe289b7f4993f4bde9a671b0b414aca194b724691
 SHA512:
-  metadata.gz: 7ce7b4a755692a99fdee3d30e27f7dd02f6f90c12fe478a5d20f5e224183f82c5d7f82141c80d229edee48a1dcf6a90878c5648b3bb2107d093dcef5884abf59
-  data.tar.gz: 03daf597a17aee15f67f2bf3aa37625e84c9d2f759c22313a9e1010b9f3878c1e8d2dc005b0f82fca5f1792ee57abf7f93d3ab176edad5e29686ca7dedaae905
+  metadata.gz: 77518eb11bf8dd5fa8a29ad88f48c30650ff375ae9b74001fa59d30f634feddf5c4f3ef8d791dc4064afc1d9d68b9b463eaf0e778e927655e0da0c0a9da6fdee
+  data.tar.gz: 2911b20a882d8b6f577bda9a388a9a755a093cfd3c1aaaaa355aa5be97ffe506935620043adb115158565ead6941e52f789cdd714e4932aff4916412c60a3aee

data/.github/workflows/main.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.4, 2.5, 2.6, 2.7, 3.0]
+        os: [ubuntu, macos]
+        experimental: [false]
+    runs-on: ${{ matrix.os }}-latest
+    continue-on-error: ${{ matrix.experimental }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: |
+        gem install bundler -v 2.2.3
+        bundle install
+        bundle exec rake

data/.gitignore

@@ -10,6 +10,7 @@
 *.so
 *.o
 *.a
+compile_commands.json
 mkmf.log
 
 # rspec failure tracking

data/.rubocop.yml

@@ -0,0 +1,199 @@
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 2.4
+  NewCops: disable
+  Exclude:
+    - bin/benchmark-driver
+    - bin/rake
+    - bin/rspec
+    - bin/rubocop
+
+###########################################################################
+# rubocop defaults are simply WRONG about many rules... Sorry. It's true.
+
+###########################################################################
+# Layout: Alignment.  I want these to work, I really do...
+
+# I wish this worked with "table". but that goes wrong sometimes.
+Layout/HashAlignment: { Enabled: false }
+
+# This needs to be configurable so parenthesis calls are aligned with first
+# parameter, and non-parenthesis calls are aligned with fixed indentation.
+Layout/ParameterAlignment: { Enabled: false }
+
+###########################################################################
+# Layout: Empty lines
+
+Layout/EmptyLineAfterGuardClause:                 { Enabled: false }
+Layout/EmptyLineAfterMagicComment:                { Enabled: true }
+Layout/EmptyLineAfterMultilineCondition:          { Enabled: false }
+Layout/EmptyLines:                                { Enabled: true }
+Layout/EmptyLinesAroundAccessModifier:            { Enabled: true }
+Layout/EmptyLinesAroundArguments:                 { Enabled: true }
+Layout/EmptyLinesAroundBeginBody:                 { Enabled: true }
+Layout/EmptyLinesAroundBlockBody:                 { Enabled: false }
+Layout/EmptyLinesAroundExceptionHandlingKeywords: { Enabled: true }
+Layout/EmptyLinesAroundMethodBody:                { Enabled: true }
+
+Layout/EmptyLineBetweenDefs:
+  Enabled: true
+  AllowAdjacentOneLineDefs: true
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  inherit_mode:
+    merge:
+      - Exclude
+      - AllowedMethods
+  Enabled: true
+  AllowedMethods:
+    - delegate
+    - def_delegator
+    - def_delegators
+    - def_instance_delegators
+
+# "empty_lines_special" sometimes does the wrong thing and annoys me.
+# But I've mostly learned to live with it... mostly. 🙁
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: true
+  EnforcedStyle: empty_lines_special
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: true
+  EnforcedStyle: empty_lines_special
+
+###########################################################################
+# Layout: Space around, before, inside, etc
+
+Layout/SpaceAroundEqualsInParameterDefault: { Enabled: false }
+Layout/SpaceBeforeBlockBraces:              { Enabled: false }
+Layout/SpaceBeforeFirstArg:                 { Enabled: false }
+Layout/SpaceInLambdaLiteral:                { Enabled: false }
+Layout/SpaceInsideArrayLiteralBrackets:     { Enabled: false }
+Layout/SpaceInsideHashLiteralBraces:        { Enabled: false }
+
+Layout/SpaceInsideBlockBraces:
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: space
+  SpaceBeforeBlockParameters: false
+
+# I would enable this if it were a bit better at handling alignment.
+Layout/ExtraSpacing:
+  Enabled: false
+  AllowForAlignment: true
+  AllowBeforeTrailingComments: true
+
+###########################################################################
+# Layout: Misc
+
+Layout/LineLength:
+  Max: 90 # should stay under 80, but we'll allow a little wiggle-room
+
+Layout/MultilineOperationIndentation: { Enabled: false }
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+###########################################################################
+# Lint and Naming: rubocop defaults are mostly good, but...
+
+Lint/UnusedMethodArgument: { Enabled: false }
+Naming/BinaryOperatorParameterName: { Enabled: false } # def /(denominator)
+Naming/RescuedExceptionsVariableName: { Enabled: false }
+
+###########################################################################
+# Matrics:
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+# Although it may be better to split specs into multiple files...?
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*_spec.rb"
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/ClassLength:
+  Max: 200
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+###########################################################################
+# Style...
+
+Style/AccessorGrouping:        { Enabled: false }
+Style/AsciiComments:           { Enabled: false } # 👮 can't stop our 🎉🥳🎊🥳!
+Style/ClassAndModuleChildren:  { Enabled: false }
+Style/EachWithObject:          { Enabled: false }
+Style/FormatStringToken:       { Enabled: false }
+Style/FloatDivision:           { Enabled: false }
+Style/IfUnlessModifier:        { Enabled: false }
+Style/IfWithSemicolon:         { Enabled: false }
+Style/Lambda:                  { Enabled: false }
+Style/LineEndConcatenation:    { Enabled: false }
+Style/MixinGrouping:           { Enabled: false }
+Style/MultilineBlockChain:     { Enabled: false }
+Style/PerlBackrefs:            { Enabled: false } # use occasionally/sparingly
+Style/RescueStandardError:     { Enabled: false }
+Style/Semicolon:               { Enabled: false }
+Style/SingleLineMethods:       { Enabled: false }
+Style/StabbyLambdaParentheses: { Enabled: false }
+Style/WhenThen               : { Enabled: false }
+
+# I require trailing commas elsewhere, but these are optional
+Style/TrailingCommaInArguments: { Enabled: false }
+
+# If rubocop had an option to only enforce this on constants and literals (e.g.
+# strings, regexp, range), I'd agree.
+#
+# But if you are using it e.g. on method arguments of unknown type, in the same
+# style that ruby uses it with grep, then you are doing exactly the right thing.
+Style/CaseEquality: { Enabled: false }
+
+# I'd enable if "require_parentheses_when_complex" considered unary '!' simple.
+Style/TernaryParentheses:
+  EnforcedStyle: require_parentheses_when_complex
+  Enabled: false
+
+Style/BlockDelimiters:
+  inherit_mode:
+    merge:
+      - Exclude
+      - ProceduralMethods
+      - IgnoredMethods
+      - FunctionalMethods
+  EnforcedStyle: semantic
+  AllowBracesOnProceduralOneLiners: true
+  IgnoredMethods:
+    - expect  # rspec
+    - profile # ruby-prof
+    - ips     # benchmark-ips
+
+
+Style/FormatString:
+  EnforcedStyle: percent
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/YodaCondition:
+  EnforcedStyle: forbid_for_equality_operators_only

data/.yardopts

@@ -0,0 +1,10 @@
+-o doc
+--embed-mixins
+--hide-void-return
+--no-private
+--asset images:images
+--exclude lib/benchmark_driver
+--exclude lib/d_heap/benchmarks*
+-
+CHANGELOG.md
+CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -0,0 +1,72 @@
+## Current/Unreleased
+
+## Release v0.6.0 (2021-01-24)
+
+* 🔥 **Breaking**: `#initialize` uses a keyword argument for `d`
+* ✨ Added `#initialize(capacity: capa)` to set initial capacity.
+* ✨ Added `peek_with_score` and `peek_score`
+* ✨ Added `pop_with_score` and `each_pop(with_score: true)`
+* ✨ Added `pop_all_below(max_score, array = [])`
+* ✨ Added aliases for `shift` and `next`
+* 📈 Added benchmark charts to README, and `bin/bench_charts` to generate them.
+    * requires `gruff` which requires `rmagick` which requires `imagemagick`
+* 📝 Many documentation updates and fixes.
+
+## Release v0.5.0 (2021-01-17)
+
+* 🔥 **Breaking**: reversed order of `#push` arguments to `value, score`.
+* ✨ Added `#insert(score, value)` to replace earlier version of `#push`.
+* ✨ Added `#each_pop` enumerator.
+* ✨ Added aliases for `deq`, `enq`, `first`, `pop_below`, `length`, and
+    `count`, to mimic other classes in ruby's stdlib.
+* ⚡️♻️  More performance improvements:
+    * Created an `ENTRY` struct and store both the score and the value pointer in
+      the same `ENTRY *entries` array.
+    * Reduced unnecessary allocations or copies in both sift loops.  A similar
+      refactoring also sped up the pure ruby benchmark implementation.
+    * Compiling with `-O3`.
+* 📝 Updated (and in some cases, fixed) yardoc
+* ♻️  Moved aliases and less performance sensitive code into ruby.
+* ♻️  DRY up push/insert methods
+
+## Release v0.4.0 (2021-01-12)
+
+* 🔥 **Breaking**: Scores must be `Integer` or convertable to `Float`
+    * ⚠️  `Integer` scores must fit in `-ULONG_LONG_MAX` to `+ULONG_LONG_MAX`.
+* ⚡️ Big performance improvements, by using C `long double *cscores` array
+* ⚡️ many many (so many) updates to benchmarks
+* ✨ Added `DHeap#clear`
+* 🐛 Fixed `DHeap#initialize_copy` and `#freeze`
+* ♻️  significant refactoring
+* 📝 Updated docs (mostly adding benchmarks)
+
+## Release v0.3.0 (2020-12-29)
+
+* 🔥 **Breaking**: Removed class methods that operated directly on an array.
+    They weren't compatible with the performance improvements.
+* ⚡️ Big performance improvements, by converting to a `T_DATA` struct.
+* ♻️  Major refactoring/rewriting of dheap.c
+* ✅ Added benchmark specs
+
+## Release v0.2.2 (2020-12-27)
+
+* 🐛 fix `optimized_cmp`, avoiding internal symbols
+* 📝 Update documentation
+* 💚 fix macos CI
+* ➕ Add rubocop 👮🎨
+
+## Release v0.2.1 (2020-12-26)
+
+* ⬆️  Upgraded rake (and bundler) to support ruby 3.0
+
+## Release v0.2.0 (2020-12-24)
+
+* ✨ Add ability to push separate score and value
+* ⚡️ Big performance gain, by storing scores separately and using ruby's
+  internal `OPTIMIZED_CMP` instead of always directly calling `<=>`
+
+## Release v0.1.0 (2020-12-22)
+
+🎉 initial release 🎉
+
+* ✨ Add basic d-ary Heap implementation

data/Gemfile

@@ -1,8 +1,20 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in d_heap.gemspec
 gemspec
 
+gem "pry"
 gem "rake", "~> 13.0"
 gem "rake-compiler"
 gem "rspec", "~> 3.10"
+gem "rubocop", "~> 1.0"
+
+install_if -> { RUBY_PLATFORM !~ /darwin/ } do
+  gem "benchmark_driver-output-gruff"
+end
+
+gem "perf"
+gem "priority_queue_cxx"
+gem "stackprof"

data/Gemfile.lock

@@ -1,15 +1,38 @@
 PATH
   remote: .
   specs:
-    d_heap (0.2.1)
+    d_heap (0.6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.1)
+    benchmark_driver (0.15.16)
+    benchmark_driver-output-gruff (0.3.1)
+      benchmark_driver (>= 0.12.0)
+      gruff
+    coderay (1.1.3)
     diff-lcs (1.4.4)
+    gruff (0.12.1)
+      histogram
+      rmagick
+    histogram (0.2.4.1)
+    method_source (1.0.0)
+    parallel (1.19.2)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    perf (0.1.2)
+    priority_queue_cxx (0.3.4)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rainbow (3.0.0)
     rake (13.0.3)
     rake-compiler (1.1.1)
       rake
+    regexp_parser (1.8.2)
+    rexml (3.2.3)
+    rmagick (4.1.2)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
@@ -23,15 +46,38 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.0)
+    rubocop (1.2.0)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
+      rexml
+      rubocop-ast (>= 1.0.1)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.1.1)
+      parser (>= 2.7.1.5)
+    ruby-prof (1.4.2)
+    ruby-progressbar (1.10.1)
+    stackprof (0.2.16)
+    unicode-display_width (1.7.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  benchmark_driver
+  benchmark_driver-output-gruff
   d_heap!
+  perf
+  priority_queue_cxx
+  pry
   rake (~> 13.0)
   rake-compiler
   rspec (~> 3.10)
+  rubocop (~> 1.0)
+  ruby-prof
+  stackprof
 
 BUNDLED WITH
    2.2.3

data/N

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+export BENCH_N="$1"
+shift
+
+exec ruby "$@"

data/README.md

@@ -1,53 +1,134 @@
-# DHeap
-
-A fast _d_-ary heap implementation for ruby, useful in priority queues and graph
-algorithms.
-
-The _d_-ary heap data structure is a generalization of the binary heap, in which
-the nodes have _d_ children instead of 2.  This allows for "decrease priority"
-operations to be performed more quickly with the tradeoff of slower delete
-minimum.  Additionally, _d_-ary heaps can have better memory cache behavior than
-binary heaps, allowing them to run more quickly in practice despite slower
-worst-case time complexity.
-
-_TODO:_ In addition to a basic _d_-ary heap class (`DHeap`), this library
-~~includes~~ _will include_ extensions to `Array`, allowing an Array to be
-directly handled as a priority queue.  These extension methods are meant to be
-used similarly to how `#bsearch` and `#bsearch_index` might be used.
-
-_TODO:_ Also included is `DHeap::Set`, which augments the basic heap with an
-internal `Hash`, which maps a set of values to scores.
-loosely inspired by go's timers.  e.g: It lazily sifts its heap after deletion
-and adjustments, to achieve faster average runtime for *add* and *cancel*
-operations.
-
-_TODO:_ Also included is `DHeap::Timers`, which contains some features that are
-loosely inspired by go's timers.  e.g: It lazily sifts its heap after deletion
-and adjustments, to achieve faster average runtime for *add* and *cancel*
-operations.
+# DHeap - Fast d-ary heap for ruby
+
+[![Gem Version](https://badge.fury.io/rb/d_heap.svg)](https://badge.fury.io/rb/d_heap)
+[![Build Status](https://github.com/nevans/d_heap/workflows/CI/badge.svg)](https://github.com/nevans/d_heap/actions?query=workflow%3ACI)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ff274acd0683c99c03e1/maintainability)](https://codeclimate.com/github/nevans/d_heap/maintainability)
+
+A fast [_d_-ary heap][d-ary heap] [priority queue] implementation for ruby,
+implemented as a C extension.
+
+From [wikipedia](https://en.wikipedia.org/wiki/Heap_(data_structure)):
+> A heap is a specialized tree-based data structure which is essentially an
+> almost complete tree that satisfies the heap property: in a min heap, for any
+> given node C, if P is a parent node of C, then the key (the value) of P is
+> less than or equal to the key of C. The node at the "top" of the heap (with no
+> parents) is called the root node.
+
+![tree representation of a min heap](images/wikipedia-min-heap.png)
+
+With a regular queue, you expect "FIFO" behavior: first in, first out.  With a
+stack you expect "LIFO": last in first out.  A priority queue has a score for
+each element and elements are popped in order by score.  Priority queues are
+often used in algorithms for e.g. [scheduling] of timers or bandwidth
+management, for [Huffman coding], and various graph search algorithms such as
+[Dijkstra's algorithm], [A* search], or [Prim's algorithm].
+
+The _d_-ary heap data structure is a generalization of the [binary heap], in
+which the nodes have _d_ children instead of 2.  This allows for "insert" and
+"decrease priority" operations to be performed more quickly with the tradeoff of
+slower delete minimum or "increase priority".  Additionally, _d_-ary heaps can
+have better memory cache behavior than binary heaps, allowing them to run more
+quickly in practice despite slower worst-case time complexity. In the worst
+case, a _d_-ary heap requires only `O(log n / log d)` operations to push, with
+the tradeoff that pop requires `O(d log n / log d)`.
+
+Although you should probably just use the default _d_ value  of `4` (see the
+analysis below), it's always advisable to benchmark your specific use-case.  In
+particular, if you push items more than you pop, higher values for _d_ can give
+a faster total runtime.
+
+[d-ary heap]: https://en.wikipedia.org/wiki/D-ary_heap
+[priority queue]: https://en.wikipedia.org/wiki/Priority_queue
+[binary heap]: https://en.wikipedia.org/wiki/Binary_heap
+[scheduling]: https://en.wikipedia.org/wiki/Scheduling_(computing)
+[Huffman coding]: https://en.wikipedia.org/wiki/Huffman_coding#Compression
+[Dijkstra's algorithm]: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm#Using_a_priority_queue
+[A* search]: https://en.wikipedia.org/wiki/A*_search_algorithm#Description
+[Prim's algorithm]: https://en.wikipedia.org/wiki/Prim%27s_algorithm
 
-## Motivation
+## Usage
+
+The basic API is `#push(object, score)` and `#pop`.  Please read the
+[gem documentation] for more details and other methods.
+
+Quick reference for some common methods:
+
+* `heap << object` adds a value, with `Float(object)` as its score.
+* `heap.push(object, score)` adds a value with an extrinsic score.
+* `heap.pop` removes and returns the value with the minimum score.
+* `heap.pop_lte(max_score)` pops only if the next score is `<=` the argument.
+* `heap.peek` to view the minimum value without popping it.
+* `heap.clear` to remove all items from the heap.
+* `heap.empty?` returns true if the heap is empty.
+* `heap.size` returns the number of items in the heap.
+
+If the score changes while the object is still in the heap, it will not be
+re-evaluated again.
+
+The score must either be `Integer` or `Float` or convertable to a `Float` via
+`Float(score)` (i.e. it should implement `#to_f`).  Constraining scores to
+numeric values gives more than 50% speedup under some benchmarks!  _n.b._
+`Integer` _scores must have an absolute value that fits into_ `unsigned long
+long`. This is compiler and architecture dependant but with gcc on an IA-64
+system it's 64 bits, which gives a range of -18,446,744,073,709,551,615 to
++18,446,744,073,709,551,615, which is more than enough to store e.g. POSIX time
+in nanoseconds.
+
+_Comparing arbitary objects via_ `a <=> b` _was the original design and may be
+added back in a future version,_ if (and only if) _it can be done without
+impacting the speed of numeric comparisons. The speedup from this constraint is
+huge!_
+
+[gem documentation]: https://rubydoc.info/gems/d_heap/DHeap
+
+### Examples
 
-Ruby's Array class comes with some helpful methods for maintaining a sorted
-array, by combining `#bsearch_index` with `#insert`.  With certain insert/remove
-workloads that can perform very well, but in the worst-case an insert or delete
-can result in O(n), since it may need to memcopy a significant portion of the
-array.  Knowing that priority queues are usually implemented with a heap, and
-that the heap is a relatively simple data structure, I set out to replace my
-`#bsearch_index` and `#insert` code with a one.  I was surprised to find that,
-at least under certain benchmarks, my ruby Heap implementation was tied with or
-slower than inserting into a fully sorted array.  On the one hand, this is a
-testament to ruby's fine-tuned Array implementation.  On the other hand, it
-seemed like a heap implementated in C should easily match the speed of ruby's
-bsearch + insert.
-
-Additionally, I was inspired by reading go's "timer.go" implementation to
-experiment with a 4-ary heap, instead of the traditional binary heap.  In the
-case of timers, new timers are usually scheduled to run after most of the
-existing timers and timers are usually canceled before they have a chance to
-run. While a binary heap holds 50% of its elements in its last layer, 75% of a
-4-ary heap will have no children.  That diminishes the extra comparison
-overhead during sift-down.
+```ruby
+# create some example objects to place in our heap
+Task = Struct.new(:id, :time) do
+  def to_f; time.to_f end
+end
+t1 = Task.new(1, Time.now + 5*60)
+t2 = Task.new(2, Time.now + 50)
+t3 = Task.new(3, Time.now + 60)
+t4 = Task.new(4, Time.now +  5)
+
+# create the heap
+require "d_heap"
+heap = DHeap.new
+
+# push with an explicit score (which might be extrinsic to the value)
+heap.push t1, t1.to_f
+
+# the score will be implicitly cast with Float, so any object with #to_f
+heap.push t2, t2
+
+# if the object has an intrinsic score via #to_f, "<<" is the simplest API
+heap << t3 << t4
+
+# pop returns the lowest scored item, and removes it from the heap
+heap.pop    # => #<struct Task id=4, time=2021-01-17 17:02:22.5574 -0500>
+heap.pop    # => #<struct Task id=2, time=2021-01-17 17:03:07.5574 -0500>
+
+# peek returns the lowest scored item, without removing it from the heap
+heap.peek   # => #<struct Task id=3, time=2021-01-17 17:03:17.5574 -0500>
+heap.pop    # => #<struct Task id=3, time=2021-01-17 17:03:17.5574 -0500>
+
+# pop_lte handles the common "h.pop if h.peek_score < max" pattern
+heap.pop_lte(Time.now + 65) # => nil
+
+# the heap size can be inspected with size and empty?
+heap.empty? # => false
+heap.size   # => 1
+heap.pop    # => #<struct Task id=1, time=2021-01-17 17:07:17.5574 -0500>
+heap.empty? # => true
+heap.size   # => 0
+
+# popping from an empty heap returns nil
+heap.pop    # => nil
+```
+
+Please see the [gem documentation] for more methods and more examples.
 
 ## Installation
 
@@ -65,108 +146,264 @@ Or install it yourself as:
 
     $ gem install d_heap
 
-## Usage
-
-The simplest way to use it is simply with `#push` and `#pop`.  Push will 
-
-```ruby
-require "d_heap"
+## Motivation
 
-heap = DHeap.new # defaults to a 4-ary heap
+One naive approach to a priority queue is to maintain an array in sorted order.
+This can be very simply implemented in ruby with `Array#bseach_index` +
+`Array#insert`.  This can be very fast—`Array#pop` is `O(1)`—but the worst-case
+for insert is `O(n)` because it may need to `memcpy` a significant portion of
+the array.
 
-# storing [time, task] tuples
-heap << [Time.now + 5*60, Task.new(1)]
-heap << [Time.now +   30, Task.new(2)]
-heap << [Time.now +   60, Task.new(3)]
-heap << [Time.now +    5, Task.new(4)]
+The standard way to implement a priority queue is with a binary heap.  Although
+this increases the time complexity for `pop` alone, it reduces the combined time
+compexity for the combined `push` + `pop`. Using a d-ary heap with d > 2
+makes the tree shorter but broader, which reduces  to `O(log n / log d)` while
+increasing the comparisons needed by sift-down to `O(d log n/ log d)`.
 
-# peeking and popping (using last to get the task and ignore the time)
-heap.pop.last # => Task[4]
-heap.pop.last # => Task[2]
-heap.peak.last # => Task[3]
-heap.pop.last # => Task[3]
-heap.pop.last # => Task[1]
-```
+However, I was disappointed when my best ruby heap implementation ran much more
+slowly than the naive approach—even for heaps containing ten thousand items.
+Although it _is_ `O(n)`, `memcpy` is _very_ fast, while calling `<=>` from ruby
+has _much_ higher overhead.  And a _d_-heap needs `d + 1` times more comparisons
+for each push + pop than `bsearch` + `insert`.
 
-Read the `rdoc` for more detailed documentation and examples.
+Additionally, when researching how other systems handle their scheduling, I was
+inspired by reading go's "timer.go" implementation to experiment with a 4-ary
+heap instead of the traditional binary heap.
 
 ## Benchmarks
 
-_TODO: put benchmarks here._
+_See `bin/benchmarks` and `docs/benchmarks.txt`, as well as `bin/profile` and
+`docs/profile.txt` for much more detail or updated results. These benchmarks
+were measured with v0.5.0 and ruby 2.7.2 without MJIT enabled._
+
+These benchmarks use very simple implementations for a pure-ruby heap and an
+array that is kept sorted using `Array#bsearch_index` and `Array#insert`.  For
+comparison, I also compare to the [priority_queue_cxx gem] which uses the [C++
+STL priority_queue], and another naive implementation that uses `Array#min` and
+`Array#delete_at` with an unsorted array.
+
+In these benchmarks, `DHeap` runs faster than all other implementations for
+every scenario and every value of N, although the difference is usually more
+noticable at higher values of N.  The pure ruby heap implementation is
+competitive for `push` alone at every value of N, but is significantly slower
+than bsearch + insert for push + pop, until N is _very_ large (somewhere between
+10k and 100k)!
+
+[priority_queue_cxx gem]: https://rubygems.org/gems/priority_queue_cxx
+[C++ STL priority_queue]: http://www.cplusplus.com/reference/queue/priority_queue/
+
+Three different scenarios are measured:
+
+### push N items onto an empty heap
+
+...but never pop (clearing between each set of pushes).
+
+![bar graph for push_n_pop_n benchmarks](./images/push_n.png)
+
+### push N items onto an empty heap then pop all N
+
+Although this could be used for heap sort, we're unlikely to choose heap sort
+over Ruby's quick sort implementation. I'm using this scenario to represent
+the amortized cost of creating a heap and (eventually) draining it.
+
+![bar graph for push_n_pop_n benchmarks](./images/push_n_pop_n.png)
+
+### push and pop on a heap with N values
+
+Repeatedly push and pop while keeping a stable heap size.  This is a _very
+simplistic_ approximation for how most scheduler/timer heaps might be used.
+Usually when a timer fires it will be quickly replaced by a new timer, and the
+overall count of timers will remain roughly stable.
+
+![bar graph for push_pop benchmarks](./images/push_pop.png)
+
+### numbers
+
+Even for very small N values the benchmark implementations,  `DHeap` runs faster
+than the other implementations for each scenario, although the difference is
+still relatively small.  The pure ruby binary heap is 2x or more slower than
+bsearch + insert for common push/pop scenario.
+
+    == push N (N=5) ==========================================================
+    push N (c_dheap):   1969700.7 i/s
+    push N (c++ stl):   1049738.1 i/s - 1.88x  slower
+    push N (rb_heap):    928435.2 i/s - 2.12x  slower
+    push N (bsearch):    921060.0 i/s - 2.14x  slower
+
+    == push N then pop N (N=5) ===============================================
+    push N + pop N (c_dheap):   1375805.0 i/s
+    push N + pop N (c++ stl):   1134997.5 i/s - 1.21x  slower
+    push N + pop N (findmin):    862913.1 i/s - 1.59x  slower
+    push N + pop N (bsearch):    762887.1 i/s - 1.80x  slower
+    push N + pop N (rb_heap):    506890.4 i/s - 2.71x  slower
+
+    == Push/pop with pre-filled queue of size=N (N=5) ========================
+    push + pop (c_dheap):   9044435.5 i/s
+    push + pop (c++ stl):   7534583.4 i/s - 1.20x  slower
+    push + pop (findmin):   5026155.1 i/s - 1.80x  slower
+    push + pop (bsearch):   4300260.0 i/s - 2.10x  slower
+    push + pop (rb_heap):   2299499.7 i/s - 3.93x  slower
+
+By N=21, `DHeap` has pulled significantly ahead of bsearch + insert for all
+scenarios, but the pure ruby heap is still slower than every other
+implementation—even resorting the array after every `#push`—in any scenario that
+uses `#pop`.
+
+    == push N (N=21) =========================================================
+    push N (c_dheap):    464231.4 i/s
+    push N (c++ stl):    305546.7 i/s - 1.52x  slower
+    push N (rb_heap):    202803.7 i/s - 2.29x  slower
+    push N (bsearch):    168678.7 i/s - 2.75x  slower
+
+    == push N then pop N (N=21) ==============================================
+    push N + pop N (c_dheap):    298350.3 i/s
+    push N + pop N (c++ stl):    252227.1 i/s - 1.18x  slower
+    push N + pop N (findmin):    161998.7 i/s - 1.84x  slower
+    push N + pop N (bsearch):    143432.3 i/s - 2.08x  slower
+    push N + pop N (rb_heap):     79622.1 i/s - 3.75x  slower
+
+    == Push/pop with pre-filled queue of size=N (N=21) =======================
+    push + pop (c_dheap):   8855093.4 i/s
+    push + pop (c++ stl):   7223079.5 i/s - 1.23x  slower
+    push + pop (findmin):   4542913.7 i/s - 1.95x  slower
+    push + pop (bsearch):   3461802.4 i/s - 2.56x  slower
+    push + pop (rb_heap):   1845488.7 i/s - 4.80x  slower
+
+At higher values of N, a heaps logarithmic growth leads to only a little
+slowdown of `#push`, while insert's linear growth causes it to run noticably
+slower and slower.  But because `#pop` is `O(1)` for a sorted array and `O(d log
+n / log d)` for a heap, scenarios involving both `#push` and `#pop` remain
+relatively close, and bsearch + insert still runs faster than a pure ruby heap,
+even up to queues with 10k items.  But as queue size increases beyond than that,
+the linear time compexity to keep a sorted array dominates.
+
+    == push + pop (rb_heap)
+    queue size =    10000:    736618.2 i/s
+    queue size =    25000:    670186.8 i/s - 1.10x  slower
+    queue size =    50000:    618156.7 i/s - 1.19x  slower
+    queue size =   100000:    579250.7 i/s - 1.27x  slower
+    queue size =   250000:    572795.0 i/s - 1.29x  slower
+    queue size =   500000:    543648.3 i/s - 1.35x  slower
+    queue size =  1000000:    513523.4 i/s - 1.43x  slower
+    queue size =  2500000:    460848.9 i/s - 1.60x  slower
+    queue size =  5000000:    445234.5 i/s - 1.65x  slower
+    queue size = 10000000:    423119.0 i/s - 1.74x  slower
+
+    == push + pop (bsearch)
+    queue size =    10000:    786334.2 i/s
+    queue size =    25000:    364963.8 i/s - 2.15x  slower
+    queue size =    50000:    200520.6 i/s - 3.92x  slower
+    queue size =   100000:     88607.0 i/s - 8.87x  slower
+    queue size =   250000:     34530.5 i/s - 22.77x  slower
+    queue size =   500000:     17965.4 i/s - 43.77x  slower
+    queue size =  1000000:      5638.7 i/s - 139.45x  slower
+    queue size =  2500000:      1302.0 i/s - 603.93x  slower
+    queue size =  5000000:       592.0 i/s - 1328.25x  slower
+    queue size = 10000000:       288.8 i/s - 2722.66x  slower
+
+    == push + pop (c_dheap)
+    queue size =    10000:   7311366.6 i/s
+    queue size =    50000:   6737824.5 i/s - 1.09x  slower
+    queue size =    25000:   6407340.6 i/s - 1.14x  slower
+    queue size =   100000:   6254396.3 i/s - 1.17x  slower
+    queue size =   250000:   5917684.5 i/s - 1.24x  slower
+    queue size =   500000:   5126307.6 i/s - 1.43x  slower
+    queue size =  1000000:   4403494.1 i/s - 1.66x  slower
+    queue size =  2500000:   3304088.2 i/s - 2.21x  slower
+    queue size =  5000000:   2664897.7 i/s - 2.74x  slower
+    queue size = 10000000:   2137927.6 i/s - 3.42x  slower
 
 ## Analysis
 
 ### Time complexity
 
-Both sift operations can perform (log[d] n = log n / log d) swaps.
-Swap up performs only a single comparison per swap: O(1).
-Swap down performs as many as d comparions per swap: O(d).
-
-Inserting an item is O(log n / log d).
-Deleting the root is O(d log n / log d).
-
-Assuming every inserted item is eventually deleted from the root, d=4 requires
-the fewest comparisons for combined insert and delete:
- * (1 + 2) lg 2 = 4.328085
- * (1 + 3) lg 3 = 3.640957
- * (1 + 4) lg 4 = 3.606738
- * (1 + 5) lg 5 = 3.728010
- * (1 + 6) lg 6 = 3.906774
- * etc...
-
-Leaf nodes require no comparisons to shift down, and higher values for d have
-higher percentage of leaf nodes:
- * d=2 has ~50% leaves,
- * d=3 has ~67% leaves,
- * d=4 has ~75% leaves,
- * and so on...
+There are two fundamental heap operations: sift-up (used by push) and sift-down
+(used by pop).
+
+* A _d_-ary heap will have `log n / log d` layers, so both sift operations can
+  perform as many as `log n / log d` writes, when a member sifts the entire
+  length of the tree.
+* Sift-up makes one comparison per layer, so push runs in `O(log n / log d)`.
+* Sift-down makes d comparions per layer, so pop runs in `O(d log n / log d)`.
+
+So, in the simplest case of running balanced push/pop while maintaining the same
+heap size, `(1 + d) log n / log d` comparisons are made.  In the worst case,
+when every sift traverses every layer of the tree, `d=4` requires the fewest
+comparisons for combined insert and delete:
+
+* (1 +  2) lg n / lg d ≈ 4.328085 lg n
+* (1 +  3) lg n / lg d ≈ 3.640957 lg n
+* (1 +  4) lg n / lg d ≈ 3.606738 lg n
+* (1 +  5) lg n / lg d ≈ 3.728010 lg n
+* (1 +  6) lg n / lg d ≈ 3.906774 lg n
+* (1 +  7) lg n / lg d ≈ 4.111187 lg n
+* (1 +  8) lg n / lg d ≈ 4.328085 lg n
+* (1 +  9) lg n / lg d ≈ 4.551196 lg n
+* (1 + 10) lg n / lg d ≈ 4.777239 lg n
+* etc...
 
 See https://en.wikipedia.org/wiki/D-ary_heap#Analysis for deeper analysis.
 
 ### Space complexity
 
-Because the heap is a complete binary tree, space usage is linear, regardless
-of d.  However higher d values may provide better cache locality.
-
-We can run comparisons much much faster for Numeric or String objects than for
-ruby objects which delegate comparison to internal Numeric or String objects.
-And it is often advantageous to use extrinsic scores for uncomparable items.
-For this, our internal array uses twice as many entries (one for score and one
-for value) as it would if it only supported intrinsic comparison or used an
-un-memoized "sort_by" proc.
+Space usage is linear, regardless of d.  However higher d values may
+provide better cache locality.  Because the heap is a complete binary tree, the
+elements can be stored in an array, without the need for tree or list pointers.
 
-### Timers
+Ruby can compare Numeric values _much_ faster than other ruby objects, even if
+those objects simply delegate comparison to internal Numeric values.  And it is
+often useful to use external scores for otherwise uncomparable values.  So
+`DHeap` uses twice as many entries (one for score and one for value)
+as an array which only stores values.
 
-Additionally, when used to sort timers, we can reasonably assume that:
- * New timers usually sort after most existing timers.
- * Most timers will be canceled before executing.
- * Canceled timers usually sort after most existing timers.
+## Thread safety
 
-So, if we are able to delete an item without searching for it, by keeping a map
-of positions within the heap, most timers can be inserted and deleted in O(1)
-time.  Canceling a non-leaf timer can be further optimized by marking it as
-canceled without immediately removing it from the heap.  If the timer is
-rescheduled before we garbage collect, adjusting its position will usually be
-faster than a delete and re-insert.
+`DHeap` is _not_ thread-safe, so concurrent access from multiple threads need to
+take precautions such as locking access behind a mutex.
 
 ## Alternative data structures
 
-Depending on what you're doing, maintaining a sorted `Array` using
-`#bsearch_index` and `#insert` might be faster!  Although it is technically
-O(n) for insertions, the implementations for `memcpy` or `memmove` can be *very*
-fast on modern architectures.  Also, it can be faster O(n) on average, if
-insertions are usually near the end of the array.  You should run benchmarks
-with your expected scenarios to determine which is right.
+As always, you should run benchmarks with your expected scenarios to determine
+which is best for your application.
+
+Depending on your use-case, maintaining a sorted `Array` using `#bsearch_index`
+and `#insert` might be just fine!  Even `min` plus `delete` with an unsorted
+array can be very fast on small queues.  Although insertions run with `O(n)`,
+`memcpy` is so fast on modern hardware that your dataset might not be large
+enough for it to matter.
+
+More complex heap varients, e.g. [Fibonacci heap], allow heaps to be split and
+merged which gives some graph algorithms a lower amortized time complexity.  But
+in practice, _d_-ary heaps have much lower overhead and often run faster.
+
+[Fibonacci heap]: https://en.wikipedia.org/wiki/Fibonacci_heap
 
 If it is important to be able to quickly enumerate the set or find the ranking
-of values in it, then you probably want to use a self-balancing binary search
-tree (e.g. a red-black tree) or a skip-list.
-
-A Hashed Timing Wheel or Heirarchical Timing Wheels (or some variant in that
-family of data structures) can be constructed to have effectively O(1) running
-time in most cases.  However, the implementation for that data structure is more
-complex than a heap.  If a 4-ary heap is good enough for go's timers, it should
-be suitable for many use cases.
+of values in it, then you may want to use a self-balancing binary search tree
+(e.g. a [red-black tree]) or a [skip-list].
+
+[red-black tree]: https://en.wikipedia.org/wiki/Red%E2%80%93black_tree
+[skip-list]: https://en.wikipedia.org/wiki/Skip_list
+
+[Hashed and Heirarchical Timing Wheels][timing wheels] (or some variant in that
+family of data structures) can be constructed to have effectively `O(1)` running
+time in most cases.  Although the implementation for that data structure is more
+complex than a heap, it may be necessary for enormous values of N.
+
+[timing wheels]: http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf
+
+## TODOs...
+
+_TODO:_ Also ~~included is~~ _will include_ `DHeap::Map`, which augments the
+basic heap with an internal `Hash`, which maps objects to their position in the
+heap.  This enforces a uniqueness constraint on items on the heap, and also
+allows items to be more efficiently deleted or adjusted.  However maintaining
+the hash does lead to a small drop in normal `#push` and `#pop` performance.
+
+_TODO:_ Also ~~included is~~ _will include_ `DHeap::Lazy`, which contains some
+features that are loosely inspired by go's timers.  e.g: It lazily sifts its
+heap after deletion and adjustments, to achieve faster average runtime for *add*
+and *cancel* operations.
 
 ## Development