disjoint_interval_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2489f3da4496b1c3abb350eb582d52a40298e61fd9132f52f3ca80e69aeda976
+  data.tar.gz: a3a35b0752910b4ae0e5f2c5aa021bf2175b4ae3545041670ee1fb2f7fe20c96
+SHA512:
+  metadata.gz: 8937708e32708573ed399b91722a9ccc1ff8c9d338f6e6655c089a996e4228b0685d653d6b4dd2729e121f384a0a622a0f9cba585475128304633bf80c1830b0
+  data.tar.gz: af0540688e96cc9aa9eebfa5951d4b04aafc04e137b7d7113e959fef4d2621eb81d1a63f7fcbfbbd81d8716cf7fba2d3507e4fc20669265f94fbb2821a7dc163

data/CITATION.cff

@@ -0,0 +1,67 @@
+cff-version: 1.2.0
+message: >-
+  If you use this software in academic work, please cite the papers that
+  introduced the structures it derives from, listed under `references` below.
+title: disjoint_interval_tree
+abstract: >-
+  A set of pairwise disjoint half-open intervals, backed by an augmented AVL
+  tree written in C, with Ruby bindings. Each node caches the hull of the
+  subtree it roots, so intersection queries prune whole subtrees in constant
+  time.
+type: software
+license: CECILL-C
+repository-code: "https://github.com/anlsys/ruby-disjoint-interval-tree"
+authors:
+  - family-names: Pereira
+    given-names: Romain
+    email: rpereira@anl.gov
+    affiliation: Argonne National Laboratory
+    orcid: "https://orcid.org/0000-0003-1856-2172"
+keywords:
+  - interval tree
+  - AVL tree
+  - augmented tree
+  - ruby
+  - c
+
+references:
+  - type: conference-paper
+    title: >-
+      Taskgrind: Heavyweight Dynamic Binary Instrumentation for Parallel
+      Programs Analysis
+    authors:
+      - family-names: Pereira
+        given-names: Romain
+      - family-names: Stelle
+        given-names: George
+      - family-names: Carribault
+        given-names: Patrick
+    collection-title: >-
+      SC24-W: Workshops of the International Conference for High Performance
+      Computing, Networking, Storage and Analysis
+    year: 2024
+    month: 11
+    start: 214
+    end: 221
+    location:
+      name: Atlanta, GA, USA
+    doi: 10.1109/SCW63240.2024.00033
+    notes: Introduced the SPMT, the disjoint interval tree this software rewrites.
+
+  - type: conference-paper
+    title: Multi-GPU Memory Coherence for BLAS Matrices
+    authors:
+      - family-names: Pereira
+        given-names: Romain
+      - family-names: Polet
+        given-names: Pierre-Etienne
+      - family-names: Gautier
+        given-names: Thierry
+      - family-names: Perarnau
+        given-names: Swann
+    collection-title: >-
+      IPDPS-W HIPS: 31st International Workshop on High-level Parallel
+      Programming Models and Supportive Environments
+    year: 2026
+    month: 5
+    notes: Introduced the LP-Tree, whose subtree hull augment this software reuses.

data/README.md

