deploy: ruby-rice/rice@abc6d80

Author: cfis

4.x/bindings/callbacks/index.html

@@ -1485,6 +1485,17 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#memory-management" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Memory Management
+      
+    </span>
+  </a>
+  
 </li>
 
     </ul>
@@ -3640,6 +3651,14 @@ <h3 id="libffi-callback">LibFFI Callback<a class="headerlink" href="#libffi-call
 <div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="nb">abort</span><span class="w"> </span><span class="s2">&quot;libffi not found&quot;</span><span class="w"> </span><span class="k">unless</span><span class="w"> </span><span class="n">have_libffi</span>
 </code></pre></div>
 <p>If you are using CMake, you will need to add a C++ preprocessor define called <code>HAVE_LIBFFI</code> and link to libffi.</p>
+<h2 id="memory-management">Memory Management<a class="headerlink" href="#memory-management" title="Permanent link">&para;</a></h2>
+<p>Callback wrappers (NativeCallback instances) are intentionally never freed. This is because:</p>
+<ol>
+<li>C code may call the callback at any time, even after the Ruby code that registered it has finished executing</li>
+<li>Ruby users commonly pass blocks to C callbacks, which Rice converts to Procs internally. Without special handling, these Procs would be garbage collected and the callback would crash when invoked</li>
+</ol>
+<p>Rice uses <code>Pin</code> internally to prevent the Ruby Proc from being garbage collected, ensuring the callback remains valid for the lifetime of the program.</p>
+<p>In practice, this means each unique callback registration consumes a small amount of memory that is never reclaimed. For most applications this is not a concern, as callbacks are typically registered once during initialization.</p>
 
 
 

4.x/bindings/memory_management/index.html

@@ -1756,6 +1756,45 @@
     </span>
   </a>
 
+    <nav class="md-nav" aria-label="Heap">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#pin-api" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Pin API
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#copy-semantics" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Copy Semantics
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#when-to-use-pin-vs-ruby_mark" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        When to Use Pin vs ruby_mark
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
           <li class="md-nav__item">
@@ -3821,25 +3860,57 @@ <h2 id="c-referencing-ruby-objects">C++ Referencing Ruby Objects<a class="header
 <h3 id="stack">Stack<a class="headerlink" href="#stack" title="Permanent link">&para;</a></h3>
 <p>If you are working with VALUEs or Objects stored on the stack, the Ruby garbage collector will try to find them automatically. However, optimizing compilers may prevent them from doing so. Thus you may need to use Ruby's <a href="https://docs.ruby-lang.org/en/3.2/extension_rdoc.html#label-Appendix+E.+RB_GC_GUARD+to+protect+from+premature+GC">RB_GC_GUARD</a> macro</p>
 <h3 id="heap">Heap<a class="headerlink" href="#heap" title="Permanent link">&para;</a></h3>
