disjoint_interval_tree 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2489f3da4496b1c3abb350eb582d52a40298e61fd9132f52f3ca80e69aeda976
-  data.tar.gz: a3a35b0752910b4ae0e5f2c5aa021bf2175b4ae3545041670ee1fb2f7fe20c96
+  metadata.gz: b89b66e1ed427b22939713e6e3d8cdcaf25b3ea9d5ce352a83fc785a17abde66
+  data.tar.gz: 4885d5e8432c76ce4b8f37c78efdc9981f4815fa9baf60f791e058480aa8ae17
 SHA512:
-  metadata.gz: 8937708e32708573ed399b91722a9ccc1ff8c9d338f6e6655c089a996e4228b0685d653d6b4dd2729e121f384a0a622a0f9cba585475128304633bf80c1830b0
-  data.tar.gz: af0540688e96cc9aa9eebfa5951d4b04aafc04e137b7d7113e959fef4d2621eb81d1a63f7fcbfbbd81d8716cf7fba2d3507e4fc20669265f94fbb2821a7dc163
+  metadata.gz: a4d8ee9fba831a1a78cd10b490c2928236c5f62897f791b86edb7d19f01d5090726eb4842b6a9466ba97637b6213fd4386d2c8401813d577491e5bd92b930f5e
+  data.tar.gz: 3f18cbc6d7ef893b1e41a0027a2a3770e5e1610f51a5d2e729b8517a4bea279549162d8e9873091b38387f0f083a0a451fbdd5ec608fcc813cbcd24b385bf98d

data/README.md

@@ -29,15 +29,16 @@ time.
 require 'disjoint_interval_tree'
 
 tree = DisjointIntervalTree.new
-tree.insert(10, 20)
-tree.insert(30, 40)
+tree.insert(10, 20, 'first')
+tree.insert(30, 40, 'second')
 
-tree.intersect(15, 35) do |a, b|
-  puts "[#{a}..#{b}["
+tree.intersect(15, 35) do |a, b, obj|
+  puts "[#{a}..#{b}[ -> #{obj}"
 end
-# => [10..20[
-# => [30..40[
+# => [10..20[ -> first
+# => [30..40[ -> second
 
+tree[15]              # => "first"
 tree.remove(15, 35)   # => 2
 tree.to_a             # => []
 ```
@@ -52,6 +53,9 @@ tree.to_a             # => []
   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.
+* Every interval carries an **object**, given at insertion and handed back by
+  every query and traversal. It defaults to `nil`, may be anything, and may be
+  shared by several intervals. See [Objects](#objects).
 
 ## Operations
 
@@ -60,13 +64,14 @@ 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)`     |
+| `DisjointIntervalTree.new(intervals = nil)`  | Build an empty tree, or one filled with the given `[a, b]` or `[a, b, obj]` entries.                                      | `O(m.log m)`   |
+| `insert(a, b, obj = nil)`                    | Add `[a..b[` with its object, raising `OverlapError` if it intersects an already stored interval.                         | `O(log n)`     |
+| `insert?(a, b, obj = nil)`                   | 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)`     |
+| `at(x)`                                      | The stored interval containing the point `x` as `[a, b, obj]`, or `nil`.                                                  | `O(log n)`     |
+| `[](x)`                                      | The object of the 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)`         |
@@ -74,35 +79,36 @@ intervals handed to the constructor:
 | `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)`         |
+| `to_a`, `entries`                            | Every stored interval as an array of `[a, b, obj]` triples, 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)`         |
+| `dup`                                        | A copy sharing no node with the original, but sharing its objects.                                                        | `O(n.log n)`   |
+| `==`                                         | Whether two trees hold the same intervals, with objects comparing equal.                                                  | `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
+tree = DisjointIntervalTree.new                           # empty
+tree = DisjointIntervalTree.new([[0, 10], [20, 30, :obj]]) # 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.insert(a, b, obj = nil)  # -> self, raises OverlapError if it overlaps
+tree.insert?(a, b, obj = nil) # -> 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.intersect(a, b) { |x, y, obj| ... }  # -> self, yields increasing order
+tree.intersect(a, b)                      # -> [[x, y, obj], ...] w/o block
 
