rbtree-ruby 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28594e663eac8519467b09c0756a032b2ef887d69df9e9335d1d79c36744a134
-  data.tar.gz: 492d6896dd4a0644ecc8ad721214afe2827daf3acbde38dce938e6da54cac87f
+  metadata.gz: 327862d13e55ed6406023e1d10676e4b5e94541c59400d9205380af08822e4bf
+  data.tar.gz: 465e1a514390286bf0165db4dfa9f25ada4cd3d1410b0115b11eba15b03dcf33
 SHA512:
-  metadata.gz: 3aeeca5b0d3de1a8826fac660dc6b201c046cb193328ba75bcd20f679f682fbf65479179fcddebe63920522eaa9ede28a9f8a784c76387e86530105a7378c8cd
-  data.tar.gz: 1e960a2132c1c3bc8988e233ebfb249f121900ac6eabbbcce0aa86186ceb24caa3224d4e7ebb8ad2acda5b927976ec0d5a0437ec20ad5fe2162eda841d15f909
+  metadata.gz: 1f354523b8fb78b746cf256949887b89184ce1dcd190403a7024949cded391de24ce6f932720a58ae24592b4b453f3901b1896c9904f546aa03fe4b1524698c2
+  data.tar.gz: e1219a20ea771f3fe1ca2fc160d737c787a1a0e81cb5389b63f320dcd1d2ac9d2cc71d9df2b9698d73afc98069f76d39285ca8106691f0025f1d5a5fa8b6bf91

data/CHANGELOG.md

@@ -5,9 +5,23 @@ 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
+- **`to_h`**: Added `to_h` method to `RBTree` and `MultiRBTree` for efficient conversion to Hash.
+- **`merge!`**: Added `merge!` method to `RBTree` and `MultiRBTree`.
+  - `RBTree#merge!`: Supports `overwrite` option (default: `true`). Raises `ArgumentError` if merging a `MultiRBTree` (incompatible value structures).
+  - `MultiRBTree#merge!`: Always appends values from the source.
+
 ## [0.3.0] - 2026-01-15
 
-### Changed
 ### API Changes (Method Renaming & Deprecation)
 > [!WARNING]
 > The public API has been refactored to improve consistency. The following methods have been renamed.
@@ -184,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

@@ -174,6 +174,25 @@ tree.lt(3).first                   # => [1, "one"] (遅延評価、配列は作
 tree.gt(0).lazy.take(2).to_a  # => [[1, "one"], [2, "two"]] (最初の2件のみ計算)
 ```
 
+### 変換と結合
+
+標準のRubyオブジェクトへの変換や、他のコレクションとの結合も簡単です:
+
+```ruby
+tree = RBTree.new({1 => 'one', 2 => 'two'})
+
+# 配列への変換（Enumerable経由）
+tree.to_a  # => [[1, "one"], [2, "two"]]
+
+# ハッシュへの変換
+tree.to_h  # => {1 => "one", 2 => "two"}
+
+# 他のツリー、ハッシュ、またはEnumerableの結合
+other = {3 => 'three'}
+tree.merge!(other)
+tree.size  # => 3
+```
+
 ### MultiRBTree 値配列アクセス
 
 複数の値を持つキーで、どの値にアクセスするか選択:
@@ -217,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万件**でのベンチマーク:
@@ -235,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

@@ -174,6 +174,25 @@ tree.lt(3).first                   # => [1, "one"] (lazy, no array created)
 tree.gt(0).lazy.take(2).to_a  # => [[1, "one"], [2, "two"]] (only computes first 2)
 ```
 
+### Conversion and Merging
+
+Seamlessly convert to standard Ruby objects or merge other collections:
+
+```ruby
+tree = RBTree.new({1 => 'one', 2 => 'two'})
+
+# Convert to Array (via Enumerable)
+tree.to_a  # => [[1, "one"], [2, "two"]]
+
+# Convert to Hash
+tree.to_h  # => {1 => "one", 2 => "two"}
+
+# Merge another tree, hash, or enumerable
+other = {3 => 'three'}
+tree.merge!(other)
+tree.size  # => 3
+```
+
 ### MultiRBTree Value Array Access
 
 For keys with multiple values, choose which value to access:
@@ -217,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**:
@@ -235,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.0"
+  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,14 +100,21 @@ 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
   end
 
+  # Returns a Hash containing all key-value pairs from the tree.
+  #
+  # @return [Hash] a new Hash with the tree's contents
+  def to_h = @hash_index.transform_values(&:value)
+
   # Checks if the tree is empty.
   #
   # @return [Boolean] true if the tree contains no elements, false otherwise
@@ -298,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)
@@ -335,6 +343,19 @@ class RBTree
     end
   end
   alias :[]= :insert
