diff options
Diffstat (limited to 'Doc/Manual/Ruby.html')
| -rw-r--r-- | Doc/Manual/Ruby.html | 445 |
1 files changed, 299 insertions, 146 deletions
diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index b61ded8e5..f21e353ce 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -1,32 +1,13 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> - - - - - - - - - - - - - - <title>SWIG and Ruby</title> <link rel="stylesheet" type="text/css" href="style.css"> </head> +<body bgcolor="#ffffff"> -<body style="background-color: rgb(255, 255, 255);"> - - - - - -<H1><a name="Ruby"></a>33 SWIG and Ruby</H1> +<H1><a name="Ruby"></a>35 SWIG and Ruby</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -167,7 +148,7 @@ -<H2><a name="Ruby_nn2"></a>33.1 Preliminaries</H2> +<H2><a name="Ruby_nn2"></a>35.1 Preliminaries</H2> <p> SWIG 1.3 is known to work with Ruby versions 1.6 and later. @@ -190,7 +171,7 @@ of Ruby. </p> -<H3><a name="Ruby_nn3"></a>33.1.1 Running SWIG</H3> +<H3><a name="Ruby_nn3"></a>35.1.1 Running SWIG</H3> <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> @@ -244,7 +225,7 @@ to compile this file and link it with the rest of your program. </p> -<H3><a name="Ruby_nn4"></a>33.1.2 Getting the right header files</H3> +<H3><a name="Ruby_nn4"></a>35.1.2 Getting the right header files</H3> <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt> @@ -255,7 +236,9 @@ header file. This file is usually contained in a directory such as </p> <div class="code shell diagram"> -<pre>/usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h<br>/usr/local/lib/ruby/1.6/i686-linux/ruby.h<br></pre> +<pre>/usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h +/usr/local/lib/ruby/1.6/i686-linux/ruby.h +</pre> @@ -276,7 +259,10 @@ installed, you can run Ruby to find out. For example: </p> <div class="code shell"> -<pre>$ <b>ruby -e 'puts $:.join("\n")'</b><br>/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux<br>/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .<br> </pre> +<pre>$ <b>ruby -e 'puts $:.join("\n")'</b> +/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux +/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux . +</pre> @@ -288,7 +274,7 @@ installed, you can run Ruby to find out. For example: </p> -<H3><a name="Ruby_nn5"></a>33.1.3 Compiling a dynamic module</H3> +<H3><a name="Ruby_nn5"></a>35.1.3 Compiling a dynamic module</H3> <p> Ruby extension modules are typically compiled into shared @@ -324,16 +310,7 @@ looks like the following:</p> <div class="code targetlang"> - - - - <pre>require 'mkmf'<br>create_makefile('example')<br></pre> - - - - - </div> @@ -401,7 +378,12 @@ can add this: </p> <div class="code targetlang"> -<pre>open("Makefile", "a") { |mf|<br> puts <<EOM<br> # Your make rules go here<br> EOM<br>}<br></pre> +<pre>open("Makefile", "a") { |mf| + puts <<EOM + # Your make rules go here + EOM +} +</pre> @@ -424,7 +406,10 @@ operating system would look something like this: </p> <div class="code shell"> -<pre>$ <b>swig -ruby example.i</b><br>$ <b>gcc -c example.c</b><br>$ <b>gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux</b> <br>$ <b>gcc -shared example.o example_wrap.o -o example.so</b> +<pre>$ <b>swig -ruby example.i</b> +$ <b>gcc -c example.c</b> +$ <b>gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux</b> +$ <b>gcc -shared example.o example_wrap.o -o example.so</b> </pre> @@ -443,7 +428,7 @@ manual pages for your compiler and linker to determine the correct set of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> for additional information. </p> -<H3><a name="Ruby_nn6"></a>33.1.4 Using your module</H3> +<H3><a name="Ruby_nn6"></a>35.1.4 Using your module</H3> <p> Ruby <i>module</i> names must be capitalized, @@ -456,7 +441,12 @@ module is imported by requiring the <b>etc</b> feature: </p> <div class="code targetlang"> -<pre># The feature name begins with a lowercase letter...<br>require 'etc'<br><br># ... but the module name begins with an uppercase letter<br>puts "Your login name: #{Etc.getlogin}"<br></pre> +<pre># The feature name begins with a lowercase letter... +require 'etc' + +# ... but the module name begins with an uppercase letter +puts "Your login name: #{Etc.getlogin}" +</pre> @@ -498,7 +488,7 @@ begins with: </p> -<H3><a name="Ruby_nn7"></a>33.1.5 Static linking</H3> +<H3><a name="Ruby_nn7"></a>35.1.5 Static linking</H3> <p> An alternative approach to dynamic linking is to rebuild the @@ -519,7 +509,7 @@ finally rebuilding Ruby. </p> -<H3><a name="Ruby_nn8"></a>33.1.6 Compilation of C++ extensions</H3> +<H3><a name="Ruby_nn8"></a>35.1.6 Compilation of C++ extensions</H3> <p> On most machines, C++ extension modules should be linked @@ -571,7 +561,7 @@ extension, e.g. </p> -<H2><a name="Ruby_nn9"></a>33.2 Building Ruby Extensions under Windows 95/NT</H2> +<H2><a name="Ruby_nn9"></a>35.2 Building Ruby Extensions under Windows 95/NT</H2> <p> Building a SWIG extension to Ruby under Windows 95/NT is @@ -610,7 +600,7 @@ files. </p> -<H3><a name="Ruby_nn10"></a>33.2.1 Running SWIG from Developer Studio</H3> +<H3><a name="Ruby_nn10"></a>35.2.1 Running SWIG from Developer Studio</H3> <p> If you are developing your application within Microsoft @@ -752,7 +742,7 @@ directory, then run the Ruby script from the DOS/Command prompt: </p> -<H2><a name="Ruby_nn11"></a>33.3 The Ruby-to-C/C++ Mapping</H2> +<H2><a name="Ruby_nn11"></a>35.3 The Ruby-to-C/C++ Mapping</H2> <p> This section describes the basics of how SWIG maps C or C++ @@ -762,7 +752,7 @@ declarations in your SWIG interface files to Ruby constructs. </p> -<H3><a name="Ruby_nn12"></a>33.3.1 Modules</H3> +<H3><a name="Ruby_nn12"></a>35.3.1 Modules</H3> <p> The SWIG <tt>%module</tt> directive specifies @@ -931,7 +921,7 @@ Ruby's built-in names. </p> -<H3><a name="Ruby_nn13"></a>33.3.2 Functions</H3> +<H3><a name="Ruby_nn13"></a>35.3.2 Functions</H3> <p> Global functions are wrapped as Ruby module methods. For @@ -994,7 +984,7 @@ module that can be used like so: </p> -<H3><a name="Ruby_nn14"></a>33.3.3 Variable Linking</H3> +<H3><a name="Ruby_nn14"></a>35.3.3 Variable Linking</H3> <p> C/C++ global variables are wrapped as a pair of singleton @@ -1094,7 +1084,7 @@ effect until it is explicitly disabled using <tt>%mutable</tt>. -<H3><a name="Ruby_nn15"></a>33.3.4 Constants</H3> +<H3><a name="Ruby_nn15"></a>35.3.4 Constants</H3> <p> C/C++ constants are wrapped as module constants initialized @@ -1138,7 +1128,7 @@ constant values, e.g. </p> -<H3><a name="Ruby_nn16"></a>33.3.5 Pointers</H3> +<H3><a name="Ruby_nn16"></a>35.3.5 Pointers</H3> <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that @@ -1190,7 +1180,7 @@ the Ruby <tt>nil</tt> object. </p> -<H3><a name="Ruby_nn17"></a>33.3.6 Structures</H3> +<H3><a name="Ruby_nn17"></a>35.3.6 Structures</H3> <p> C/C++ structs are wrapped as Ruby classes, with accessor @@ -1365,7 +1355,7 @@ pointers. For example, </p> -<H3><a name="Ruby_nn18"></a>33.3.7 C++ classes</H3> +<H3><a name="Ruby_nn18"></a>35.3.7 C++ classes</H3> <p> Like structs, C++ classes are wrapped by creating a new Ruby @@ -1451,7 +1441,7 @@ class. </li> -<H3><a name="Ruby_nn19"></a>33.3.8 C++ Inheritance</H3> +<H3><a name="Ruby_nn19"></a>35.3.8 C++ Inheritance</H3> <p> The SWIG type-checker is fully aware of C++ inheritance. @@ -1682,7 +1672,7 @@ Typing"</a>). </p> -<H3><a name="Ruby_nn20"></a>33.3.9 C++ Overloaded Functions</H3> +<H3><a name="Ruby_nn20"></a>35.3.9 C++ Overloaded Functions</H3> <p> C++ overloaded functions, methods, and constructors are @@ -1882,7 +1872,7 @@ and C++"</a> chapter for more information about overloading. </p> -<H3><a name="Ruby_nn21"></a>33.3.10 C++ Operators</H3> +<H3><a name="Ruby_nn21"></a>35.3.10 C++ Operators</H3> <p> For the most part, overloaded operators are handled @@ -1963,7 +1953,7 @@ on operator overloading</a>. </p> -<H3><a name="Ruby_nn22"></a>33.3.11 C++ namespaces</H3> +<H3><a name="Ruby_nn22"></a>35.3.11 C++ namespaces</H3> <p> SWIG is aware of C++ namespaces, but namespace names do not @@ -2039,7 +2029,7 @@ identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Ruby_nn23"></a>33.3.12 C++ templates</H3> +<H3><a name="Ruby_nn23"></a>35.3.12 C++ templates</H3> <p> C++ templates don't present a huge problem for SWIG. However, @@ -2083,7 +2073,7 @@ directive. For example: </p> -<H3><a name="Ruby_nn23_1"></a>33.3.13 C++ Standard Template Library (STL)</H3> +<H3><a name="Ruby_nn23_1"></a>35.3.13 C++ Standard Template Library (STL)</H3> <p> On a related note, the standard SWIG library contains a @@ -2336,7 +2326,7 @@ chapter.</p> -<H3><a name="Ruby_C_STL_Functors"></a>33.3.14 C++ STL Functors</H3> +<H3><a name="Ruby_C_STL_Functors"></a>35.3.14 C++ STL Functors</H3> <p>Some containers in the STL allow you to modify their default @@ -2536,7 +2526,7 @@ b<br style="font-weight: bold;"> -<H3><a name="Ruby_C_Iterators"></a>33.3.15 C++ STL Iterators</H3> +<H3><a name="Ruby_C_Iterators"></a>35.3.15 C++ STL Iterators</H3> <p>The STL is well known for the use of iterators. There @@ -2733,7 +2723,7 @@ i<br> -<span style="font-weight: bold;">>> [3, 4, 5 ]</span></div> +<b>>> [3, 4, 5 ]</b></div> @@ -2747,7 +2737,7 @@ i<br> -<H3><a name="Ruby_nn24"></a>33.3.16 C++ Smart Pointers</H3> +<H3><a name="Ruby_nn24"></a>35.3.16 C++ Smart Pointers</H3> <p> In certain C++ programs, it is common to use classes that @@ -2872,7 +2862,7 @@ method. For example: </p> -<H3><a name="Ruby_nn25"></a>33.3.17 Cross-Language Polymorphism</H3> +<H3><a name="Ruby_nn25"></a>35.3.17 Cross-Language Polymorphism</H3> <p> SWIG's Ruby module supports cross-language polymorphism @@ -2885,7 +2875,7 @@ using this feature with Ruby. </p> -<H4><a name="Ruby_nn26"></a>33.3.17.1 Exception Unrolling</H4> +<H4><a name="Ruby_nn26"></a>35.3.17.1 Exception Unrolling</H4> <p> Whenever a C++ director class routes one of its virtual @@ -2923,7 +2913,7 @@ caught here and a C++ exception is raised in its place. </p> -<H2><a name="Ruby_nn27"></a>33.4 Naming</H2> +<H2><a name="Ruby_nn27"></a>35.4 Naming</H2> <p>Ruby has several common naming conventions. Constants are @@ -3019,7 +3009,7 @@ planned to become the default option in future releases.</p> -<H3><a name="Ruby_nn28"></a>33.4.1 Defining Aliases</H3> +<H3><a name="Ruby_nn28"></a>35.4.1 Defining Aliases</H3> <p> It's a fairly common practice in the Ruby built-ins and @@ -3111,7 +3101,7 @@ Features"</a>) for more details).</p> -<H3><a name="Ruby_nn29"></a>33.4.2 Predicate Methods</H3> +<H3><a name="Ruby_nn29"></a>35.4.2 Predicate Methods</H3> <p> Ruby methods that return a boolean value and end in a @@ -3200,7 +3190,7 @@ Features"</a>) for more details). </p> -<H3><a name="Ruby_nn30"></a>33.4.3 Bang Methods</H3> +<H3><a name="Ruby_nn30"></a>35.4.3 Bang Methods</H3> <p> Ruby methods that modify an object in-place and end in an @@ -3264,7 +3254,7 @@ Features"</a>) for more details). </p> -<H3><a name="Ruby_nn31"></a>33.4.4 Getters and Setters</H3> +<H3><a name="Ruby_nn31"></a>35.4.4 Getters and Setters</H3> <p> Often times a C++ library will expose properties through @@ -3334,7 +3324,7 @@ methods to be exposed in Ruby as <tt>value</tt> and <tt>value=. -<H2><a name="Ruby_nn32"></a>33.5 Input and output parameters</H2> +<H2><a name="Ruby_nn32"></a>35.5 Input and output parameters</H2> <p> A common problem in some C programs is handling parameters @@ -3585,10 +3575,10 @@ of <tt>%apply</tt> </p> -<H2><a name="Ruby_nn33"></a>33.6 Exception handling </H2> +<H2><a name="Ruby_nn33"></a>35.6 Exception handling </H2> -<H3><a name="Ruby_nn34"></a>33.6.1 Using the %exception directive </H3> +<H3><a name="Ruby_nn34"></a>35.6.1 Using the %exception directive </H3> <p>The SWIG <tt>%exception</tt> directive can be @@ -3683,7 +3673,7 @@ Features</a> for more examples.</p> -<H3><a name="Ruby_nn34_2"></a>33.6.2 Handling Ruby Blocks </H3> +<H3><a name="Ruby_nn34_2"></a>35.6.2 Handling Ruby Blocks </H3> <p>One of the highlights of Ruby and most of its standard library @@ -3864,7 +3854,7 @@ RUBY_YIELD_SELF );<br> <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p> -<H3><a name="Ruby_nn35"></a>33.6.3 Raising exceptions </H3> +<H3><a name="Ruby_nn35"></a>35.6.3 Raising exceptions </H3> <p>There are three ways to raise exceptions from C++ code to @@ -4625,7 +4615,7 @@ the built-in Ruby exception types.</p> -<H3><a name="Ruby_nn36"></a>33.6.4 Exception classes </H3> +<H3><a name="Ruby_nn36"></a>35.6.4 Exception classes </H3> <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt> @@ -4683,7 +4673,7 @@ providing for a more natural integration between C++ code and Ruby code.</p> -<H2><a name="Ruby_nn37"></a>33.7 Typemaps</H2> +<H2><a name="Ruby_nn37"></a>35.7 Typemaps</H2> <p> This section describes how you can modify SWIG's default @@ -4706,7 +4696,7 @@ of the primitive C-Ruby interface.</p> -<H3><a name="Ruby_nn38"></a>33.7.1 What is a typemap?</H3> +<H3><a name="Ruby_nn38"></a>35.7.1 What is a typemap?</H3> <p> A typemap is nothing more than a code generation rule that is @@ -4968,7 +4958,7 @@ to be used as follows (notice how the length parameter is omitted): </p> -<H3><a name="Ruby_Typemap_scope"></a>33.7.2 Typemap scope</H3> +<H3><a name="Ruby_Typemap_scope"></a>35.7.2 Typemap scope</H3> <p> Once defined, a typemap remains in effect for all of the @@ -5016,7 +5006,7 @@ where the class itself is defined. For example:</p> -<H3><a name="Ruby_Copying_a_typemap"></a>33.7.3 Copying a typemap</H3> +<H3><a name="Ruby_Copying_a_typemap"></a>35.7.3 Copying a typemap</H3> <p> A typemap is copied by using assignment. For example:</p> @@ -5118,7 +5108,7 @@ rules as for <tt> -<H3><a name="Ruby_Deleting_a_typemap"></a>33.7.4 Deleting a typemap</H3> +<H3><a name="Ruby_Deleting_a_typemap"></a>35.7.4 Deleting a typemap</H3> <p> A typemap can be deleted by simply defining no code. For @@ -5170,7 +5160,7 @@ typemaps immediately after the clear operation.</p> -<H3><a name="Ruby_Placement_of_typemaps"></a>33.7.5 Placement of typemaps</H3> +<H3><a name="Ruby_Placement_of_typemaps"></a>35.7.5 Placement of typemaps</H3> <p> Typemap declarations can be declared in the global scope, @@ -5254,7 +5244,7 @@ string</tt> -<H3><a name="Ruby_nn39"></a>33.7.6 Ruby typemaps</H3> +<H3><a name="Ruby_nn39"></a>35.7.6 Ruby typemaps</H3> <p>The following list details all of the typemap methods that @@ -5264,7 +5254,7 @@ can be used by the Ruby module: </p> -<H4><a name="Ruby_in_typemap"></a>33.7.6.1 "in" typemap</H4> +<H4><a name="Ruby_in_typemap"></a>35.7.6.1 "in" typemap</H4> <p>Converts Ruby objects to input @@ -5507,7 +5497,7 @@ arguments to be specified. For example:</p> -<H4><a name="Ruby_typecheck_typemap"></a>33.7.6.2 "typecheck" typemap</H4> +<H4><a name="Ruby_typecheck_typemap"></a>35.7.6.2 "typecheck" typemap</H4> <p> The "typecheck" typemap is used to support overloaded @@ -5548,7 +5538,7 @@ on "Typemaps and Overloading."</p> -<H4><a name="Ruby_out_typemap"></a>33.7.6.3 "out" typemap</H4> +<H4><a name="Ruby_out_typemap"></a>35.7.6.3 "out" typemap</H4> <p>Converts return value of a C function @@ -5780,7 +5770,7 @@ version of the C datatype matched by the typemap.</td> -<H4><a name="Ruby_arginit_typemap"></a>33.7.6.4 "arginit" typemap</H4> +<H4><a name="Ruby_arginit_typemap"></a>35.7.6.4 "arginit" typemap</H4> <p> The "arginit" typemap is used to set the initial value of a @@ -5805,7 +5795,7 @@ applications. For example:</p> -<H4><a name="Ruby_default_typemap"></a>33.7.6.5 "default" typemap</H4> +<H4><a name="Ruby_default_typemap"></a>35.7.6.5 "default" typemap</H4> <p> The "default" typemap is used to turn an argument into a @@ -5847,7 +5837,7 @@ default argument wrapping.</p> -<H4><a name="Ruby_check_typemap"></a>33.7.6.6 "check" typemap</H4> +<H4><a name="Ruby_check_typemap"></a>35.7.6.6 "check" typemap</H4> <p> The "check" typemap is used to supply value checking code @@ -5871,7 +5861,7 @@ arguments have been converted. For example:</p> -<H4><a name="Ruby_argout_typemap_"></a>33.7.6.7 "argout" typemap</H4> +<H4><a name="Ruby_argout_typemap_"></a>35.7.6.7 "argout" typemap</H4> <p> The "argout" typemap is used to return values from arguments. @@ -6029,7 +6019,7 @@ some function like SWIG_Ruby_AppendOutput.</p> -<H4><a name="Ruby_freearg_typemap_"></a>33.7.6.8 "freearg" typemap</H4> +<H4><a name="Ruby_freearg_typemap_"></a>35.7.6.8 "freearg" typemap</H4> <p> The "freearg" typemap is used to cleanup argument data. It is @@ -6065,7 +6055,7 @@ abort prematurely.</p> -<H4><a name="Ruby_newfree_typemap"></a>33.7.6.9 "newfree" typemap</H4> +<H4><a name="Ruby_newfree_typemap"></a>35.7.6.9 "newfree" typemap</H4> <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> @@ -6096,7 +6086,7 @@ ownership and %newobject</a> for further details.</p> -<H4><a name="Ruby_memberin_typemap"></a>33.7.6.10 "memberin" typemap</H4> +<H4><a name="Ruby_memberin_typemap"></a>35.7.6.10 "memberin" typemap</H4> <p> The "memberin" typemap is used to copy data from<em> an @@ -6129,7 +6119,7 @@ other objects.</p> -<H4><a name="Ruby_varin_typemap"></a>33.7.6.11 "varin" typemap</H4> +<H4><a name="Ruby_varin_typemap"></a>35.7.6.11 "varin" typemap</H4> <p> The "varin" typemap is used to convert objects in the target @@ -6140,7 +6130,7 @@ This is implementation specific.</p> -<H4><a name="Ruby_varout_typemap_"></a>33.7.6.12 "varout" typemap</H4> +<H4><a name="Ruby_varout_typemap_"></a>35.7.6.12 "varout" typemap</H4> <p> The "varout" typemap is used to convert a C/C++ object to an @@ -6151,7 +6141,7 @@ This is implementation specific.</p> -<H4><a name="Ruby_throws_typemap"></a>33.7.6.13 "throws" typemap</H4> +<H4><a name="Ruby_throws_typemap"></a>35.7.6.13 "throws" typemap</H4> <p> The "throws" typemap is only used when SWIG parses a C++ @@ -6210,7 +6200,7 @@ handling with %exception</a> section.</p> -<H4><a name="Ruby_directorin_typemap"></a>33.7.6.14 directorin typemap</H4> +<H4><a name="Ruby_directorin_typemap"></a>35.7.6.14 directorin typemap</H4> <p>Converts C++ objects in director @@ -6464,7 +6454,7 @@ referring to the class itself.</td> -<H4><a name="Ruby_directorout_typemap"></a>33.7.6.15 directorout typemap</H4> +<H4><a name="Ruby_directorout_typemap"></a>35.7.6.15 directorout typemap</H4> <p>Converts Ruby objects in director @@ -6724,7 +6714,7 @@ exception.<br> -<H4><a name="Ruby_directorargout_typemap"></a>33.7.6.16 directorargout typemap</H4> +<H4><a name="Ruby_directorargout_typemap"></a>35.7.6.16 directorargout typemap</H4> <p>Output argument processing in director @@ -6964,7 +6954,7 @@ referring to the instance of the class itself</td> -<H4><a name="Ruby_ret_typemap"></a>33.7.6.17 ret typemap</H4> +<H4><a name="Ruby_ret_typemap"></a>35.7.6.17 ret typemap</H4> <p>Cleanup of function return values @@ -6974,7 +6964,7 @@ referring to the instance of the class itself</td> -<H4><a name="Ruby_globalin_typemap"></a>33.7.6.18 globalin typemap</H4> +<H4><a name="Ruby_globalin_typemap"></a>35.7.6.18 globalin typemap</H4> <p>Setting of C global variables @@ -6984,7 +6974,7 @@ referring to the instance of the class itself</td> -<H3><a name="Ruby_nn40"></a>33.7.7 Typemap variables</H3> +<H3><a name="Ruby_nn40"></a>35.7.7 Typemap variables</H3> <p> @@ -7094,7 +7084,7 @@ being created. </div> -<H3><a name="Ruby_nn41"></a>33.7.8 Useful Functions</H3> +<H3><a name="Ruby_nn41"></a>35.7.8 Useful Functions</H3> <p> When you write a typemap, you usually have to work directly @@ -7118,7 +7108,7 @@ across multiple languages.</p> -<H4><a name="Ruby_nn42"></a>33.7.8.1 C Datatypes to Ruby Objects</H4> +<H4><a name="Ruby_nn42"></a>35.7.8.1 C Datatypes to Ruby Objects</H4> <div class="diagram"> @@ -7174,7 +7164,7 @@ SWIG_From_float(float)</td> -<H4><a name="Ruby_nn43"></a>33.7.8.2 Ruby Objects to C Datatypes</H4> +<H4><a name="Ruby_nn43"></a>35.7.8.2 Ruby Objects to C Datatypes</H4> <p>Here, while the Ruby versions return the value directly, the SWIG @@ -7263,7 +7253,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input -<H4><a name="Ruby_nn44"></a>33.7.8.3 Macros for VALUE</H4> +<H4><a name="Ruby_nn44"></a>35.7.8.3 Macros for VALUE</H4> <p> <tt>RSTRING_LEN(str)</tt> </p> @@ -7326,7 +7316,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input -<H4><a name="Ruby_nn45"></a>33.7.8.4 Exceptions</H4> +<H4><a name="Ruby_nn45"></a>35.7.8.4 Exceptions</H4> <p> <tt>void rb_raise(VALUE exception, const char *fmt, @@ -7493,7 +7483,7 @@ arguments are interpreted as with <tt>printf()</tt>. </div> -<H4><a name="Ruby_nn46"></a>33.7.8.5 Iterators</H4> +<H4><a name="Ruby_nn46"></a>35.7.8.5 Iterators</H4> <p> <tt>void rb_iter_break()</tt> </p> @@ -7595,7 +7585,7 @@ VALUE), VALUE value)</tt></p> -<H3><a name="Ruby_nn47"></a>33.7.9 Typemap Examples</H3> +<H3><a name="Ruby_nn47"></a>35.7.9 Typemap Examples</H3> <p> This section includes a few examples of typemaps. For more @@ -7606,7 +7596,7 @@ directory. </p> -<H3><a name="Ruby_nn48"></a>33.7.10 Converting a Ruby array to a char **</H3> +<H3><a name="Ruby_nn48"></a>35.7.10 Converting a Ruby array to a char **</H3> <p> A common problem in many C programs is the processing of @@ -7661,7 +7651,7 @@ after the execution of the C function. </p> -<H3><a name="Ruby_nn49"></a>33.7.11 Collecting arguments in a hash</H3> +<H3><a name="Ruby_nn49"></a>35.7.11 Collecting arguments in a hash</H3> <p> Ruby's solution to the "keyword arguments" capability of some @@ -7940,7 +7930,7 @@ directory of the SWIG distribution. </p> -<H3><a name="Ruby_nn50"></a>33.7.12 Pointer handling</H3> +<H3><a name="Ruby_nn50"></a>35.7.12 Pointer handling</H3> <p> Occasionally, it might be necessary to convert pointer values @@ -8039,7 +8029,7 @@ For example: </p> -<H4><a name="Ruby_nn51"></a>33.7.12.1 Ruby Datatype Wrapping</H4> +<H4><a name="Ruby_nn51"></a>35.7.12.1 Ruby Datatype Wrapping</H4> <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void @@ -8090,7 +8080,7 @@ and assigns that pointer to <i>ptr</i>. </div> -<H3><a name="Ruby_nn52"></a>33.7.13 Example: STL Vector to Ruby Array</H3> +<H3><a name="Ruby_nn52"></a>35.7.13 Example: STL Vector to Ruby Array</H3> <p>Another use for macros and type maps is to create a Ruby array @@ -8199,7 +8189,7 @@ the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.<br> -<H2><a name="Ruby_nn65"></a>33.8 Docstring Features</H2> +<H2><a name="Ruby_nn65"></a>35.8 Docstring Features</H2> <p> @@ -8260,7 +8250,7 @@ generate ri documentation from a c wrap file, you could do:</p> -<H3><a name="Ruby_nn66"></a>33.8.1 Module docstring</H3> +<H3><a name="Ruby_nn66"></a>35.8.1 Module docstring</H3> <p> @@ -8311,7 +8301,7 @@ macro. For example: -<H3><a name="Ruby_nn67"></a>33.8.2 %feature("autodoc")</H3> +<H3><a name="Ruby_nn67"></a>35.8.2 %feature("autodoc")</H3> <p>Since SWIG does know everything about the function it wraps, @@ -8340,7 +8330,7 @@ feature, described below. -<H4><a name="Ruby_nn68"></a>33.8.2.1 %feature("autodoc", "0")</H4> +<H4><a name="Ruby_nn68"></a>35.8.2.1 %feature("autodoc", "0")</H4> <p> @@ -8388,7 +8378,7 @@ Then Ruby code like this will be generated: -<H4><a name="Ruby_autodoc1"></a>33.8.2.2 %feature("autodoc", "1")</H4> +<H4><a name="Ruby_autodoc1"></a>35.8.2.2 %feature("autodoc", "1")</H4> <p> @@ -8420,7 +8410,7 @@ this: -<H4><a name="Ruby_autodoc2"></a>33.8.2.3 %feature("autodoc", "2")</H4> +<H4><a name="Ruby_autodoc2"></a>35.8.2.3 %feature("autodoc", "2")</H4> <p> @@ -8436,7 +8426,7 @@ this: -<H4><a name="Ruby_feature_autodoc3"></a>33.8.2.4 %feature("autodoc", "3")</H4> +<H4><a name="Ruby_feature_autodoc3"></a>35.8.2.4 %feature("autodoc", "3")</H4> <p> @@ -8464,7 +8454,7 @@ this: -<H4><a name="Ruby_nn70"></a>33.8.2.5 %feature("autodoc", "docstring")</H4> +<H4><a name="Ruby_nn70"></a>35.8.2.5 %feature("autodoc", "docstring")</H4> <p> @@ -8492,7 +8482,7 @@ generated string. For example: -<H3><a name="Ruby_nn71"></a>33.8.3 %feature("docstring")</H3> +<H3><a name="Ruby_nn71"></a>35.8.3 %feature("docstring")</H3> <p> @@ -8507,10 +8497,10 @@ docstring and they are output together. </p> -<H2><a name="Ruby_nn53"></a>33.9 Advanced Topics</H2> +<H2><a name="Ruby_nn53"></a>35.9 Advanced Topics</H2> -<H3><a name="Ruby_operator_overloading"></a>33.9.1 Operator overloading</H3> +<H3><a name="Ruby_operator_overloading"></a>35.9.1 Operator overloading</H3> <p> SWIG allows operator overloading with, by using the <tt>%extend</tt> @@ -9527,7 +9517,7 @@ parses the expression <i>a != b</i> as <i>!(a == b)</i>. -<H3><a name="Ruby_nn55"></a>33.9.2 Creating Multi-Module Packages</H3> +<H3><a name="Ruby_nn55"></a>35.9.2 Creating Multi-Module Packages</H3> <p> The chapter on <a href="Modules.html#Modules">Working @@ -9708,7 +9698,7 @@ initialized: </p> -<H3><a name="Ruby_nn56"></a>33.9.3 Specifying Mixin Modules</H3> +<H3><a name="Ruby_nn56"></a>35.9.3 Specifying Mixin Modules</H3> <p> The Ruby language doesn't support multiple inheritance, but @@ -9806,7 +9796,7 @@ Features"</a>) for more details). </p> -<H2><a name="Ruby_nn57"></a>33.10 Memory Management</H2> +<H2><a name="Ruby_nn57"></a>35.10 Memory Management</H2> <p>One of the most common issues in generating SWIG bindings for @@ -9853,7 +9843,7 @@ understanding of how the underlying library manages memory.</p> -<H3><a name="Ruby_nn58"></a>33.10.1 Mark and Sweep Garbage Collector </H3> +<H3><a name="Ruby_nn58"></a>35.10.1 Mark and Sweep Garbage Collector </H3> <p>Ruby uses a mark and sweep garbage collector. When the garbage @@ -9901,7 +9891,7 @@ this memory. </p> -<H3><a name="Ruby_nn59"></a>33.10.2 Object Ownership</H3> +<H3><a name="Ruby_nn59"></a>35.10.2 Object Ownership</H3> <p>As described above, memory management depends on clearly @@ -10098,7 +10088,38 @@ classes is:</p> <div class="code"> -<pre>/* File RubyOwnershipExample.i */<br><br>%module RubyOwnershipExample<br><br>%{<br>#include "RubyOwnershipExample.h"<br>%}<br><br>class Foo<br>{<br>public:<br> Foo();<br> ~Foo();<br>};<br><br>class Bar<br>{<br> Foo *foo_;<br>public:<br> Bar();<br> ~Bar();<br> Foo* get_foo();<br><br><span style="font-weight: bold;"> %newobject get_new_foo;</span><br> Foo* get_new_foo();<br><br><span style="font-weight: bold;"> %apply SWIGTYPE *DISOWN {Foo *foo};</span><br> void set_foo(Foo *foo);<br><span style="font-weight: bold;"> %clear Foo *foo;</span><br>};<br><br></pre> +<pre>/* File RubyOwnershipExample.i */ + +%module RubyOwnershipExample + +%{ +#include "RubyOwnershipExample.h" +%} + +class Foo +{ +public: + Foo(); + ~Foo(); +}; + +class Bar +{ + Foo *foo_; +public: + Bar(); + ~Bar(); + Foo* get_foo(); + +<b> %newobject get_new_foo;</b> + Foo* get_new_foo(); + +<b> %apply SWIGTYPE *DISOWN {Foo *foo};</b> + void set_foo(Foo *foo); +<b> %clear Foo *foo;</b> +}; + +</pre> @@ -10128,7 +10149,7 @@ classes is:</p> -<H3><a name="Ruby_nn60"></a>33.10.3 Object Tracking</H3> +<H3><a name="Ruby_nn60"></a>35.10.3 Object Tracking</H3> <p>The remaining parts of this section will use the class library @@ -10165,7 +10186,35 @@ class library models a zoo and the animals it contains. </p> <div class="code targetlang"> -<pre>$ <span style="font-weight: bold;">irb</span><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be3820><br><br>irb(main):004:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>=> "tiger1"<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0a60><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo.get_num_animals()</span><br>=> 1<br><br>irb(main):007:0> <span style="font-weight: bold;">tiger2 = zoo.remove_animal(0)</span><br>=> #<Example::Animal:0x2bd4a18><br><br>irb(main):008:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>=> "tiger1"<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.equal?(tiger2)</span><br>=> false<br><br></pre> +<pre>$ <b>irb</b> +irb(main):001:0> <b>require 'example'</b> +=> true + +irb(main):002:0> <b>tiger1 = Example::Animal.new("tiger1")</b> +=> #<Example::Animal:0x2be3820> + +irb(main):004:0> <b>tiger1.get_name()</b> +=> "tiger1" + +irb(main):003:0> <b>zoo = Example::Zoo.new()</b> +=> #<Example::Zoo:0x2be0a60> + +irb(main):006:0> <b>zoo.add_animal(tiger)</b> +=> nil + +irb(main):007:0> <b>zoo.get_num_animals()</b> +=> 1 + +irb(main):007:0> <b>tiger2 = zoo.remove_animal(0)</b> +=> #<Example::Animal:0x2bd4a18> + +irb(main):008:0> <b>tiger2.get_name()</b> +=> "tiger1" + +irb(main):009:0> <b>tiger1.equal?(tiger2)</b> +=> false + +</pre> @@ -10192,7 +10241,16 @@ the same underlying C++ object. This can cause problems. For example:<br> <div class="code targetlang"> -<pre>irb(main):010:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):011:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):012:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>(irb):12: [BUG] Segmentation fault<br><br></pre> +<pre>irb(main):010:0> <b>tiger1 = nil</b> +=> nil + +irb(main):011:0> <b>GC.start</b> +=> nil + +irb(main):012:0> <b>tiger2.get_name()</b> +(irb):12: [BUG] Segmentation fault + +</pre> @@ -10251,7 +10309,7 @@ class-by-class basis if needed. To fix the example above:</p> <div class="code"> -<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br><span style="font-weight: bold;">/* Tell SWIG that create_animal creates a new object */</span><br><span style="font-weight: bold;">%newobject Zoo::create_animal;</span><br><br><span style="font-weight: bold;">/* Tell SWIG to keep track of mappings between C/C++ structs/classes. */</span><br style="font-weight: bold;"><span style="font-weight: bold;">%trackobjects;</span><br><br>%include "example.h"</pre> +<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br><b>/* Tell SWIG that create_animal creates a new object */</b><br><b>%newobject Zoo::create_animal;</b><br><br><b>/* Tell SWIG to keep track of mappings between C/C++ structs/classes. */</b><br style="font-weight: bold;"><b>%trackobjects;</b><br><br>%include "example.h"</pre> @@ -10282,7 +10340,7 @@ class-by-class basis if needed. To fix the example above:</p> <div class="code targetlang"> -<pre>$ <span style="font-weight: bold;">irb</span><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0a18><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):006:0> <span style="font-weight: bold;">tiger2 = zoo.remove_animal(0)</span><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):007:0> <span style="font-weight: bold;">tiger1.equal?(tiger2)</span><br>=> true<br><br>irb(main):008:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):010:0> <span style="font-weight: bold;">tiger.get_name()</span><br>=> "tiger1"<br>irb(main):011:0><br><br></pre> +<pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'example'</b><br>=> true<br><br>irb(main):002:0> <b>tiger1 = Example::Animal.new("tiger1")</b><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):003:0> <b>zoo = Example::Zoo.new()</b><br>=> #<Example::Zoo:0x2be0a18><br><br>irb(main):004:0> <b>zoo.add_animal(tiger1)</b><br>=> nil<br><br>irb(main):006:0> <b>tiger2 = zoo.remove_animal(0)</b><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):007:0> <b>tiger1.equal?(tiger2)</b><br>=> true<br><br>irb(main):008:0> <b>tiger1 = nil</b><br>=> nil<br><br>irb(main):009:0> <b>GC.start</b><br>=> nil<br><br>irb(main):010:0> <b>tiger.get_name()</b><br>=> "tiger1"<br>irb(main):011:0><br><br></pre> @@ -10342,7 +10400,7 @@ methods.</p> -<H3><a name="Ruby_nn61"></a>33.10.4 Mark Functions</H3> +<H3><a name="Ruby_nn61"></a>35.10.4 Mark Functions</H3> <p>With a bit more testing, we see that our class library still @@ -10359,7 +10417,7 @@ has problems. For example:<br> <div class="targetlang"> -<pre>$ <b>irb</b><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> tiger1 = <span style="font-weight: bold;">Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bea6a8><br><br>irb(main):003:0> zoo = <span style="font-weight: bold;">Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be7960><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):005:0> <span style="font-weight: bold;">tiger2 = zoo.get_animal(0)</span><br>(irb):12: [BUG] Segmentation fault</pre> +<pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'example'</b><br>=> true<br><br>irb(main):002:0> tiger1 = <b>Example::Animal.new("tiger1")</b><br>=> #<Example::Animal:0x2bea6a8><br><br>irb(main):003:0> zoo = <b>Example::Zoo.new()</b><br>=> #<Example::Zoo:0x2be7960><br><br>irb(main):004:0> <b>zoo.add_animal(tiger1)</b><br>=> nil<br><br>irb(main):007:0> <b>tiger1 = nil</b><br>=> nil<br><br>irb(main):007:0> <b>GC.start</b><br>=> nil<br><br>irb(main):005:0> <b>tiger2 = zoo.get_animal(0)</b><br>(irb):12: [BUG] Segmentation fault</pre> @@ -10407,7 +10465,7 @@ implementation is:</p> <div class="code"> -<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>/* Keep track of mappings between C/C++ structs/classes<br> and Ruby objects so we can implement a mark function. */<br><span style="font-weight: bold;">%trackobjects;</span><br><br>/* Specify the mark function */<br><span style="font-weight: bold;">%markfunc Zoo "mark_Zoo";</span><br><br>%include "example.h"<br><br>%header %{<br><br>static void mark_Zoo(void* ptr) {<br> Zoo* zoo = (Zoo*) ptr;<br><br> /* Loop over each object and tell the garbage collector<br> that we are holding a reference to them. */<br> int count = zoo->get_num_animals();<br><br> for(int i = 0; i < count; ++i) {<br> Animal* animal = zoo->get_animal(i);<br> VALUE object = SWIG_RubyInstanceFor(animal);<br><br> if (object != Qnil) {<br> rb_gc_mark(object);<br> }<br> }<br>}<br>%}<br><br></pre> +<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>/* Keep track of mappings between C/C++ structs/classes<br> and Ruby objects so we can implement a mark function. */<br><b>%trackobjects;</b><br><br>/* Specify the mark function */<br><b>%markfunc Zoo "mark_Zoo";</b><br><br>%include "example.h"<br><br>%header %{<br><br>static void mark_Zoo(void* ptr) {<br> Zoo* zoo = (Zoo*) ptr;<br><br> /* Loop over each object and tell the garbage collector<br> that we are holding a reference to them. */<br> int count = zoo->get_num_animals();<br><br> for(int i = 0; i < count; ++i) {<br> Animal* animal = zoo->get_animal(i);<br> VALUE object = SWIG_RubyInstanceFor(animal);<br><br> if (object != Qnil) {<br> rb_gc_mark(object);<br> }<br> }<br>}<br>%}<br><br></pre> @@ -10436,7 +10494,7 @@ test suite.</p> <div class="targetlang"> -<pre>$ <b>irb<br></b>irb(main):002:0> <span style="font-weight: bold;">tiger1=Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):003:0> <span style="font-weight: bold;">Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be1780><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2bde9c0><br><br>irb(main):005:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):010:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br>irb(main):014:0> <span style="font-weight: bold;">tiger2 = zoo.get_animal(0)</span><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):015:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>=> "tiger1"<br>irb(main):016:0><br><br></pre> +<pre>$ <b>irb<br></b>irb(main):002:0> <b>tiger1=Example::Animal.new("tiger1")</b><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):003:0> <b>Example::Zoo.new()</b><br>=> #<Example::Zoo:0x2be1780><br><br>irb(main):004:0> <b>zoo = Example::Zoo.new()</b><br>=> #<Example::Zoo:0x2bde9c0><br><br>irb(main):005:0> <b>zoo.add_animal(tiger1)</b><br>=> nil<br><br>irb(main):009:0> <b>tiger1 = nil</b><br>=> nil<br><br>irb(main):010:0> <b>GC.start</b><br>=> nil<br>irb(main):014:0> <b>tiger2 = zoo.get_animal(0)</b><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):015:0> <b>tiger2.get_name()</b><br>=> "tiger1"<br>irb(main):016:0><br><br></pre> @@ -10460,7 +10518,7 @@ test suite.</p> -<H3><a name="Ruby_nn62"></a>33.10.5 Free Functions</H3> +<H3><a name="Ruby_nn62"></a>35.10.5 Free Functions</H3> <p>By default, SWIG creates a "free" function that is called when @@ -10512,14 +10570,22 @@ directive, let's slightly change our example. Assume that the zoo object is responsible for freeing animal that it contains. This means that the <span style="font-family: monospace;">Zoo::add_animal</span> function should be marked with a <span style="font-family: monospace;">DISOWN</span> typemap -and the destructor should be updated as below::</p> +and the destructor should be updated as below:</p> <div class="code"> -<pre>Zoo::~Zoo() {<br> IterType iter = this->animals.begin();<br> IterType end = this->animals.end();<br><br> for(iter; iter != end; ++iter) {<br> Animal* animal = *iter;<br> delete animal;<br> }<br>}</pre> +<pre>Zoo::~Zoo() { + IterType iter = this->animals.begin(); + IterType end = this->animals.end(); + + for(iter; iter != end; ++iter) { + Animal* animal = *iter; + delete animal; + } +}</pre> @@ -10538,7 +10604,29 @@ and the destructor should be updated as below::</p> <div class="code targetlang"> -<pre class="targetlang"><span style="font-weight: bold;">$irb</span><br>irb(main):002:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0fe8><br><br>irb(main):005:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bda760><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo = nil</span><br>=> nil<br><br>irb(main):008:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>(irb):12: [BUG] Segmentation fault<br><br></pre> +<pre class="targetlang"><b>$irb</b> +irb(main):002:0> <b>require 'example'</b> +=> true + +irb(main):003:0> <b>zoo = Example::Zoo.new()</b> +=> #<Example::Zoo:0x2be0fe8> + +irb(main):005:0> <b>tiger1 = Example::Animal.new("tiger1")</b> +=> #<Example::Animal:0x2bda760> + +irb(main):006:0> <b>zoo.add_animal(tiger1)</b> +=> nil + +irb(main):007:0> <b>zoo = nil</b> +=> nil + +irb(main):008:0> <b>GC.start</b> +=> nil + +irb(main):009:0> <b>tiger1.get_name()</b> +(irb):12: [BUG] Segmentation fault + +</pre> @@ -10571,7 +10659,49 @@ existing Ruby object to the destroyed C++ object and raise an exception.<br> <div class="code"> -<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>/* Specify that ownership is transferred to the zoo<br> when calling add_animal */<br>%apply SWIGTYPE *DISOWN { Animal* animal };<br><br>/* Track objects */<br>%trackobjects;<br><br>/* Specify the mark function */<br>%freefunc Zoo "free_Zoo";<br><br>%include "example.h"<br><br>%header %{<br> static void free_Zoo(void* ptr) {<br> Zoo* zoo = (Zoo*) ptr;<br><br> /* Loop over each animal */<br> int count = zoo->get_num_animals();<br><br> for(int i = 0; i < count; ++i) {<br> /* Get an animal */<br> Animal* animal = zoo->get_animal(i);<br><br> /* Unlink the Ruby object from the C++ object */<br> SWIG_RubyUnlinkObjects(animal);<br><br> /* Now remove the tracking for this animal */<br> SWIG_RubyRemoveTracking(animal);<br> }<br><br> /* Now call SWIG_RubyRemoveTracking for the zoo */<br> SWIG_RubyRemoveTracking(ptr);<br> <br> /* Now free the zoo which will free the animals it contains */<br> delete zoo;<br> }<br>%} </pre> +<pre>%module example + +%{ +#include "example.h" +%} + +/* Specify that ownership is transferred to the zoo + when calling add_animal */ +%apply SWIGTYPE *DISOWN { Animal* animal }; + +/* Track objects */ +%trackobjects; + +/* Specify the mark function */ +%freefunc Zoo "free_Zoo"; + +%include "example.h" + +%header %{ + static void free_Zoo(void* ptr) { + Zoo* zoo = (Zoo*) ptr; + + /* Loop over each animal */ + int count = zoo->get_num_animals(); + + for(int i = 0; i < count; ++i) { + /* Get an animal */ + Animal* animal = zoo->get_animal(i); + + /* Unlink the Ruby object from the C++ object */ + SWIG_RubyUnlinkObjects(animal); + + /* Now remove the tracking for this animal */ + SWIG_RubyRemoveTracking(animal); + } + + /* Now call SWIG_RubyRemoveTracking for the zoo */ + SWIG_RubyRemoveTracking(ptr); + + /* Now free the zoo which will free the animals it contains */ + delete zoo; + } +%} </pre> @@ -10590,7 +10720,30 @@ existing Ruby object to the destroyed C++ object and raise an exception.<br> <div class="code targetlang"> -<pre><span style="font-weight: bold;">$irb</span><br>irb(main):002:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0fe8><br><br>irb(main):005:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bda760><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo = nil</span><br>=> nil<br><br>irb(main):008:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>RuntimeError: This Animal * already released<br> from (irb):10:in `get_name'<br> from (irb):10<br>irb(main):011:0></pre> +<pre><b>$irb</b> +irb(main):002:0> <b>require 'example'</b> +=> true + +irb(main):003:0> <b>zoo = Example::Zoo.new()</b> +=> #<Example::Zoo:0x2be0fe8> + +irb(main):005:0> <b>tiger1 = Example::Animal.new("tiger1")</b> +=> #<Example::Animal:0x2bda760> + +irb(main):006:0> <b>zoo.add_animal(tiger1)</b> +=> nil + +irb(main):007:0> <b>zoo = nil</b> +=> nil + +irb(main):008:0> <b>GC.start</b> +=> nil + +irb(main):009:0> <b>tiger1.get_name()</b> +RuntimeError: This Animal * already released + from (irb):10:in `get_name' + from (irb):10 +irb(main):011:0></pre> @@ -10615,7 +10768,7 @@ been freed, and thus raises a runtime exception.</p> -<H3><a name="Ruby_nn63"></a>33.10.6 Embedded Ruby and the C++ Stack</H3> +<H3><a name="Ruby_nn63"></a>35.10.6 Embedded Ruby and the C++ Stack</H3> <p>As has been said, the Ruby GC runs and marks objects before |