-tree.remove(a, b)                      # -> number of intervals removed
-tree.remove(a, b) { |x, y| ... }       # ... and yields each removed interval
+tree.remove(a, b)                         # -> number of intervals removed
+tree.remove(a, b) { |x, y, obj| ... }     # ... and yields each removed one
 
 # --- 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.at(x)                   # -> [a, b, obj] containing the point x, or nil
+tree[x]                      # -> the object of that interval, 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
@@ -111,15 +117,15 @@ 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.each { |a, b, obj| ... }
+tree.to_a                    # -> [[a, b, obj], ...], in increasing order
 tree.map { |a, b| b - a }
 tree.coverage                # -> total length covered
 
 # --- misc -----------------------------------------------------------------
 
 tree.clear                   # -> self
-tree.dup                     # -> deep copy
+tree.dup                     # -> copy, sharing the objects
 tree == other
 tree.check!                  # -> self, raises CorruptedError if an invariant
                              #    of the underlying tree is broken
@@ -133,6 +139,37 @@ 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.
 
+## Objects
+
+Every interval carries an object. It is given as the third argument of
+`insert`, defaults to `nil`, and comes back - by identity, never copied - from
+every query and traversal:
+
+```ruby
+tree = DisjointIntervalTree.new
+tree.insert(4096, 8192, Allocation.new(:device))
+
+tree[6000]        # => #<Allocation device>   the object at that address
+tree.at(6000)     # => [4096, 8192, #<Allocation device>]
+tree.intersect(6000, 12288) { |a, b, alloc| alloc.report(a, b) }
+tree.remove(6000, 12288) { |_a, _b, alloc| alloc.release }
+```
+
+* Any object is accepted, `nil` included, and several intervals may share one.
+* `tree[x]` returns `nil` both when no interval covers `x` and when the
+  covering interval holds a `nil` object. Use `at(x)` or `cover?(x)` to tell
+  the two apart.
+* The tree holds a **strong reference**: an object stays alive as long as its
+  interval is in the tree, and becomes collectable as soon as `remove` or
+  `clear` drops it.
+* `dup` is **shallow**: the copy shares the very same objects.
+* A compacting GC may move the objects: the tree updates its references
+  accordingly, so identity is preserved across `GC.compact`.
+
+In C the object is a plain `void *` that the tree only ever stores and hands
+back - it never reads, copies nor frees it. Pass a callback to `dit_remove()`
+to reclaim objects as their intervals go away.
+
 ## C API
 
 The Ruby extension is a thin binding over a standalone, dependency-free C
@@ -142,21 +179,30 @@ 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)
+static int print_cb(dit_value_t a, dit_value_t b, dit_object_t obj, void * user)
 {
     (void) user;
-    printf("[%lu..%lu[\n", a, b);
+    printf("[%lu..%lu[ -> %s\n", a, b, (const char *) obj);
     return 0;   /* non-zero stops the traversal */
 }
 
+static int free_cb(dit_value_t a, dit_value_t b, dit_object_t obj, void * user)
+{
+    (void) a; (void) b; (void) user;
+    free(obj);
+    return 0;
+}
+
 dit_t tree;
 dit_init(&tree);
 
-if (dit_insert(&tree, 0, 10) != DIT_OK)
+if (dit_insert(&tree, 0, 10, strdup("payload")) != DIT_OK)
     { /* DIT_EMPTY, DIT_OVERLAP or DIT_NOMEM */ }
 
 dit_intersect(&tree, 5, 25, print_cb, NULL);
