rbtree-ruby 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc2846050227a83e7ae7bb63d1e6208ed39acc54de759c98e08d994685d1b067
-  data.tar.gz: 2a28105ee3667fb794c1f5d32c396b21542f45bceb3c858c160d7389f6d2ae3b
+  metadata.gz: 56ddd66545f9e423b96066b12deea8e22fc86b35b7a97be056ebf91f80543e77
+  data.tar.gz: 10a3ec88b0a5f5cb199ac96267d7665bfee99ab4fb9cf89488790fe798120b05
 SHA512:
-  metadata.gz: 22239d22c7b771a93bbb1811407d6ea6364ae21b22008d53d44e102188991b7299b6dacdcbc28a206dbfd21658d8081f964bf855b7c69c3d19d3312be49ffe3d
-  data.tar.gz: 8f98487332a3cb77f478f745b775b148aff862ab80fc020d064cade6a84692a4e498854cce864b4d49806a760ee7c6d9c38e4e9ac3e5c7598444ead625e91eb7
+  metadata.gz: 1d521a30299f8c3db327d1b671d84113cf3c9e5adc90a78747e76b7480ef02ceb95d813a90eeebadfd32e4b8360b2d43fffd1ed1ac4d9314d8368cbe137ce7aa
+  data.tar.gz: 445a6cf0a99efdd0b5b4dc41dd86ec219e784cc3a2ecf150b4467e2619bcb08bd9b47d119d1c5310f43fdecdd7dc19941c3bfa4ae9e7b68d2b359819336f0a97

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] - 2026-01-13
+
+### Changed
+- **Iterative Traversal**: Replaced recursive tree traversal with iterative approach
+  - `each`, `reverse_each`, and other traversal methods now use an explicit stack
+  - Prevents `SystemStackError` (stack overflow) on extremely deep trees
+  - Slightly improves iteration performance by removing recursion overhead
+  - Applies to both `RBTree` and `MultiRBTree`
+
+## [0.1.4] - 2026-01-13
+
+### Changed
+- **Memory Pool**: Implemented internal node recycling mechanism
+  - Reuse `RBTree::Node` objects instead of creating new ones for every insertion
+  - Significantly reduces GC pressure during frequent insert/delete operations
+  - Automatically manages pool size (grows on delete, shrinks on insert)
+  - Fully transparent to the user
+
 ## [0.1.3] - 2026-01-13
 
 ### Changed
@@ -59,5 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - ASCII diagrams for tree rotation operations
 - MIT License (Copyright © 2026 Masahito Suzuki)
 
+[0.1.5]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.5
+[0.1.4]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.4
 [0.1.3]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.3
 [0.1.2]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.2

data/README.md

@@ -133,12 +133,47 @@ All major operations run in **O(log n)** time:
 
 - `insert(key, value)` - O(log n)
 - `delete(key)` - O(log n)
-- `get(key)` / `[]` - O(log n)
-- `min` / `max` - O(1) for min, O(log n) for max
+- `get(key)` / `[]` - **O(1)** (hybrid hash index)
+- `has_key?` - **O(1)** (hybrid hash index)
+- `min` - **O(1)**
+- `max` - O(log n)
 - `shift` / `pop` - O(log n)
 
 Iteration over all elements takes O(n) time.
 
+### Memory Efficiency
+
+RBTree uses an internal **Memory Pool** to recycle node objects. 
+- Significantly reduces Garbage Collection (GC) pressure during frequent insertions and deletions (e.g., in high-throughput queues).
+- In benchmarks with 100,000 cyclic operations, **GC time was 0.0s** compared to significant pauses without pooling.
+
+### RBTree vs Hash vs Array
+
+RBTree provides significant advantages for ordered operations:
+
+| Operation | RBTree | Hash | Speedup |
+|-----------|--------|------|---------|
+| `min` / `max` | O(1) / O(log n) | O(n) | **~1000x faster** |
+| Range queries (`between`, `lt`, `gt`) | O(log n + k) | O(n) | **10-100x faster** |
+| Nearest key search | O(log n) | O(n) | **100x+ faster** |
+| Ordered iteration | O(n), always sorted | Requires `sort` O(n log n) | **Free sorting** |
+| Key lookup | O(1) | O(1) | Equal |
+
+### When to Use RBTree
+
+✅ **Use RBTree when you need:**
+- Ordered iteration by key
+- Fast min/max retrieval  
+- Range queries (`between`, `lt`, `gt`, `lte`, `gte`)
+- Nearest key search
+- Priority queue behavior (shift/pop by key order)
+
+✅ **Use Hash when you only need:**
+- Fast key-value lookup (RBTree is now equally fast!)
+- No ordering requirements
+
+Run `ruby demo.rb` for a full benchmark demonstration.
+
 ## API Documentation
 
 Full RDoc documentation is available. Generate it locally with:

data/lib/rbtree/version.rb

@@ -2,5 +2,5 @@
 
 class RBTree
   # The version of the rbtree-ruby gem
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/rbtree.rb

@@ -93,6 +93,7 @@ class RBTree
     @root = @nil_node
     @min_node = @nil_node
     @hash_index = {}  # Hash index for O(1) key lookup
+    @node_pool = []   # Memory pool for recycling nodes
     @size = 0
 
     if args.any?
@@ -188,7 +189,7 @@ class RBTree
         x = x.right
       end
     end
-    z = Node.new(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
+    z = allocate_node(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
     z.parent = y
     if y == @nil_node
       @root = z
@@ -464,10 +465,17 @@ class RBTree
   # @yield [key, value] each key-value pair in ascending order
   # @return [void]
   def traverse_asc(node, &block)
-    return if node == @nil_node
-    traverse_asc(node.left, &block)
-    yield node.key, node.value
-    traverse_asc(node.right, &block)
+    stack = []
+    current = node
+    while current != @nil_node || !stack.empty?
+      while current != @nil_node
+        stack << current
+        current = current.left
+      end
+      current = stack.pop
+      yield current.key, current.value
+      current = current.right
+    end
   end
 
   # Traverses the tree in descending order (reverse in-order traversal).
@@ -476,10 +484,17 @@ class RBTree
   # @yield [key, value] each key-value pair in descending order
   # @return [void]
   def traverse_desc(node, &block)
-    return if node == @nil_node
-    traverse_desc(node.right, &block)
-    yield node.key, node.value
-    traverse_desc(node.left, &block)
+    stack = []
+    current = node
+    while current != @nil_node || !stack.empty?
+      while current != @nil_node
+        stack << current
+        current = current.right
+      end
+      current = stack.pop
+      yield current.key, current.value
+      current = current.left
+    end
   end
 
   # Traverses nodes with keys less than the specified key.
@@ -680,7 +695,9 @@ class RBTree
       @min_node = next_min_node
     end
 
-    z.value
+    value = z.value
+    release_node(z)
+    value
   end
 
   # Restores red-black tree properties after deletion.
@@ -900,6 +917,32 @@ class RBTree
     y.parent = x
   end
 
+  # Allocates a new node or recycles one from the pool.
+  # @return [Node]
+  def allocate_node(key, value, color, left, right, parent)
+    if (node = @node_pool.pop)
+      node.key = key
+      node.value = value
+      node.color = color
+      node.left = left
+      node.right = right
+      node.parent = parent
+      node
+    else
+      Node.new(key, value, color, left, right, parent)
+    end
+  end
+
+  # Releases a node back to the pool.
+  # @param node [Node] the node to release
+  def release_node(node)
+    node.left = nil
+    node.right = nil
+    node.parent = nil
+    node.value = nil # Help GC
+    @node_pool << node
+  end
+
   # Recursively checks black height consistency.
   #
   # Verifies that:
@@ -1024,7 +1067,7 @@ class MultiRBTree < RBTree
         x = x.right
       end
     end
-    z = Node.new(key, [value], Node::RED, @nil_node, @nil_node, @nil_node)
+    z = allocate_node(key, [value], Node::RED, @nil_node, @nil_node, @nil_node)
     z.parent = y
     if y == @nil_node
       @root = z
@@ -1137,17 +1180,31 @@ class MultiRBTree < RBTree
   private
 
   def traverse_asc(node, &block)
-    return if node == @nil_node
-    traverse_asc(node.left, &block)
-    node.value.each { |v| yield node.key, v }
-    traverse_asc(node.right, &block)
+    stack = []
+    current = node
+    while current != @nil_node || !stack.empty?
+      while current != @nil_node
+        stack << current
+        current = current.left
+      end
+      current = stack.pop
+      current.value.each { |v| yield current.key, v }
+      current = current.right
+    end
   end
 
   def traverse_desc(node, &block)
-    return if node == @nil_node
-    traverse_desc(node.right, &block)
-    node.value.reverse_each { |v| yield node.key, v }
-    traverse_desc(node.left, &block)
+    stack = []
+    current = node
+    while current != @nil_node || !stack.empty?
+      while current != @nil_node
+        stack << current
+        current = current.right
+      end
+      current = stack.pop
+      current.value.reverse_each { |v| yield current.key, v }
+      current = current.left
+    end
   end
 
   def traverse_lt(node, key, &block)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Masahito Suzuki