rbtree-ruby 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8aaee3fedf309a0079082fa38c10e3748bc68873131800e13f30dee1202273
-  data.tar.gz: 5e6dd162b0ebb1b50929d9127c4ac57598c7391ecf63a7d1dca7e42107d4ca3a
+  metadata.gz: 327862d13e55ed6406023e1d10676e4b5e94541c59400d9205380af08822e4bf
+  data.tar.gz: 465e1a514390286bf0165db4dfa9f25ada4cd3d1410b0115b11eba15b03dcf33
 SHA512:
-  metadata.gz: c1df7b56cad01d4a0725668f415510a3e65fd6409a0271143504ec1223d64a7e395a93a1dbd43881ceb75e5a36ea9328f60e86e95cdfcde653ab075fab81cb7b
-  data.tar.gz: cecad1db1c9fba3eb4c91b20493dc849cfbf70f8d2e1fede1c09e8b22d59d925e724e26788e06627a02b620de42c655afef4a8be51d31fdeaff5fa5158a2d192
+  metadata.gz: 1f354523b8fb78b746cf256949887b89184ce1dcd190403a7024949cded391de24ce6f932720a58ae24592b4b453f3901b1896c9904f546aa03fe4b1524698c2
+  data.tar.gz: e1219a20ea771f3fe1ca2fc160d737c787a1a0e81cb5389b63f320dcd1d2ac9d2cc71d9df2b9698d73afc98069f76d39285ca8106691f0025f1d5a5fa8b6bf91

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.3.2] - 2026-01-15
+
+### Added
+- **Custom Node Allocator**: `RBTree#initialize` now accepts a `node_allocator:` keyword argument, allowing customization of the node pooling strategy.
+- **AutoShrinkNodePool**: Introduced `RBTree::AutoShrinkNodePool` as the default allocator. It automatically releases memory back to the GC when the pool size exceeds the fluctuation range of recent active node counts, preventing memory bloat in long-running processes with variable loads.
+- **Explicit Overwrite**: `overwrite: true` is now the explicit default for `initialize` and `insert`.
+
 ## [0.3.1] - 2026-01-15
 
 ### Added
@@ -191,6 +198,8 @@ 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.3.2]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.2
+[0.3.1]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.1
 [0.3.0]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.0
 [0.2.3]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.2.3
 [0.2.2]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.2.2

data/README.ja.md

@@ -236,12 +236,6 @@ tree.max(last: true)      # => [2, "b"]      (最大キーの最後の値)
 
 全要素のイテレーションはO(n)時間。
 
-### メモリ効率
-
-RBTreeは内部的な**メモリプール**を使用してノードオブジェクトを再利用:
-- 頻繁な挿入・削除時のGC負荷を大幅に削減
-- 100,000回の循環操作ベンチマークで**GC時間0.0秒**を達成
-
 ### RBTree vs Hash vs Array
 
 順序付き操作と空間的操作において、RBTreeは単に速いだけでなく、全く異なるクラスの性能を発揮。**50万件**でのベンチマーク:
@@ -254,6 +248,23 @@ RBTreeは内部的な**メモリプール**を使用してノードオブジェ
 | **ソート済みイテレーション** | **O(n)** | O(n log n) | **無料** | 常にソート済み vs 明示的な`sort` |
 | **キー検索** | **O(1)** | O(1) | **同等** | **ハイブリッドハッシュインデックスにより、Hashと同等のO(1)検索速度を実現** |
 
+### メモリ効率とカスタムアロケータ
+
+RBTreeは内部的な**メモリプール**を使用してノードオブジェクトを再利用します。
+- 頻繁な挿入・削除時のGC負荷を大幅に削減します。
+- **自動縮小**: デフォルトの `AutoShrinkNodePool` は、現在の使用量に対してプールが大きくなりすぎた場合、自動的に未使用ノードをRubyのGCに解放します。これにより、負荷が変動する長時間実行アプリケーションでのメモリ肥大化を防ぎます。
+- **カスタマイズ**: プールの動作をカスタマイズしたり、独自のアロケータを指定することができます:
+
+```ruby
+# 自動縮小パラメータのカスタマイズ
+pool = RBTree::AutoShrinkNodePool.new(
+  history_size: 60,       # 60秒の履歴
+  buffer_factor: 1.5,     # 変動幅の50%をバッファとして保持
+  reserve_ratio: 0.2      # 常に最大値の20%を予備として保持
+)
+tree = RBTree.new(node_allocator: pool)
+```
+
 ### RBTreeを使うべき場面
 
 ✅ **RBTreeが適している場合:**

data/README.md

@@ -236,12 +236,6 @@ All major operations run in **O(log n)** time:
 
 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 (Overwhelming Power)
 
 For ordered and spatial operations, RBTree is not just faster—it is in a completely different class. The following benchmarks were conducted with **500,000 items**:
@@ -254,6 +248,23 @@ For ordered and spatial operations, RBTree is not just faster—it is in a compl
 | **Sorted Iteration** | **O(n)** | O(n log n) | **FREE** | Always sorted vs explicit `sort` |
 | **Key Lookup** | **O(1)** | O(1) | **Equal** | **Hybrid Hash Index provides O(1) access like standard Hash** |
 
+### Memory Efficiency & Custom Allocators
+
+RBTree uses an internal **Memory Pool** to recycle node objects. 
+- Significantly reduces Garbage Collection (GC) pressure during frequent insertions and deletions.
+- **Auto-Shrinking**: The default `AutoShrinkNodePool` automatically releases unused nodes back to Ruby's GC when the pool gets too large relative to current usage, preventing memory leaks in long-running applications with fluctuating workloads.
+- **Customization**: You can customize the pool behavior or provide your own allocator:
+
+```ruby
+# Customize auto-shrink parameters
+pool = RBTree::AutoShrinkNodePool.new(
+  history_size: 60,       # 1 minute history
+  buffer_factor: 1.5,     # Keep 50% buffer above fluctuation
+  reserve_ratio: 0.2      # Always keep 20% reserve
+)
+tree = RBTree.new(node_allocator: pool)
+```
+
 ### When to Use RBTree
 
 ✅ **Use RBTree when you need:**

data/lib/rbtree/version.rb

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

data/lib/rbtree.rb

@@ -77,6 +77,7 @@ class RBTree
   #
   # @param args [Hash, Array, nil] optional initial data
   # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @param node_allocator [NodeAllocator] allocator instance to use (default: AutoShrinkNodePool.new)
   # @yieldreturn [Object] optional initial data
   #   - If a Hash is provided, each key-value pair is inserted into the tree
   #   - If an Array is provided, it should contain [key, value] pairs
@@ -91,7 +92,7 @@ class RBTree
   #   tree = RBTree.new([[1, 'one'], [2, 'two']])
   # @example Create with overwrite: false
   #   tree = RBTree.new([[1, 'one'], [1, 'uno']], overwrite: false)
-  def initialize(*args, overwrite: true, &block)
+  def initialize(*args, overwrite: true, node_allocator: AutoShrinkNodePool.new, &block)
     @nil_node = Node.new
     @nil_node.color = Node::BLACK
     @nil_node.left = @nil_node
@@ -99,9 +100,11 @@ 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
+    @node_allocator = node_allocator
     @key_count = 0
 
+    @overwrite = overwrite
+
     if args.size > 0 || block_given?
       insert(*args, overwrite: overwrite, &block)
     end
@@ -303,7 +306,7 @@ class RBTree
   #   tree.insert({1 => 'one', 2 => 'two'})
   # @example Bulk insert from Array
   #   tree.insert([[1, 'one'], [2, 'two']])
-  def insert(*args, overwrite: true, &block)
+  def insert(*args, overwrite: @overwrite, &block)
     if args.size == 2
       key, value = args
       insert_entry(key, value, overwrite: overwrite)
@@ -1326,30 +1329,17 @@ class RBTree
   # Allocates a new node or recycles one from the pool.
   # @return [Node]
   def allocate_node(key, value, color, left, right, parent)
-    node = @node_pool.pop
-    if node
-      node.key = key
-      node.value = value
-      node.color = color
-      node.left = left
-      node.right = right
-      node.parent = parent
-      node
-    else
-      node = Node.new(key, value, color, left, right, parent)
-    end
+    node = @node_allocator.allocate(key, value, color, left, right, parent)
     @key_count += 1
     node
   end
 
+  # Releases a node back to the pool.
+  # @param node [Node] the node to release
   # 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
+    @node_allocator.release(node)
     @key_count -= 1
   end
 
@@ -1790,3 +1780,203 @@ class RBTree::Node
   # @return [Array(Object, Object)] the key-value pair
   def pair = [key, value]
 end