-dit_remove(&tree, 5, 25);
+
+/* the callback is optional, and lets the caller reclaim the objects */
+dit_remove(&tree, 5, 25, free_cb, NULL);
 
 dit_destroy(&tree);
 ```
@@ -191,6 +237,7 @@ Customization points, to define before including `dit.h`:
 | macro           | default                | purpose                                         |
 | --------------- | ---------------------- | ----------------------------------------------- |
 | `DIT_VALUE_T`   | `uint64_t`             | interval bound type                              |
+| `DIT_OBJECT_T`  | `void *`               | type of the object associated with each interval |
 | `DIT_ASSERT`    | `assert`               | internal consistency assertions                  |
 | `DIT_MALLOC`    | `malloc` / `free`      | node allocation                                  |
 | `DIT_PARANOID`  | `0`                    | run `dit_check()` after every mutation           |
@@ -216,6 +263,12 @@ 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, ...).
 
+Objects are opaque, so no invariant can be derived from them and `dit_check()`
+says nothing about them. Both test suites cover that blind spot instead, by
+storing in every interval an object derived from its lower bound and checking
+it on each reported interval - which is what pins down the one place an object
+could be left behind, the deletion of a node with two children.
+
 ## Building and testing
 
 Building the extension needs the ruby development headers (`ruby-dev` /

data/Rakefile

@@ -20,10 +20,18 @@ NPROC     = Etc.respond_to?(:nprocessors) ? Etc.nprocessors : 4
 VERSION   = DisjointIntervalTree::VERSION
 GEM_FILE  = File.expand_path("pkg/#{EXT_NAME}-#{VERSION}.gem", __dir__)
 
+# `lib/` holds a single .so, but a C extension only ever works with the ruby
+# ABI it was compiled against: switching ruby - system, spack, rbenv, a CI
+# matrix - has to force a rebuild. Loading the wrong one is not a clean
+# failure, it corrupts memory and crashes somewhere else entirely.
+BUILD_ID_PATH = File.join(LIB_DIR, '.build-id')
+BUILD_ID      = [RUBY_ENGINE, RbConfig::CONFIG['ruby_version'], RUBY_PLATFORM,
+                 (ENV['EXTOPTS'] || '')].join(' ')
+
 SOURCES = FileList["#{EXT_DIR}/*.c", "#{EXT_DIR}/*.h", "#{EXT_DIR}/extconf.rb"]
 
 CLEAN.include('tmp')
-CLOBBER.include(SO_PATH, 'pkg')
+CLOBBER.include(SO_PATH, BUILD_ID_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
@@ -37,6 +45,37 @@ EXTOPTS = (ENV['EXTOPTS'] || '').split
 directory BUILD_DIR
 directory LIB_DIR
 
+# Building needs the ruby development headers. Without them mkmf fails deep in
+# the build log with a message about the wrong directory, so say it up front.
+task :check_headers do
+  header = File.join(RbConfig::CONFIG['rubyhdrdir'].to_s, 'ruby.h')
+  next if File.exist?(header)
+
+  abort <<~MSG
+    #{RUBY_BIN} has no development headers (no #{header}).
+
+    Install them, or build with a ruby that has them:
+      debian/ubuntu : sudo apt install ruby-dev
+      spack         : spack load ruby
+  MSG
+end
+
+# Drop an extension built by another ruby rather than letting it be loaded
+task check_build_id: [LIB_DIR, :check_headers] do
+  next if File.exist?(BUILD_ID_PATH) && File.read(BUILD_ID_PATH) == BUILD_ID
+
+  if File.exist?(SO_PATH)
+    puts "#{SO_NAME} was built by another ruby (#{begin
+      File.read(BUILD_ID_PATH)
+    rescue StandardError
+      'unknown'
+    end}), rebuilding for #{BUILD_ID}"
+  end
+
+  FileUtils.rm_f(SO_PATH)
+  File.write(BUILD_ID_PATH, BUILD_ID)
+end
+
 file SO_PATH => SOURCES + [BUILD_DIR, LIB_DIR] do
   Dir.chdir(BUILD_DIR) do
     sh(RUBY_BIN, File.join(EXT_DIR, 'extconf.rb'), *EXTOPTS)
@@ -45,16 +84,21 @@ file SO_PATH => SOURCES + [BUILD_DIR, LIB_DIR] do
   FileUtils.cp(File.join(BUILD_DIR, SO_NAME), SO_PATH, verbose: true)
 end
 
+# The checks come first, as prerequisites rather than as prerequisites of
+# SO_PATH itself: a basic rake task timestamps as `Time.now`, so depending on
+# one would make the file task look out of date on every single run
 desc 'Build the C extension'
-task compile: SO_PATH
+task compile: [:check_headers, :check_build_id, 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[:check_headers].invoke
   Rake::Task[:clean].invoke
   FileUtils.rm_f(SO_PATH)
   [BUILD_DIR, LIB_DIR, SO_PATH].each { |t| Rake::Task[t].reenable }
+  Rake::Task[:check_build_id].invoke
   Rake::Task[SO_PATH].invoke
 end
 
@@ -110,8 +154,9 @@ namespace :test do
       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]]
+      tree = DisjointIntervalTree.new([[0, 10, :first], [20, 30]])
+      raise 'unexpected content' unless tree.intersect(5, 25) == [[0, 10, :first], [20, 30, nil]]
+      raise 'unexpected object' unless tree[5] == :first
       raise 'unexpected removal' unless tree.remove(5, 25) == 2
       tree.check!
 

data/ext/disjoint_interval_tree/dit.c

@@ -107,7 +107,7 @@ dit_node_refresh_augment(dit_node_t * node)
 }
 
 static inline dit_node_t *
-dit_node_new(dit_value_t a, dit_value_t b)
+dit_node_new(dit_value_t a, dit_value_t b, dit_object_t obj)
 {
     DIT_ASSERT(a < b);
 
@@ -117,6 +117,7 @@ dit_node_new(dit_value_t a, dit_value_t b)
 
     node->a              = a;
     node->b              = b;
+    node->obj            = obj;
     node->left           = NULL;
     node->right          = NULL;
     node->augment.hull.a = a;
@@ -304,22 +305,23 @@ dit_insert_from(
     dit_node_t * node,
     dit_value_t a,
     dit_value_t b,
+    dit_object_t obj,
     dit_status_t * status
 ) {
     if (node == NULL)
     {
-        dit_node_t * created = dit_node_new(a, b);
+        dit_node_t * created = dit_node_new(a, b, obj);
         *status = created ? DIT_OK : DIT_NOMEM;
         return created;
     }
 
     /* case (1) - [a..b[ entirely before this node */
     if (b <= node->a)
-        node->left = dit_insert_from(node->left, a, b, status);
+        node->left = dit_insert_from(node->left, a, b, obj, status);
 
     /* case (2) - [a..b[ entirely after this node */
     else if (a >= node->b)
-        node->right = dit_insert_from(node->right, a, b, status);
+        node->right = dit_insert_from(node->right, a, b, obj, status);
 
     /* case (3) - contract violation, [a..b[ intersect this node */
     else
@@ -338,7 +340,7 @@ dit_insert_from(
 }
 
 dit_status_t
-dit_insert(dit_t * tree, dit_value_t a, dit_value_t b)
+dit_insert(dit_t * tree, dit_value_t a, dit_value_t b, dit_object_t obj)
 {
     DIT_ASSERT(tree);
     DIT_ASSERT(tree->traversing == 0 && "cannot mutate the tree while traversing it");
@@ -347,7 +349,7 @@ dit_insert(dit_t * tree, dit_value_t a, dit_value_t b)
         return DIT_EMPTY;
 
     dit_status_t status = DIT_OK;
-    dit_node_t * root = dit_insert_from(tree->root, a, b, &status);
+    dit_node_t * root = dit_insert_from(tree->root, a, b, obj, &status);
 
     if (status != DIT_OK)
         return status;
@@ -385,6 +387,37 @@ dit_intersecting_from(dit_node_t * node, dit_value_t a, dit_value_t b)
     return NULL;
 }
 
+/* Same, but always returning the *smallest* such interval. It cannot stop as
+ * soon as it finds a match, so it always walks a full root-to-leaf path -
+ * still O(log n), just without the early exit */
+static inline dit_node_t *
+dit_leftmost_intersecting_from(dit_node_t * node, dit_value_t a, dit_value_t b)
+{
+    dit_node_t * leftmost = NULL;
+
+    /* leftmost node ending after `a`. Intervals being disjoint and ordered,
+     * those intersecting [a..b[ form a contiguous run, so that node is the
+     * first of the run - when it starts before `b` */
+    while (node)
+    {
+        if (node->b > a)
+        {
+            leftmost = node;
+            node = node->left;
+        }
+        else
+            node = node->right;
+    }
+
+    if (leftmost && leftmost->a < b)
+    {
+        DIT_ASSERT(DIT_INTERSECTS(a, b, leftmost->a, leftmost->b));
+        return leftmost;
+    }
+
+    return NULL;
+}
+
 const dit_node_t *
 dit_intersecting(const dit_t * tree, dit_value_t a, dit_value_t b)
 {
@@ -440,7 +473,7 @@ dit_intersect_from(
 
     if (DIT_INTERSECTS(a, b, node->a, node->b))
     {
-        if ((r = cb(node->a, node->b, user)) != 0)
+        if ((r = cb(node->a, node->b, node->obj, user)) != 0)
             return r;
     }
 
@@ -476,7 +509,7 @@ dit_each_from(dit_node_t * node, dit_cb_t cb, void * user)
     if ((r = dit_each_from(node->left, cb, user)) != 0)
         return r;
 
-    if ((r = cb(node->a, node->b, user)) != 0)
+    if ((r = cb(node->a, node->b, node->obj, user)) != 0)
         return r;
 
     return dit_each_from(node->right, cb, user);
@@ -545,15 +578,20 @@ dit_remove_from(dit_node_t * node, dit_value_t key)
         }
 
         /* two children: replace the interval with its in-order successor's,
-         * then remove that successor from the right subtree */
+         * then remove that successor from the right subtree.
+         *
+         * The object travels with the interval it belongs to: forgetting it
+         * here would silently hand the successor's interval the object of the
+         * node being deleted */
         dit_node_t * successor;
         node->right = dit_detach_min(node->right, &successor);
 
         DIT_ASSERT(successor && successor->left == NULL);
         DIT_ASSERT(node->a < successor->a);
 
-        node->a = successor->a;
-        node->b = successor->b;
+        node->a   = successor->a;
+        node->b   = successor->b;
+        node->obj = successor->obj;
 
         DIT_FREE(successor);
     }
@@ -563,7 +601,7 @@ dit_remove_from(dit_node_t * node, dit_value_t key)
 }
 
 size_t
-dit_remove(dit_t * tree, dit_value_t a, dit_value_t b)
+dit_remove(dit_t * tree, dit_value_t a, dit_value_t b, dit_cb_t cb, void * user)
 {
     DIT_ASSERT(tree);
     DIT_ASSERT(tree->traversing == 0 && "cannot mutate the tree while traversing it");
@@ -573,13 +611,23 @@ dit_remove(dit_t * tree, dit_value_t a, dit_value_t b)
 
     size_t n = 0;
 
-    /* each iteration is a O(log n) descent plus a O(log n) deletion */
+    /* each iteration is a O(log n) descent plus a O(log n) deletion. Removing
+     * the smallest match every time reports them in increasing order */
     for (;;)
     {
-        dit_node_t * node = dit_intersecting_from(tree->root, a, b);
+        dit_node_t * node = dit_leftmost_intersecting_from(tree->root, a, b);
         if (node == NULL)
             break ;
 
+        if (cb)
+        {
+            /* the callback may read the tree, but not mutate it: it would
+             * free the very node about to be deleted */
+            tree->traversing += 1;
+            cb(node->a, node->b, node->obj, user);
+            tree->traversing -= 1;
+        }
+
         tree->root = dit_remove_from(tree->root, node->a);
 
         DIT_ASSERT(tree->n > 0);
@@ -821,6 +869,7 @@ dit_dump_dot_from(const dit_node_t * node, FILE * f)
 
     fprintf(f, "    N%p[shape=record, label=\"{[%" DIT_VALUE_FMT "..%" DIT_VALUE_FMT "[",
             (const void *) node, node->a, node->b);
+    fprintf(f, "|obj %p", (const void *) (uintptr_t) node->obj);
     fprintf(f, "|hull [%" DIT_VALUE_FMT "..%" DIT_VALUE_FMT "[",
             node->augment.hull.a, node->augment.hull.b);
     fprintf(f, "|h=%d, n=%u}\"] ;\n", (int) node->augment.height, node->augment.size);

data/ext/disjoint_interval_tree/dit.h

@@ -34,6 +34,12 @@
 **      insertion descent: `DIT_OVERLAP` is returned and the tree is left
 **      untouched.
 **
+**  Objects
+**      Every interval carries an opaque object, given at insertion and handed
+**      back by every query and traversal. The tree never owns it: it only
+**      stores the value, and never reads, copies nor releases whatever it
+**      points to. See `dit_remove()` to reclaim objects as intervals go away.
+**
 **  Complexities, with `n` intervals stored and `k` intervals reported
 **      dit_insert      O(log n)
 **      dit_intersect   O(k + log n)
@@ -65,6 +71,15 @@ extern "C" {
 
 typedef DIT_VALUE_T dit_value_t;
 
+/* Type of the object associated with each interval. It is opaque to the tree,
+ * which only ever stores and hands it back */
+# ifndef DIT_OBJECT_T
+#  define DIT_OBJECT_T      void *
+#  define DIT_OBJECT_NULL   ((dit_object_t) NULL)
+# endif /* DIT_OBJECT_T */
+
+typedef DIT_OBJECT_T dit_object_t;
+
 /* Internal consistency assertions. Those only ever fire on a dit bug, never on
  * a caller mistake - caller mistakes are reported through `dit_status_t`.
  * Define `DIT_ASSERT` to override, or `NDEBUG` to compile them out */
@@ -139,6 +154,10 @@ typedef struct  dit_node_s
     /* the interval [a..b[ represented by this node, with a < b */
     dit_value_t a, b;
 
+    /* the object associated with that interval, as given to `dit_insert()`.
+     * Opaque to the tree, which never dereferences nor releases it */
+    dit_object_t obj;
+
     /* children - `child[DIT_LEFT]` holds intervals entirely before `a`,
      * `child[DIT_RIGHT]` holds intervals entirely after `b` */
     union {
@@ -166,15 +185,18 @@ typedef struct  dit_s
 }               dit_t;
 
 /* Interval callback.
- * `[a..b[` is the stored interval, `user` the opaque pointer given to the
- * traversal. Return 0 to keep going, non-zero to stop the traversal early -
- * that value is then returned by the traversal routine */
-typedef int (*dit_cb_t)(dit_value_t a, dit_value_t b, void * user);
+ * `[a..b[` is the stored interval and `obj` its associated object, while
+ * `user` is the opaque pointer given to the traversal. Return 0 to keep going,
+ * non-zero to stop the traversal early - that value is then returned by the
+ * traversal routine */
+typedef int (*dit_cb_t)(dit_value_t a, dit_value_t b, dit_object_t obj, void * user);
 
 /* Initialize an empty tree. `dit_t` may also be zero-initialized */
 void dit_init(dit_t * tree);
 
-/* Free every node. The tree is left initialized and empty */
+/* Free every node. The tree is left initialized and empty.
+ * Objects are *not* released: walk the tree with `dit_each()` first if they
+ * need to be reclaimed */
 void dit_clear(dit_t * tree);
 
 /* Alias of `dit_clear()`, for symmetry with `dit_init()` */
@@ -194,11 +216,11 @@ int dit_height(const dit_t * tree);
  * untouched when the tree is empty. O(1) */
 int dit_hull(const dit_t * tree, dit_value_t * a, dit_value_t * b);
 
-/* Insert `[a..b[`.
+/* Insert `[a..b[`, associated with the object `obj`.
  * Returns DIT_OK, DIT_EMPTY if `a >= b`, DIT_OVERLAP if `[a..b[` intersects an
  * already inserted interval, DIT_NOMEM on allocation failure. The tree is left
  * unchanged unless DIT_OK is returned */
-dit_status_t dit_insert(dit_t * tree, dit_value_t a, dit_value_t b);
+dit_status_t dit_insert(dit_t * tree, dit_value_t a, dit_value_t b, dit_object_t obj);
 
 /* Return the stored interval intersecting `[a..b[`, or NULL if there is none.
  * If several intervals intersect `[a..b[`, which one is returned is
@@ -223,8 +245,13 @@ int dit_each(dit_t * tree, dit_cb_t cb, void * user);
 
 /* Remove every stored interval intersecting `[a..b[`. Returns how many
  * intervals were removed. Removed intervals are removed as a whole: an
- * interval merely overlapping `[a..b[` is *not* split */
-size_t dit_remove(dit_t * tree, dit_value_t a, dit_value_t b);
+ * interval merely overlapping `[a..b[` is *not* split.
+ *
+ * `cb`, when not NULL, is invoked on each interval just before its node is
+ * freed, so that its object can be reclaimed. It is called in increasing
+ * order, must not mutate the tree, and - unlike a traversal callback - its
+ * return value is ignored: a removal cannot be interrupted halfway */
+size_t dit_remove(dit_t * tree, dit_value_t a, dit_value_t b, dit_cb_t cb, void * user);
 
 /* Verify every structural invariant of the tree.
  * Returns 0 if the tree is coherent. Otherwise returns a non-zero value and,