-<p>If you allocate an Object on the heap or if it is a member of an object that might be allocated on the heap, use <code>Rice::Address_Registration_Guard</code> to register the object with the garbage collector.</p>
+<p>If a C++ object holds a Ruby VALUE and that C++ object is <em>not</em> wrapped by Ruby (i.e., it's allocated on the heap or is a standalone object), use <code>Rice::Pin</code> to prevent the garbage collector from collecting the Ruby object.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">Container</span>
+<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="p">{</span>
+<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="k">public</span><span class="o">:</span>
+<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w">  </span><span class="n">Container</span><span class="p">(</span><span class="n">VALUE</span><span class="w"> </span><span class="n">value</span><span class="p">)</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">pin_</span><span class="p">(</span><span class="n">value</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span>
+<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w">  </span><span class="n">VALUE</span><span class="w"> </span><span class="n">getValue</span><span class="p">()</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">pin_</span><span class="p">.</span><span class="n">get</span><span class="p">();</span><span class="w"> </span><span class="p">}</span>
+<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w">  </span><span class="kt">void</span><span class="w"> </span><span class="n">setValue</span><span class="p">(</span><span class="n">VALUE</span><span class="w"> </span><span class="n">value</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">pin_</span><span class="p">.</span><span class="n">set</span><span class="p">(</span><span class="n">value</span><span class="p">);</span><span class="w"> </span><span class="p">}</span>
+<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a>
+<a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="k">private</span><span class="o">:</span>
+<a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w">  </span><span class="n">Rice</span><span class="o">::</span><span class="n">Pin</span><span class="w"> </span><span class="n">pin_</span><span class="p">;</span>
+<a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="p">};</span>
+</code></pre></div>
+<h4 id="pin-api">Pin API<a class="headerlink" href="#pin-api" title="Permanent link">&para;</a></h4>
+<ul>
+<li><code>Pin(VALUE value)</code> - Construct a Pin that protects the given VALUE from garbage collection</li>
+<li><code>VALUE get() const</code> - Retrieve the pinned VALUE</li>
+<li><code>void set(VALUE value)</code> - Replace the pinned VALUE</li>
+</ul>
+<h4 id="copy-semantics">Copy Semantics<a class="headerlink" href="#copy-semantics" title="Permanent link">&para;</a></h4>
+<p><code>Pin</code> uses shared ownership internally. When you copy a <code>Pin</code>, both copies share the same underlying GC anchor:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="n">Pin</span><span class="w"> </span><span class="nf">pin1</span><span class="p">(</span><span class="n">some_value</span><span class="p">);</span>
+<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="n">Pin</span><span class="w"> </span><span class="n">pin2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">pin1</span><span class="p">;</span><span class="w">       </span><span class="c1">// pin1 and pin2 share the same anchor</span>
+<a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a>
+<a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="n">pin1</span><span class="p">.</span><span class="n">set</span><span class="p">(</span><span class="n">other_value</span><span class="p">);</span><span class="w"> </span><span class="c1">// Both pin1.get() and pin2.get() now return other_value</span>
+</code></pre></div>
+<p>This is useful when multiple C++ objects need to reference the same Ruby object - only one GC registration is needed.</p>
+<h4 id="when-to-use-pin-vs-ruby_mark">When to Use Pin vs ruby_mark<a class="headerlink" href="#when-to-use-pin-vs-ruby_mark" title="Permanent link">&para;</a></h4>
+<p>Use <code>Pin</code> when:
+* The C++ object is <strong>not</strong> wrapped by Ruby (e.g., created with <code>new</code> in C++, stored in a global, or part of a C++ library's internal data structures)
+* You want self-contained protection without manual GC registration</p>
+<p>Use <code>ruby_mark</code> (see below) when:
+* The C++ object <strong>is</strong> wrapped by Ruby via <code>Data_Type</code>
+* Ruby owns the C++ object and will call the mark function during garbage collection</p>
 <h3 id="member-variables">Member Variables<a class="headerlink" href="#member-variables" title="Permanent link">&para;</a></h3>
 <p>If you create classes or structures that reference Ruby objects, you need to implement a custom <code>ruby_mark</code> function:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">MyClass</span>
-<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="p">{</span>
-<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w">  </span><span class="n">VALUE</span><span class="w"> </span><span class="n">value_</span><span class="p">;</span>
-<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="p">}</span>
-<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a>
-<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="k">namespace</span><span class="w"> </span><span class="nn">Rice</span>
-<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="p">{</span>
-<a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="w">  </span><span class="k">template</span><span class="o">&lt;&gt;</span>
-<a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w">  </span><span class="n">ruby_mark</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">MyClass</span><span class="o">*</span><span class="w"> </span><span class="n">myClass</span><span class="p">)</span>
-<a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="w">  </span><span class="p">{</span>
-<a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></a><span class="w">    </span><span class="n">rb_gc_mark</span><span class="p">(</span><span class="n">myClass</span><span class="o">-&gt;</span><span class="n">value_</span><span class="p">);</span>
-<a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a><span class="w">  </span><span class="p">}</span>
-<a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a><span class="p">}</span>
-<a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a>
-<a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a><span class="n">Data_Type</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="w"> </span><span class="k">class</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">define_class</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="p">(</span><span class="s">&quot;MyClass&quot;</span><span class="p">)</span>
-<a id="__codelineno-10-16" name="__codelineno-10-16" href="#__codelineno-10-16"></a><span class="w">          </span><span class="p">.</span><span class="n">define_constructor</span><span class="p">(</span><span class="n">Constructor</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="p">());</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">MyClass</span>
+<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="p">{</span>
+<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="w">  </span><span class="n">VALUE</span><span class="w"> </span><span class="n">value_</span><span class="p">;</span>
+<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a><span class="p">}</span>
+<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a>
+<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a><span class="k">namespace</span><span class="w"> </span><span class="nn">Rice</span>
+<a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="p">{</span>
+<a id="__codelineno-12-8" name="__codelineno-12-8" href="#__codelineno-12-8"></a><span class="w">  </span><span class="k">template</span><span class="o">&lt;&gt;</span>
+<a id="__codelineno-12-9" name="__codelineno-12-9" href="#__codelineno-12-9"></a><span class="w">  </span><span class="n">ruby_mark</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">MyClass</span><span class="o">*</span><span class="w"> </span><span class="n">myClass</span><span class="p">)</span>
+<a id="__codelineno-12-10" name="__codelineno-12-10" href="#__codelineno-12-10"></a><span class="w">  </span><span class="p">{</span>
+<a id="__codelineno-12-11" name="__codelineno-12-11" href="#__codelineno-12-11"></a><span class="w">    </span><span class="n">rb_gc_mark</span><span class="p">(</span><span class="n">myClass</span><span class="o">-&gt;</span><span class="n">value_</span><span class="p">);</span>
+<a id="__codelineno-12-12" name="__codelineno-12-12" href="#__codelineno-12-12"></a><span class="w">  </span><span class="p">}</span>
+<a id="__codelineno-12-13" name="__codelineno-12-13" href="#__codelineno-12-13"></a><span class="p">}</span>
+<a id="__codelineno-12-14" name="__codelineno-12-14" href="#__codelineno-12-14"></a>
+<a id="__codelineno-12-15" name="__codelineno-12-15" href="#__codelineno-12-15"></a><span class="n">Data_Type</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="w"> </span><span class="k">class</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">define_class</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="p">(</span><span class="s">&quot;MyClass&quot;</span><span class="p">)</span>
+<a id="__codelineno-12-16" name="__codelineno-12-16" href="#__codelineno-12-16"></a><span class="w">          </span><span class="p">.</span><span class="n">define_constructor</span><span class="p">(</span><span class="n">Constructor</span><span class="o">&lt;</span><span class="n">MyClass</span><span class="o">&gt;</span><span class="p">());</span>
 </code></pre></div>
 
 