+  
+  # Merges the contents of another tree, hash, or enumerable into this tree.
+  #
+  # @param other [RBTree, Hash, Enumerable] the source to merge from
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @return [RBTree] self
+  def merge!(other, overwrite: true)
+    if defined?(MultiRBTree) && other.is_a?(MultiRBTree)
+      raise ArgumentError, "Cannot merge MultiRBTree into RBTree"
+    end
+    insert(other, overwrite: overwrite)
+    self
+  end
 
   # Deletes the key-value pair with the specified key.
   #
@@ -1308,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
 
@@ -1548,61 +1556,15 @@ class MultiRBTree < RBTree
   #   tree.succ(4)   # => [5, "five"]
   def succ(key, last: false) = (pair = super(key)) && [pair[0], pair[1].send(last ? :last : :first)]
 
-  # Inserts a value for the given key.
+  # Merges the contents of another tree, hash, or enumerable into this tree.
   #
-  # If the key already exists, the value is appended to its list.
-  # If the key doesn't exist, a new node is created.
+  # Appends values from the other source to the existing values for each key.
   #
-  # @param key [Object] the key (must implement <=>)
-  # @param value [Object] the value to insert
-  # @param overwrite [Boolean] ignored for MultiRBTree which always appends
-  # @return [Boolean] always returns true
-  # @example
-  #   tree = MultiRBTree.new
-  #   tree.insert(1, 'first')
-  #   tree.insert(1, 'second')  # adds another value for key 1
-  def insert_entry(key, value, **)
-    if (node = @hash_index[key])
-      node.value << value
-      @value_count += 1
-      return true
-    end
-    y = @nil_node
-    x = @root
-    while x != @nil_node
-      y = x
-      cmp = key <=> x.key
-      if cmp == 0
-        x.value << value
-        @value_count += 1
-        return true
-      elsif cmp < 0
-        x = x.left
-      else
-        x = x.right
-      end
-    end
-    z = allocate_node(key, [value], Node::RED, @nil_node, @nil_node, @nil_node)
-    z.parent = y
-    if y == @nil_node
-      @root = z
-    elsif (key <=> y.key) < 0
-      y.left = z
-    else
-      y.right = z
-    end
-    z.left = @nil_node
-    z.right = @nil_node
-    z.color = Node::RED
-    insert_fixup(z)
-    @value_count += 1
-    
-    if @min_node == @nil_node || (key <=> @min_node.key) < 0
-      @min_node = z
-    end
-    
-    @hash_index[key] = z  # Add to hash index
-    true
+  # @param other [RBTree, Hash, Enumerable] the source to merge from
+  # @return [MultiRBTree] self
+  def merge!(other)
+    insert(other)
+    self
   end
 
   # Deletes a single value for the specified key.
@@ -1692,6 +1654,63 @@ class MultiRBTree < RBTree
   # @!visibility private
   private
 
+  # Inserts a value for the given key.
+  #
+  # If the key already exists, the value is appended to its list.
+  # If the key doesn't exist, a new node is created.
+  #
+  # @param key [Object] the key (must implement <=>)
+  # @param value [Object] the value to insert
+  # @param overwrite [Boolean] ignored for MultiRBTree which always appends
+  # @return [Boolean] always returns true
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')  # adds another value for key 1
+  def insert_entry(key, value, **)
+    if (node = @hash_index[key])
+      node.value << value
+      @value_count += 1
+      return true
+    end
+    y = @nil_node
+    x = @root
+    while x != @nil_node
+      y = x
+      cmp = key <=> x.key
+      if cmp == 0
+        x.value << value
+        @value_count += 1
+        return true
+      elsif cmp < 0
+        x = x.left
+      else
+        x = x.right
+      end
+    end
+    z = allocate_node(key, [value], Node::RED, @nil_node, @nil_node, @nil_node)
+    z.parent = y
+    if y == @nil_node
+      @root = z
+    elsif (key <=> y.key) < 0
+      y.left = z
+    else
+      y.right = z
+    end
+    z.left = @nil_node
+    z.right = @nil_node
+    z.color = Node::RED
+    insert_fixup(z)
+    @value_count += 1
+    
+    if @min_node == @nil_node || (key <=> @min_node.key) < 0
+      @min_node = z
+    end
+    
+    @hash_index[key] = z  # Add to hash index
+    true
+  end
+
   # Traverses the tree in ascending order, yielding each key-value pair.
   #
   # @param range [Range] the range of keys to traverse
@@ -1761,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.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Masahito Suzuki
@@ -25,7 +25,6 @@ files:
 - README.ja.md
 - README.md
 - Rakefile
-- lib/rbtree.old.rb
 - lib/rbtree.rb
 - lib/rbtree/version.rb
 - rbtree-ruby.gemspec