rbtree-ruby 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59400faa90822b08dbe1fc115c6bf28f526b4e139924e1950f625ac552f5124c
-  data.tar.gz: 3f7bda0222388236a6b9f0b8fc4e8fef0cc5e365b1b98eddceef73ec3c1d8114
+  metadata.gz: 3d5898bb2e8aaea4617747c5f4024ab023a1afeabba3abafeaf2b86bb6afa986
+  data.tar.gz: c6651a33b8e66ee3528dc8ab3abf2359f3e2647fc27491e8bd5083ef08844d77
 SHA512:
-  metadata.gz: b2207668d8974b8af9e0261c819d3a63f537b557d9f1188799026524d27dd23703f020fb3ce397047bd6b9434cc3f079e42e68152f33fa9bd69ede97b4e66530
-  data.tar.gz: 593e5575adb4755b6a2212144ca56920918fe31a5a0b048e37655b5729216ee4bfe3f3ae43f5477ec2c8b9e0d2e1cf2ef4dca5df1208f757fef85a643c9b1c7d
+  metadata.gz: e7d1619486160150a91842631953842f3bddcb90213d415ec9aaca846184220ada9494cdae1eadf05ae5d523c5646b1ce19590d0b60c9df8ddd0c0f01a40ede7
+  data.tar.gz: ed2f20ab619e64c6daf16f4484fc52b0bc724e3b9b0f8b08c3a61921cbde5077f99beace823afbf3133c74ab3dfd838b48c5b09392bcaaee4fc0a930eb507589

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.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
+- **Hybrid Hash Index**: Added internal `@hash_index` for O(1) key lookup
+  - `get(key)` and `has_key?(key)` now use hash lookup instead of tree traversal
+  - Search performance now matches Hash (within 10-20% overhead)
+  - Benchmark: 10M elements, 1M lookups - RBTree 290ms vs Hash 271ms
+  - Both RBTree and MultiRBTree benefit from this optimization
+  - Memory trade-off: ~1.5x due to hash index storage
+
 ## [0.1.2] - 2026-01-13
 
 ### Changed
@@ -49,4 +68,6 @@ 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.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.2"
+  VERSION = "0.1.4"
 end

data/lib/rbtree.rb

@@ -92,6 +92,8 @@ class RBTree
     @nil_node.right = @nil_node
     @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?
@@ -139,7 +141,7 @@ class RBTree
   #   tree.has_key?(1)  # => true
   #   tree.has_key?(3)  # => false
   def has_key?(key)
-    find_node(key) != @nil_node
+    @hash_index.key?(key)
   end
 
   # Retrieves the value associated with the given key.
@@ -152,8 +154,7 @@ class RBTree
   #   tree[2]      # => "two"
   #   tree[3]      # => nil
   def get(key)
-    n = find_node(key)
-    n == @nil_node ? nil : n.value
+    @hash_index[key]&.value
   end
   alias_method :[], :get
 
@@ -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
@@ -207,6 +208,7 @@ class RBTree
       @min_node = z
     end
     
+    @hash_index[key] = z  # Add to hash index
     true
   end
   alias_method :[]=, :insert
@@ -232,6 +234,7 @@ class RBTree
   def clear
     @root = @nil_node
     @min_node = @nil_node
+    @hash_index.clear
     @size = 0
     self
   end
@@ -622,8 +625,8 @@ class RBTree
   # @param key [Object] the key to delete
   # @return [Object, nil] the value of the deleted node, or nil if not found
   def delete_node(key)
-    z = find_node(key)
-    return nil if z == @nil_node
+    z = @hash_index.delete(key)  # O(1) lookup and remove from index
+    return nil unless z
     remove_node(z)
   end
 
@@ -678,7 +681,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.
@@ -898,6 +903,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:
@@ -936,12 +967,12 @@ end
 # A Multi Red-Black Tree that allows duplicate keys.
 #
 # MultiRBTree extends RBTree to support multiple values per key. Each key maps to
-# a linked list of values rather than a single value. The size reflects the total
+# an array of values rather than a single value. The size reflects the total
 # number of key-value pairs (not unique keys).
 #
 # == Features
 #
-# * Multiple values per key using linked lists
+# * Multiple values per key using arrays
 # * Separate methods for single deletion (`delete_one`) vs. all deletions (`delete`)
 # * Values for each key maintain insertion order
 # * min/max return first/last values respectively
@@ -1022,7 +1053,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
@@ -1041,6 +1072,7 @@ class MultiRBTree < RBTree
       @min_node = z
     end
     
+    @hash_index[key] = z  # Add to hash index
     true
   end
 
@@ -1058,12 +1090,13 @@ class MultiRBTree < RBTree
   #   tree.delete_one(1)  # => "first"
   #   tree.get(1)         # => "second"
   def delete_one(key)
-    z = find_node(key)
-    return nil if z == @nil_node
+    z = @hash_index[key]  # O(1) lookup
+    return nil unless z
 
     value = z.value.shift
     @size -= 1
     if z.value.empty?
+      @hash_index.delete(key)  # Remove from index when node removed
       remove_node(z)
     end
     value
@@ -1082,8 +1115,8 @@ class MultiRBTree < RBTree
   #   vals = tree.delete(1)  # removes both values
   #   vals.size  # => 2
   def delete(key)
-    z = find_node(key)
-    return nil if z == @nil_node
+    z = @hash_index.delete(key)  # O(1) lookup and remove from index
+    return nil unless z
     
     count = z.value.size
     remove_node(z)
@@ -1257,4 +1290,3 @@ class RBTree::Node
   # @return [Boolean] true if black, false otherwise
   def black? = @color == BLACK
 end
-

metadata

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