4.x/changelog/index.html

@@ -3919,9 +3919,24 @@ <h2 id="492-unreleased">4.9.2 (unreleased)<a class="headerlink" href="#492-unrel
 * Add support for <code>std::ostream</code>, <code>std::ostringstream</code>, and <code>std::ofstream</code>. Ruby can write to C++ streams and pass them to C++ functions. Standard streams are exposed as <code>Std::COUT</code> and <code>Std::CERR</code>.</p>
 <p>Internal:
 * Refactor type handling by merging <code>TypeMapper</code> into <code>TypeDetail</code> and simplifying class hierarchy</p>
-<p>Incomptatible Changes:
-* Rice converts Ruby blocks to procs. Thus if you have a method that expects a block, you must add
-  a VALUE parameter and tell Rice it is a value. For example:</p>
+<p>Incompatible Changes:
+* <code>Address_Registration_Guard</code> has been replaced by <code>Pin</code>. If you are using <code>Address_Registration_Guard</code>
+  to protect Ruby VALUEs from garbage collection, update your code to use <code>Pin</code> instead:</p>
+<p>Before:
+  <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">VALUE</span><span class="w"> </span><span class="n">value_</span><span class="p">;</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="n">Address_Registration_Guard</span><span class="w"> </span><span class="n">guard_</span><span class="p">;</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="n">MyClass</span><span class="p">()</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">value_</span><span class="p">(</span><span class="n">rb_str_new2</span><span class="p">(</span><span class="s">&quot;test&quot;</span><span class="p">)),</span><span class="w"> </span><span class="n">guard_</span><span class="p">(</span><span class="o">&amp;</span><span class="n">value_</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span>
+</code></pre></div></p>
+<p>After:
+  <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="n">Pin</span><span class="w"> </span><span class="n">pin_</span><span class="p">;</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="n">MyClass</span><span class="p">()</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">pin_</span><span class="p">(</span><span class="n">rb_str_new2</span><span class="p">(</span><span class="s">&quot;test&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{}</span>
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="n">VALUE</span><span class="w"> </span><span class="n">getValue</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">pin_</span><span class="p">.</span><span class="n">get</span><span class="p">();</span><span class="w"> </span><span class="p">}</span>
+</code></pre></div></p>
+<p><code>Pin</code> is self-contained and provides <code>get()</code> and <code>set()</code> methods to access the pinned VALUE.</p>
+<ul>
+<li>Rice converts Ruby blocks to procs. Thus if you have a method that expects a block, you must add
+  a VALUE parameter and tell Rice it is a value. For example:</li>
+</ul>
 <p>define_method("my_method", <a href="VALUE self, VALUE proc"></a>
   {
   }, Arg("proc").setValue())</p>