@@ -0,0 +1,340 @@
+# disjoint\_interval\_tree
+
+A set of **pairwise disjoint half-open intervals `[a..b[`**, implemented in C
+and exposed to Ruby.
+
+It is a self-balancing (AVL) binary search tree, augmented - as the LP-Tree it
+is inspired from, see [References](#references) - with the *hull* of the
+subtree each node roots, so that intersection queries prune whole subtrees in
+`O(1)`.
+
+## Installation
+
+```sh
+gem install disjoint_interval_tree
+```
+
+or, in a `Gemfile`:
+
+```ruby
+gem 'disjoint_interval_tree'
+```
+
+Ruby >= 2.7 and a C compiler are required: the extension is built at install
+time.
+
+## Synopsis
+
+```ruby
+require 'disjoint_interval_tree'
+
+tree = DisjointIntervalTree.new
+tree.insert(10, 20)
+tree.insert(30, 40)
+
+tree.intersect(15, 35) do |a, b|
+  puts "[#{a}..#{b}["
+end
+# => [10..20[
+# => [30..40[
+
+tree.remove(15, 35)   # => 2
+tree.to_a             # => []
+```
+
+## Semantics
+
+* Intervals are **half-open**: `[a..b[` contains `a` but not `b`. `[0..10[` and
+  `[10..20[` are adjacent, they do **not** intersect.
+* Bounds are **unsigned 64 bits integers**, so intervals live in
+  `[0 .. DisjointIntervalTree::MAX[`. Negative or non-integer bounds raise.
+* Stored intervals are **pairwise disjoint**. It is a usage contract that the
+  caller never inserts an interval overlapping an already inserted one.
+  Breaking it raises `DisjointIntervalTree::OverlapError` and leaves the tree
+  unchanged - intervals are never merged nor split implicitly.
+
+## Operations
+
+With `n` intervals stored, `k` intervals reported by the call, and `m`
+intervals handed to the constructor:
+
+| operation                                    | description                                                                                                              | complexity     |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------- |
+| `DisjointIntervalTree.new(intervals = nil)`  | Build an empty tree, or one filled with the given `[a, b]` pairs.                                                         | `O(m.log m)`   |
+| `insert(a, b)`                               | Add `[a..b[`, raising `OverlapError` if it intersects an already stored interval.                                         | `O(log n)`     |
+| `insert?(a, b)`                              | Same as `insert`, but returns `false` instead of raising when it would overlap.                                           | `O(log n)`     |
+| `intersect(a, b, &blk)`                      | Yield every stored interval intersecting `[a..b[` in increasing order, or return them as an array when given no block.    | `O(k + log n)` |
+| `intersect?(a, b)`                           | Whether at least one stored interval intersects `[a..b[`.                                                                 | `O(log n)`     |
+| `remove(a, b, &blk)`                         | Remove every stored interval intersecting `[a..b[` - whole, never split - and return how many went.                       | `O(k.log n)`   |
+| `at(x)`                                      | The stored interval containing the point `x`, or `nil`.                                                                   | `O(log n)`     |
+| `cover?(x)`                                  | Whether the point `x` falls inside a stored interval.                                                                     | `O(log n)`     |
+| `hull`                                       | The smallest interval enclosing every stored one, read straight off the root augment.                                     | `O(1)`         |
+| `size`, `length`                             | How many intervals are stored.                                                                                            | `O(1)`         |
+| `empty?`                                     | Whether the tree holds no interval at all.                                                                                | `O(1)`         |
+| `height`                                     | Height of the underlying AVL tree, for tests and diagnostics.                                                             | `O(1)`         |
+| `coverage`                                   | Total length covered, that is the sum of the lengths of the stored intervals.                                             | `O(n)`         |
+| `each(&blk)`                                 | Yield every stored interval in increasing order, or return an `Enumerator` when given no block.                           | `O(n)`         |
+| `to_a`, `entries`                            | Every stored interval as an array of `[a, b]` pairs, in increasing order.                                                 | `O(n)`         |
+| `map`, `select`, ...                         | Anything `Enumerable` provides, built on `each`.                                                                          | `O(n)`         |
+| `clear`                                      | Drop every interval, leaving the tree usable.                                                                             | `O(n)`         |
+| `dup`                                        | A deep copy, sharing no node with the original.                                                                           | `O(n.log n)`   |
+| `==`                                         | Whether two trees hold exactly the same intervals.                                                                        | `O(n)`         |
+| `check!`                                     | Re-derive every structural invariant, raising `CorruptedError` if one is broken.                                          | `O(n)`         |
+| `inspect`, `to_s`                            | A short `#<DisjointIntervalTree size=... height=...>` summary.                                                            | `O(1)`         |
+
+## Ruby API
+
+```ruby
+tree = DisjointIntervalTree.new                      # empty
+tree = DisjointIntervalTree.new([[0, 10], [20, 30]]) # pre-filled
+
+# --- the three core operations -------------------------------------------
+
+tree.insert(a, b)            # -> self, raises OverlapError if it overlaps
+tree.insert?(a, b)           # -> true / false instead of raising
+
+tree.intersect(a, b) { |x, y| ... }   # -> self, yields in increasing order
+tree.intersect(a, b)                  # -> [[x, y], ...] when no block given
+
+tree.remove(a, b)                      # -> number of intervals removed
+tree.remove(a, b) { |x, y| ... }       # ... and yields each removed interval
+
+# --- queries --------------------------------------------------------------
+
+tree.intersect?(a, b)        # -> true if any stored interval intersect [a..b[
+tree.at(x)                   # -> [a, b] containing the point x, or nil
+tree.cover?(x)               # -> true if x is covered by a stored interval
+tree.hull                    # -> [a, b] spanning every interval, or nil
+tree.size                    # -> number of stored intervals
+tree.empty?
+tree.height                  # -> height of the underlying AVL tree
+
+# --- iteration (DisjointIntervalTree includes Enumerable) -----------------
+
+tree.each { |a, b| ... }
+tree.to_a                    # -> [[a, b], ...], in increasing order
+tree.map { |a, b| b - a }
+tree.coverage                # -> total length covered
+
+# --- misc -----------------------------------------------------------------
+
+tree.clear                   # -> self
+tree.dup                     # -> deep copy
+tree == other
+tree.check!                  # -> self, raises CorruptedError if an invariant
+                             #    of the underlying tree is broken
+```
+
+Aliases: `each_intersecting` (`intersect`), `overlaps?` (`intersect?`),
+`length` (`size`), `entries` (`to_a`).
+
+The tree **must not be modified from within `each` or `intersect`**: doing so
+raises `DisjointIntervalTree::Error` rather than corrupting the structure. The
+block given to `remove` is called after the removal, on a snapshot, so it may
+modify the tree.
+
+## C API
+
+The Ruby extension is a thin binding over a standalone, dependency-free C
+library made of `ext/disjoint_interval_tree/dit.{c,h}`. It can be vendored as
+is into a C or C++ project.
+
+```c
+#include "dit.h"
+
+static int print_cb(dit_value_t a, dit_value_t b, void * user)
+{
+    (void) user;
+    printf("[%lu..%lu[\n", a, b);
+    return 0;   /* non-zero stops the traversal */
+}
+
+dit_t tree;
+dit_init(&tree);
+
+if (dit_insert(&tree, 0, 10) != DIT_OK)
+    { /* DIT_EMPTY, DIT_OVERLAP or DIT_NOMEM */ }
+
+dit_intersect(&tree, 5, 25, print_cb, NULL);
+dit_remove(&tree, 5, 25);
+
+dit_destroy(&tree);
+```
+
+### Node augments
+
+Each node stores its own interval, its children, and - in a single `augment`
+field - everything it caches about the subtree it roots:
+
+```c
+typedef struct dit_augment_s
+{
+    /* the englobing interval of the subtree, i.e. the smallest interval
+     * including every interval stored in that subtree */
+    struct { dit_value_t a, b; } hull;
+
+    /* height of the subtree, a leaf has 1 */
+    int32_t height;
+
+    /* number of nodes in the subtree */
+    uint32_t size;
+}   dit_augment_t;
+```
+
+Augments are derived from the subtree alone and recomputed bottom-up after
+every structural change, so a rotation only has to refresh the two nodes it
+moves. `hull` is what lets `dit_intersect()` discard a whole subtree with a
+single comparison; the root one is readable in O(1) through `dit_hull()`.
+
+Customization points, to define before including `dit.h`:
+
+| macro           | default                | purpose                                         |
+| --------------- | ---------------------- | ----------------------------------------------- |
+| `DIT_VALUE_T`   | `uint64_t`             | interval bound type                              |
+| `DIT_ASSERT`    | `assert`               | internal consistency assertions                  |
+| `DIT_MALLOC`    | `malloc` / `free`      | node allocation                                  |
+| `DIT_PARANOID`  | `0`                    | run `dit_check()` after every mutation           |
+
+### Invariants
+
+`dit_check()` validates, without ever aborting, that:
+
+1. every stored interval is non-empty (`a < b`),
+2. the binary search tree ordering holds, which - the bounds narrowing at each
+   level - also proves the intervals are pairwise disjoint,
+3. an in-order traversal yields increasing, non-overlapping intervals,
+4. the `height` augment of every node is correct,
+5. every node is AVL-balanced,
+6. the `size` augment of every node is correct,
+7. the `hull` augment of every node englobes its subtree exactly,
+8. that hull spans from the leftmost to the rightmost descendant,
+9. the cached cardinality matches the number of nodes,
+10. the tree depth is logarithmic in the number of nodes,
+11. no traversal is leaking.
+
+On top of that, the implementation is littered with `DIT_ASSERT`s on the
+invariants it relies on locally (rotations, augment refresh, deletion cases,
+insertion contract, ...).
+
+## Building and testing
+
+Building the extension needs the ruby development headers (`ruby-dev` /
+`ruby-devel`, or any ruby built from source).
+
+```sh
+rake compile                      # build the extension into lib/
+rake recompile                    # force a full rebuild, use this when in doubt
+rake test                         # ruby test suite
+rake test:c                       # C test suite: debug, asan+ubsan, release
+rake test:valgrind                # C test suite under valgrind
+rake test:paranoid                # ruby test suite against a DIT_PARANOID build
+rake test:gem                     # build, install into a sandbox, test the installed gem
+rake test:files                   # every file the gem ships is present and tracked by git
+rake                              # default: test:c + test
+rake verify                       # everything above, plus a randomized seed sweep
+```
+
+What each configuration actually proves:
+
+| configuration                          | proves                                                                                        |
+| -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `test:c` debug (`-O0 -DDIT_PARANOID=1`) | all the invariants below are re-validated after *every* mutation, plus the inline `DIT_ASSERT`s |
+| `test:c` sanitize                       | no undefined behaviour, no out of bounds access, no leak, still paranoid                        |
+| `test:c` release (`-DNDEBUG`)           | the behaviour is identical with every assertion compiled out                                    |
+| `test:valgrind`                         | no invalid access and no leak, independently of the sanitizers                                  |
+| `test` / `test:paranoid`                | the ruby bindings, against the regular and the paranoid extension                               |
+| `test:gem`                              | the *packaged* gem installs and works, which `test` cannot tell                                 |
+| `test:files`                            | the gem and the repository ship the same files, which neither of the above can tell             |
+
+The C test suite can also be driven directly:
+
+```sh
+make -C test/c            # debug, sanitized and release builds
+make -C test/c debug SEED=42
+```
+
+Both suites cross-check the tree against a naive reference implementation on
+randomized workloads, and validate every structural invariant after each
+operation. `rake verify SEEDS=100` widens the randomized sweep.
+
+## Releasing
+
+Releases are cut from `main`, with CI green.
+
+**1. Bump the version.**
+
+```ruby
+# lib/disjoint_interval_tree/version.rb
+VERSION = '0.2.0'
+```
+
+**2. Commit, push, and wait for CI.** `rake release` re-runs everything
+locally, but a release should not be cut from a commit CI has not seen.
+
+**3. Publish.**
+
+```sh
+rake release
+```
+
+It refuses to do anything unless the working tree is clean, the branch is
+`main`, and the tag is still free. It then runs `rake verify`, tags `vX.Y.Z`,
+pushes the tag, and `gem push`es the gem it just built.
+
+**4. Attach the gem to a GitHub release.** `rake release` prints this command
+with the version filled in:
+
+```sh
+gh release create vX.Y.Z pkg/disjoint_interval_tree-X.Y.Z.gem \
+    --title vX.Y.Z --generate-notes
+```
+
+**5. Update the downstream packagers.** `rake release` prints the sha256 of
+what it published, as a ready to paste spack `version(...)` line. For
+[THAPI-spack](https://github.com/argonne-lcf/THAPI-spack), that is
+`packages/ruby-disjoint-interval-tree/package.py`. The published artifact can
+also be checksummed directly, which is the authoritative source:
+
+```sh
+spack checksum ruby-disjoint-interval-tree X.Y.Z
+```
+
+## References
+
+`dit` is a C rewrite of two structures published by the author:
+
+* the **SPMT**, a red-black tree of disjoint memory intervals that merges
+  adjacent ranges, used to track memory accesses in Taskgrind:
+
+  > R. Pereira, G. Stelle and P. Carribault, *"Taskgrind: Heavyweight Dynamic
+  > Binary Instrumentation for Parallel Programs Analysis"*, SC24-W: Workshops
+  > of the International Conference for High Performance Computing, Networking,
+  > Storage and Analysis, Atlanta, GA, USA, 2024, pp. 214-221,
+  > doi: [10.1109/SCW63240.2024.00033](https://doi.org/10.1109/SCW63240.2024.00033).
+
+* the **LP-Tree**, a k-dimensional interval tree where each node caches the
+  hyperrectangle hull of its subtree, used to track matrix tile coherence
+  across GPUs:
+
+  > R. Pereira, P.-E. Polet, T. Gautier and S. Perarnau, *"Multi-GPU Memory
+  > Coherence for BLAS Matrices"*, IPDPS-W HIPS: 31st International Workshop on
+  > High-level Parallel Programming Models and Supportive Environments, 2026.
+
+What this library takes from each, and where it departs from them:
+
+* from the **LP-Tree**, the `includes` augment - the hull of the subtree cached
+  in every node, here `augment.hull` - and the case analysis of the insertion
+  descent. `dit` is the `K = 1` case, so the hyperrectangle collapses to an
+  interval, and `includes.hyperrect[0]` to `augment.hull`;
+* from the **SPMT**, the flat C style, the callback-based traversals and the
+  coherency-check approach (`dit_check()`);
+* unlike both, `dit` never merges nor splits intervals. Keeping them disjoint
+  is a *caller contract*, checked at no extra cost during the insertion
+  descent, which is what lets a stored interval keep its identity;
+* unlike the SPMT, the tree is an AVL rather than a red-black tree: rebalancing
+  is bottom-up and recursive, which makes the augment refresh and the deletion
+  paths markedly harder to get wrong, at the cost of slightly more rotations.
+
+## License
+
+CeCILL-C, see the headers of the source files.

data/Rakefile

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'fileutils'
+require 'rake/clean'
+require 'rbconfig'
+
+require_relative 'lib/disjoint_interval_tree/version'
+
+EXT_NAME  = 'disjoint_interval_tree'
+EXT_DIR   = File.expand_path("ext/#{EXT_NAME}", __dir__)
+LIB_DIR   = File.expand_path("lib/#{EXT_NAME}", __dir__)
+BUILD_DIR = File.expand_path("tmp/#{RUBY_PLATFORM}/#{EXT_NAME}/#{RUBY_VERSION}", __dir__)
+GEM_DIR   = File.expand_path('tmp/gemtest', __dir__)
+DLEXT     = RbConfig::CONFIG['DLEXT']
+SO_NAME   = "#{EXT_NAME}.#{DLEXT}"
+SO_PATH   = File.join(LIB_DIR, SO_NAME)
+RUBY_BIN  = RbConfig.ruby
+NPROC     = Etc.respond_to?(:nprocessors) ? Etc.nprocessors : 4
+VERSION   = DisjointIntervalTree::VERSION
+GEM_FILE  = File.expand_path("pkg/#{EXT_NAME}-#{VERSION}.gem", __dir__)
+
+SOURCES = FileList["#{EXT_DIR}/*.c", "#{EXT_DIR}/*.h", "#{EXT_DIR}/extconf.rb"]
+
+CLEAN.include('tmp')
+CLOBBER.include(SO_PATH, 'pkg')
+
+# Number of distinct RNG seeds the randomized tests are replayed with by
+# `rake verify`. Both suites take a seed, and those randomized cross-checks
+# against a naive model are the strongest correctness signal there is here.
+SEEDS = Integer(ENV.fetch('SEEDS', 20))
+
+# `rake compile EXTOPTS=--enable-paranoid` to build an extension running the
+# full coherency check after every mutation
+EXTOPTS = (ENV['EXTOPTS'] || '').split
+
+directory BUILD_DIR
+directory LIB_DIR
+
+file SO_PATH => SOURCES + [BUILD_DIR, LIB_DIR] do
+  Dir.chdir(BUILD_DIR) do
+    sh(RUBY_BIN, File.join(EXT_DIR, 'extconf.rb'), *EXTOPTS)
+    sh('make', "-j#{NPROC}")
+  end
+  FileUtils.cp(File.join(BUILD_DIR, SO_NAME), SO_PATH, verbose: true)
+end
+
+desc 'Build the C extension'
+task compile: SO_PATH
+
+# `clean` alone would not be enough: rake never considers a file task out of
+# date because of a directory prerequisite, so the stale .so has to go
+desc 'Rebuild the C extension from scratch'
+task :recompile do
+  Rake::Task[:clean].invoke
+  FileUtils.rm_f(SO_PATH)
+  [BUILD_DIR, LIB_DIR, SO_PATH].each { |t| Rake::Task[t].reenable }
+  Rake::Task[SO_PATH].invoke
+end
+
+desc 'Run the ruby test suite'
+task test: :compile do
+  sh(RUBY_BIN, '-Ilib', '-Itest', 'test/test_disjoint_interval_tree.rb')
+end
+
+namespace :test do
+  desc 'Run the C test suite (debug, sanitizers and release builds)'
+  task :c do
+    sh('make', '-C', 'test/c', 'all')
+  end
+
+  desc 'Run the C test suite under valgrind'
+  task :valgrind do
+    sh('make', '-C', 'test/c', 'valgrind')
+  end
+
+  # `EXTOPTS` is read when the Rakefile is loaded, hence the sub-invocation.
+  # The regular extension is then rebuilt, so that a paranoid - and much
+  # slower - build is never left behind in lib/
+  desc 'Run the ruby test suite against a paranoid build of the extension'
+  task :paranoid do
+    sh({ 'EXTOPTS' => '--enable-paranoid' }, RUBY_BIN, $PROGRAM_NAME, 'recompile', 'test')
+  ensure
+    sh(RUBY_BIN, $PROGRAM_NAME, 'recompile')
+  end
+
+  # This is the only task exercising what users actually get: it runs the suite
+  # without `-Ilib`, so `require 'disjoint_interval_tree'` resolves through the
+  # installed gem. A file missing from `spec.files`, a broken `extconf.rb` or a
+  # wrong `require_paths` fails here and nowhere else.
+  desc 'Install the built gem in a sandbox and run the ruby test suite against it'
+  task gem: :build do
+    FileUtils.rm_rf(GEM_DIR)
+    FileUtils.mkdir_p(GEM_DIR)
+
+    # the sandbox is the install target, but the default gem dirs stay on the
+    # path so that the test suite can still find minitest
+    env = {
+      'GEM_HOME' => GEM_DIR,
+      'GEM_PATH' => ([GEM_DIR] + Gem.path).uniq.join(File::PATH_SEPARATOR)
+    }
+
+    sh(env, 'gem', 'install', '--norc', '--no-document', '--local', GEM_FILE)
+
+    # the gem must come from the sandbox, not from a copy installed elsewhere
+    sh(env, RUBY_BIN, '-e', <<~RUBY)
+      gem 'disjoint_interval_tree', '= #{VERSION}'
+      require 'disjoint_interval_tree'
+
+      path = Gem.loaded_specs['disjoint_interval_tree'].full_gem_path
+      raise "loaded \#{path}, expected it under #{GEM_DIR}" unless path.start_with?('#{GEM_DIR}')
+
+      tree = DisjointIntervalTree.new([[0, 10], [20, 30]])
+      raise 'unexpected content' unless tree.intersect(5, 25) == [[0, 10], [20, 30]]
+      raise 'unexpected removal' unless tree.remove(5, 25) == 2
+      tree.check!
+
+      puts "installed gem \#{DisjointIntervalTree::VERSION} loads from \#{path}"
+    RUBY
+
+    sh(env, RUBY_BIN, '-Itest', 'test/test_disjoint_interval_tree.rb')
+  end
+
+  desc 'Replay the randomized tests over SEEDS distinct seeds (default 20)'
+  task seeds: :compile do
+    (1..SEEDS).each do |seed|
+      sh('make', '-C', 'test/c', 'debug', "SEED=#{seed}")
+      sh({ 'SEED' => seed.to_s }, RUBY_BIN, '-Ilib', '-Itest',
+         'test/test_disjoint_interval_tree.rb')
+    end
+  end
+
+  # `spec.files` is a `Dir[]` glob over the working tree, so a file that is
+  # gitignored, or simply never added, still ends up in the gem while being
+  # absent from the repository. That asymmetry is silent, and it is how
+  # `test/c/Makefile` - matched by a bare `Makefile` ignore rule - shipped in
+  # the gem but broke every CI job.
+  desc 'Check that every file the gem ships is present and tracked by git'
+  task :files do
+    spec = Gem::Specification.load("#{EXT_NAME}.gemspec")
+    problems = []
+
+    spec.files.sort.each do |path|
+      problems << "#{path}: listed by the gemspec but missing on disk" unless File.exist?(path)
+
+      ignored = !`git check-ignore -- #{path}`.empty?
+      problems << "#{path}: shipped in the gem but matched by .gitignore" if ignored
+
+      tracked = system("git ls-files --error-unmatch -- #{path} > /dev/null 2>&1")
+      problems << "#{path}: shipped in the gem but not tracked by git" if !tracked && !ignored
+    end
+
+    # the repository needs these too, even though the gem does not ship them
+    ['.gitignore', 'Rakefile', '.github/workflows/ci.yml'].each do |path|
+      next if `git check-ignore -- #{path}`.empty?
+
+      problems << "#{path}: matched by .gitignore"
+    end
+
+    unless problems.empty?
+      problems.each { |p| warn "  #{p}" }
+      abort "test:files: #{problems.size} problem(s)"
+    end
+
+    puts "test:files: the #{spec.files.size} files the gem ships are all present and tracked"
+  end
+end
+
+desc 'Run both the C and the ruby test suites'
+task default: ['test:c', :test]
+
+desc 'Run every test suite: C, sanitizers, valgrind, ruby, paranoid, packaged gem, seed sweep'
+task verify: ['test:files', 'test:c', 'test:valgrind', :test, 'test:paranoid', 'test:gem',
+              'test:seeds'] do
+  puts
+  puts "#{EXT_NAME} #{VERSION}: everything passed"
+end
+
+# `gem build` stamps the gem with the current date, which makes it a different
+# file on every run. Pinning SOURCE_DATE_EPOCH to the last commit makes the
+# build byte-reproducible, so the sha256 a downstream packager - spack, nix,
+# a distro - records for a release can be recomputed and checked.
+def source_date_epoch
+  ENV['SOURCE_DATE_EPOCH'] || begin
+    epoch = `git log -1 --format=%ct 2> /dev/null`.strip
+    epoch.empty? ? Time.now.to_i.to_s : epoch
+  end
+end
+
+desc 'Build the gem into pkg/'
+task :build do
+  require 'digest'
+
+  FileUtils.mkdir_p('pkg')
+  sh({ 'SOURCE_DATE_EPOCH' => source_date_epoch }, 'gem', 'build', '--norc', "#{EXT_NAME}.gemspec")
+  FileUtils.mv(FileList["#{EXT_NAME}-*.gem"].to_a, 'pkg', verbose: true)
+
+  puts
+  puts "sha256(#{File.basename(GEM_FILE)}) = #{Digest::SHA256.file(GEM_FILE).hexdigest}"
+  puts 'spack recipe line:'
+  puts %(  version("#{VERSION}", sha256="#{Digest::SHA256.file(GEM_FILE).hexdigest}", expand=False))
+  puts
+end
+
+task gem: :build
+
+desc "Verify, tag and publish v#{DisjointIntervalTree::VERSION} to rubygems.org"
+task :release do
+  abort 'release: the working tree has uncommitted changes' unless `git status --porcelain`.empty?
+
+  branch = `git rev-parse --abbrev-ref HEAD`.strip
+  abort "release: on branch #{branch}, expected main" unless branch == 'main'
+
+  tag = "v#{VERSION}"
+  abort "release: #{tag} already exists" if system("git rev-parse -q --verify refs/tags/#{tag} > /dev/null")
+
+  Rake::Task[:verify].invoke
+
+  sh('git', 'tag', '-a', tag, '-m', "#{EXT_NAME} #{VERSION}")
+  sh('git', 'push', 'origin', 'main', '--follow-tags')
+  sh('gem', 'push', GEM_FILE)
+
+  require 'digest'
+  puts
+  puts "published #{tag}."
+  puts
+  puts 'attach the gem to the github release with:'
+  puts "  gh release create #{tag} #{GEM_FILE} --title #{tag} --generate-notes"
+  puts
+  puts 'and record this in the spack recipe:'
+  puts %(  version("#{VERSION}", sha256="#{Digest::SHA256.file(GEM_FILE).hexdigest}", expand=False))
+end