+
+# Allocator for RBTree nodes.
+#
+# @api private
+class RBTree::NodeAllocator
+  # Allocates a new node.
+    #
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @param color [Boolean] the color (true=red, false=black)
+  # @param left [Node] the left child
+  # @param right [Node] the right child
+  # @param parent [Node] the parent node
+  def allocate(key, value, color, left, right, parent) = RBTree::Node.new(key, value, color, left, right, parent)
+
+  # Releases a node.
+  #
+  # @param node [Node] the node to release
+  def release(node) = nil
+end
+
+# Internal node pool for RBTree.
+#
+# Manages recycling of Node objects to reduce object allocation overhead.
+#
+# @api private
+class RBTree::NodePool < RBTree::NodeAllocator
+  def initialize
+    @pool = []
+  end
+
+  # Allocates a new node or recycles one from the pool.
+  #
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @param color [Boolean] the color (true=red, false=black)
+  # @param left [Node] the left child
+  # @param right [Node] the right child
+  # @param parent [Node] the parent node
+  def allocate(key, value, color, left, right, parent)
+    node = @pool.pop
+    if node
+      node.key = key
+      node.value = value
+      node.color = color
+      node.left = left
+      node.right = right
+      node.parent = parent
+      node
+    else
+      super
+    end
+  end
+
+  # Releases a node back to the pool.
+  #
+  # @param node [Node] the node to release
+  def release(node)
+    node.left = node.right = node.parent = node.value = node.key = nil
+    @pool << node
+  end
+end
+
+# Internal node pool for RBTree.
+#
+# Manages recycling of Node objects to reduce object allocation overhead.
+# Includes an auto-shrink mechanism to release memory back to GC when
+# the pool size exceeds the fluctuation range of recent active node count.
+#
+# This class can be used to customize the node allocation strategy by passing
+# an instance to {RBTree#initialize}.
+class RBTree::AutoShrinkNodePool < RBTree::NodePool
+  # Initializes a new AutoShrinkNodePool.
+  #
+  # @param max_maintenance_interval [Integer] maximum interval between maintenance checks (default: 1000)
+  # @param target_check_interval [Float] target interval in seconds for maintenance checks (default: 1.0)
+  # @param history_size [Integer] duration in seconds to keep history for fluctuation analysis (default: 120)
+  # @param buffer_factor [Float] buffer factor to apply to observed fluctuation (default: 1.25)
+  # @param reserve_ratio [Float] minimum reserve capacity as a ratio of max active nodes (default: 0.1)
+  def initialize(
+      max_maintenance_interval: 1000,
+      target_check_interval: 1.0,
+      history_size: 120,
+      buffer_factor: 1.25,
+      reserve_ratio: 0.1)
+    @pool = []
+    
+    @max_maintenance_interval = max_maintenance_interval
+    @target_check_interval = target_check_interval
+    @history_limit = history_size
+    @buffer_ratio = buffer_factor
+    @reserve_ratio = reserve_ratio
+    
+    @maintenance_count = 0
+    @check_interval = 1000
+    @check_count = 0
+    @avg_release_rate = nil
+    @last_check_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    
+    @active_nodes = 0
+    @global_max_active = 0
+    @global_min_active = 0
+    @max_active_in_interval = 0
+    @min_active_in_interval = 0
+    @history = []
+    @current_target_capacity = Float::INFINITY
+  end
+
+  # Allocates a new node or recycles one from the pool.
+  #
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @param color [Boolean] the color (true=red, false=black)
+  # @param left [Node] the left child
+  # @param right [Node] the right child
+  # @param parent [Node] the parent node
+  def allocate(key, value, color, left, right, parent)
+    @active_nodes += 1
+    @max_active_in_interval = @active_nodes if @active_nodes > @max_active_in_interval
+    super
+  end
+
+  # Releases a node back to the pool.
+  #
+  # Checks auto-shrink logic to decide whether to keep the node or let it be GC'd.
+  #
+  # @param node [Node] the node to release
+  def release(node)
+    @active_nodes -= 1
+    @min_active_in_interval = @active_nodes if @active_nodes < @min_active_in_interval
+
+    @check_count += 1
+    
+    perform_maintenance if @check_count >= @check_interval
+
+    super if @pool.size < @current_target_capacity
+  end
+
+  private
+
+  def perform_maintenance
+    @maintenance_count += 1
+    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    elapsed = now - @last_check_time
+    return if elapsed <= 0
+    
+    current_rate = @check_count / elapsed
+    
+    if @avg_release_rate.nil?
+      @avg_release_rate = current_rate
+    else
+      @avg_release_rate = (@avg_release_rate * 3 + current_rate) / 4
+    end
+    
+    @check_interval = [[(@avg_release_rate * @target_check_interval).to_i, 1].max, @max_maintenance_interval].min
+    
+    expired_min = false
+    expired_max = false
+    needs_recalc = false
+
+    cutoff_time = now - @history_limit
+    while !@history.empty? && @history.first[0] < cutoff_time
+      if !expired_min && @history.first[1] == @global_min_active
+        expired_min = true
+        needs_recalc = true
+      end
+      if !expired_max && @history.first[2] == @global_max_active
+        expired_max = true
+        needs_recalc = true
+      end
+      @history.shift
+    end
+
+    @history << [now, @min_active_in_interval, @max_active_in_interval]
+
+    if @min_active_in_interval < @global_min_active
+      @global_min_active = @min_active_in_interval
+      expired_min = false
+      needs_recalc = true
+    end
+    if @max_active_in_interval > @global_max_active
+      @global_max_active = @max_active_in_interval
+      expired_max = false
+      needs_recalc = true
+    end
+
+    @global_min_active = @history.map { |_, min, _| min }.min if expired_min
+    @global_max_active = @history.map { |_, _, max| max }.max if expired_max
+    if needs_recalc
+      fluctuation = @global_max_active - @global_min_active
+      reserve = (@reserve_ratio * @global_max_active).to_i
+      @current_target_capacity = [(fluctuation * @buffer_ratio).to_i, reserve].max
+    end
+    
+    @check_count = 0
+    @last_check_time = now
+    @max_active_in_interval = @active_nodes
+    @min_active_in_interval = @active_nodes
+  end
+end

metadata

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