1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
18 <title>SWIG and Ruby</title>
19 <link rel="stylesheet" type="text/css" href="style.css">
23 <body style="background-color: rgb(255, 255, 255);">
29 <H1><a name="Ruby"></a>32 SWIG and Ruby</H1>
31 <div class="sectiontoc">
33 <li><a href="#Ruby_nn2">Preliminaries</a>
35 <li><a href="#Ruby_nn3">Running SWIG</a>
36 <li><a href="#Ruby_nn4">Getting the right header files</a>
37 <li><a href="#Ruby_nn5">Compiling a dynamic module</a>
38 <li><a href="#Ruby_nn6">Using your module</a>
39 <li><a href="#Ruby_nn7">Static linking</a>
40 <li><a href="#Ruby_nn8">Compilation of C++ extensions</a>
42 <li><a href="#Ruby_nn9">Building Ruby Extensions under Windows 95/NT</a>
44 <li><a href="#Ruby_nn10">Running SWIG from Developer Studio</a>
46 <li><a href="#Ruby_nn11">The Ruby-to-C/C++ Mapping</a>
48 <li><a href="#Ruby_nn12">Modules</a>
49 <li><a href="#Ruby_nn13">Functions</a>
50 <li><a href="#Ruby_nn14">Variable Linking</a>
51 <li><a href="#Ruby_nn15">Constants</a>
52 <li><a href="#Ruby_nn16">Pointers</a>
53 <li><a href="#Ruby_nn17">Structures</a>
54 <li><a href="#Ruby_nn18">C++ classes</a>
55 <li><a href="#Ruby_nn19">C++ Inheritance</a>
56 <li><a href="#Ruby_nn20">C++ Overloaded Functions</a>
57 <li><a href="#Ruby_nn21">C++ Operators</a>
58 <li><a href="#Ruby_nn22">C++ namespaces</a>
59 <li><a href="#Ruby_nn23">C++ templates</a>
60 <li><a href="#Ruby_nn23_1">C++ Standard Template Library (STL)</a>
61 <li><a href="#C_STL_Functors">C++ STL Functors</a>
62 <li><a href="#Ruby_C_Iterators">C++ STL Iterators</a>
63 <li><a href="#Ruby_nn24">C++ Smart Pointers</a>
64 <li><a href="#Ruby_nn25">Cross-Language Polymorphism</a>
66 <li><a href="#Ruby_nn26">Exception Unrolling</a>
69 <li><a href="#Ruby_nn27">Naming</a>
71 <li><a href="#Ruby_nn28">Defining Aliases</a>
72 <li><a href="#Ruby_nn29">Predicate Methods</a>
73 <li><a href="#Ruby_nn30">Bang Methods</a>
74 <li><a href="#Ruby_nn31">Getters and Setters</a>
76 <li><a href="#Ruby_nn32">Input and output parameters</a>
77 <li><a href="#Ruby_nn33">Exception handling </a>
79 <li><a href="#Ruby_nn34">Using the %exception directive </a>
80 <li><a href="#Ruby_nn34_2">Handling Ruby Blocks </a>
81 <li><a href="#Ruby_nn35">Raising exceptions </a>
82 <li><a href="#Ruby_nn36">Exception classes </a>
84 <li><a href="#Ruby_nn37">Typemaps</a>
86 <li><a href="#Ruby_nn38">What is a typemap?</a>
87 <li><a href="#Ruby_Typemap_scope">Typemap scope</a>
88 <li><a href="#Ruby_Copying_a_typemap">Copying a typemap</a>
89 <li><a href="#Ruby_Deleting_a_typemap">Deleting a typemap</a>
90 <li><a href="#Ruby_Placement_of_typemaps">Placement of typemaps</a>
91 <li><a href="#Ruby_nn39">Ruby typemaps</a>
93 <li><a href="#Ruby_in_typemap"> "in" typemap</a>
94 <li><a href="#Ruby_typecheck_typemap">"typecheck" typemap</a>
95 <li><a href="#Ruby_out_typemap"> "out" typemap</a>
96 <li><a href="#Ruby_arginit_typemap">"arginit" typemap</a>
97 <li><a href="#Ruby_default_typemap">"default" typemap</a>
98 <li><a href="#Ruby_check_typemap">"check" typemap</a>
99 <li><a href="#Ruby_argout_typemap_">"argout" typemap</a>
100 <li><a href="#Ruby_freearg_typemap_">"freearg" typemap</a>
101 <li><a href="#Ruby_newfree_typemap">"newfree" typemap</a>
102 <li><a href="#Ruby_memberin_typemap">"memberin" typemap</a>
103 <li><a href="#Ruby_varin_typemap">"varin" typemap</a>
104 <li><a href="#Ruby_varout_typemap_">"varout" typemap</a>
105 <li><a href="#Ruby_throws_typemap">"throws" typemap</a>
106 <li><a href="#Ruby_directorin_typemap">directorin typemap</a>
107 <li><a href="#Ruby_directorout_typemap">directorout typemap</a>
108 <li><a href="#Ruby_directorargout_typemap">directorargout typemap</a>
109 <li><a href="#Ruby_ret_typemap">ret typemap</a>
110 <li><a href="#Ruby_globalin_typemap">globalin typemap</a>
112 <li><a href="#Ruby_nn40">Typemap variables</a>
113 <li><a href="#Ruby_nn41">Useful Functions</a>
115 <li><a href="#Ruby_nn42">C Datatypes to Ruby Objects</a>
116 <li><a href="#Ruby_nn43">Ruby Objects to C Datatypes</a>
117 <li><a href="#Ruby_nn44">Macros for VALUE</a>
118 <li><a href="#Ruby_nn45">Exceptions</a>
119 <li><a href="#Ruby_nn46">Iterators</a>
121 <li><a href="#Ruby_nn47">Typemap Examples</a>
122 <li><a href="#Ruby_nn48">Converting a Ruby array to a char **</a>
123 <li><a href="#Ruby_nn49">Collecting arguments in a hash</a>
124 <li><a href="#Ruby_nn50">Pointer handling</a>
126 <li><a href="#Ruby_nn51">Ruby Datatype Wrapping</a>
128 <li><a href="#Ruby_nn52">Example: STL Vector to Ruby Array</a>
130 <li><a href="#Ruby_nn65">Docstring Features</a>
132 <li><a href="#Ruby_nn66">Module docstring</a>
133 <li><a href="#Ruby_nn67">%feature("autodoc")</a>
135 <li><a href="#Ruby_nn68">%feature("autodoc", "0")</a>
136 <li><a href="#Ruby_autodoc1">%feature("autodoc", "1")</a>
137 <li><a href="#Ruby_autodoc2">%feature("autodoc", "2")</a>
138 <li><a href="#Ruby_feature_autodoc3">%feature("autodoc", "3")</a>
139 <li><a href="#Ruby_nn70">%feature("autodoc", "docstring")</a>
141 <li><a href="#Ruby_nn71">%feature("docstring")</a>
143 <li><a href="#Ruby_nn53">Advanced Topics</a>
145 <li><a href="#Ruby_nn54">Operator overloading</a>
146 <li><a href="#Ruby_nn55">Creating Multi-Module Packages</a>
147 <li><a href="#Ruby_nn56">Specifying Mixin Modules</a>
149 <li><a href="#Ruby_nn57">Memory Management</a>
151 <li><a href="#Ruby_nn58">Mark and Sweep Garbage Collector </a>
152 <li><a href="#Ruby_nn59">Object Ownership</a>
153 <li><a href="#Ruby_nn60">Object Tracking</a>
154 <li><a href="#Ruby_nn61">Mark Functions</a>
155 <li><a href="#Ruby_nn62">Free Functions</a>
156 <li><a href="#Ruby_nn63">Embedded Ruby and the C++ Stack</a>
164 <p>This chapter describes SWIG's support of Ruby.</p>
170 <H2><a name="Ruby_nn2"></a>32.1 Preliminaries</H2>
173 <p> SWIG 1.3 is known to work with Ruby versions 1.6 and later.
174 Given the choice, you should use the latest stable version of Ruby. You
175 should also determine if your system supports shared libraries and
176 dynamic loading. SWIG will work with or without dynamic loading, but
177 the compilation process will vary. </p>
183 <p>This chapter covers most SWIG features, but in less depth than
184 is found in earlier chapters. At the very least, make sure you also
185 read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
186 chapter. It is also assumed that the reader has a basic understanding
193 <H3><a name="Ruby_nn3"></a>32.1.1 Running SWIG</H3>
196 <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
203 <div class="code shell">
204 <pre>$ <b>swig -ruby example.i</b>
217 <p> If building a C++ extension, add the <tt>-c++</tt>
224 <div class="code shell">
225 <pre>$ <b>swig -c++ -ruby example.i</b>
238 <p> This creates a file <tt>example_wrap.c</tt> (<tt>example_wrap.cxx</tt>
239 if compiling a C++ extension) that contains all of the code needed to
240 build a Ruby extension module. To finish building the module, you need
241 to compile this file and link it with the rest of your program. </p>
247 <H3><a name="Ruby_nn4"></a>32.1.2 Getting the right header files</H3>
250 <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
251 header file. This file is usually contained in a directory such as </p>
257 <div class="code shell diagram">
258 <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>
270 <p> The exact location may vary on your machine, but the above
271 location is typical. If you are not entirely sure where Ruby is
272 installed, you can run Ruby to find out. For example: </p>
278 <div class="code shell">
279 <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>
291 <H3><a name="Ruby_nn5"></a>32.1.3 Compiling a dynamic module</H3>
294 <p> Ruby extension modules are typically compiled into shared
295 libraries that the interpreter loads dynamically at runtime. Since the
296 exact commands for doing this vary from platform to platform, your best
297 bet is to follow the steps described in the <tt>README.EXT</tt>
298 file from the Ruby distribution: </p>
315 <p>Create a file called <tt>extconf.rb</tt> that
316 looks like the following:</p>
326 <div class="code targetlang">
331 <pre>require 'mkmf'<br>create_makefile('example')<br></pre>
354 <p>Type the following to build the extension:</p>
364 <div class="code shell">
369 <pre>$ <b>ruby extconf.rb</b><br>$ <b>make</b><br>$ <b>make install</b>
394 <p> Of course, there is the problem that mkmf does not work
395 correctly on all platforms, e.g, HPUX. If you need to add your own make
396 rules to the file that <tt>extconf.rb</tt> produces, you
403 <div class="code targetlang">
404 <pre>open("Makefile", "a") { |mf|<br> puts <<EOM<br> # Your make rules go here<br> EOM<br>}<br></pre>
416 <p> to the end of the <tt>extconf.rb</tt> file. If
417 for some reason you don't want to use the standard approach, you'll
418 need to determine the correct compiler and linker flags for your build
419 platform. For example, a typical sequence of commands for the Linux
420 operating system would look something like this: </p>
426 <div class="code shell">
427 <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>
440 <p> For other platforms it may be necessary to compile with the <tt>-fPIC</tt>
441 option to generate position-independent code. If in doubt, consult the
442 manual pages for your compiler and linker to determine the correct set
443 of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a>
444 for additional information. </p>
446 <H3><a name="Ruby_nn6"></a>32.1.4 Using your module</H3>
449 <p> Ruby <i>module</i> names must be capitalized,
450 but the convention for Ruby <i>feature</i> names is to use
451 lowercase names. So, for example, the <b>Etc</b> extension
452 module is imported by requiring the <b>etc</b> feature: </p>
458 <div class="code targetlang">
459 <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>
471 <p> To stay consistent with this practice, you should always
472 specify a <b>lowercase</b> module name with SWIG's <tt>%module</tt>
473 directive. SWIG will automatically correct the resulting Ruby module
474 name for your extension. So for example, a SWIG interface file that
482 <pre>%module example<br></pre>
494 <p> will result in an extension module using the feature name
495 "example" and Ruby module name "Example". </p>
501 <H3><a name="Ruby_nn7"></a>32.1.5 Static linking</H3>
504 <p> An alternative approach to dynamic linking is to rebuild the
505 Ruby interpreter with your extension module added to it. In the past,
506 this approach was sometimes necessary due to limitations in dynamic
507 loading support on certain machines. However, the situation has
508 improved greatly over the last few years and you should not consider
509 this approach unless there is really no other option. </p>
515 <p>The usual procedure for adding a new module to Ruby involves
516 finding the Ruby source, adding an entry to the <tt>ext/Setup</tt>
517 file, adding your directory to the list of extensions in the file, and
518 finally rebuilding Ruby. </p>
522 <H3><a name="Ruby_nn8"></a>32.1.6 Compilation of C++ extensions</H3>
525 <p> On most machines, C++ extension modules should be linked
526 using the C++ compiler. For example: </p>
532 <div class="code shell">
533 <pre>$ <b>swig -c++ -ruby example.i</b><br>$ <b>g++ -c example.cxx</b><br>$ <b>g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux</b><br>$ <b>g++ -shared example.o example_wrap.o -o example.so</b>
546 <p> If you've written an <tt>extconf.rb</tt> script
547 to automatically generate a <tt>Makefile</tt> for your C++
548 extension module, keep in mind that (as of this writing) Ruby still
549 uses <tt>gcc</tt> and not <tt>g++</tt> as its
550 linker. As a result, the required C++ runtime library support will not
551 be automatically linked into your extension module and it may fail to
552 load on some platforms. A workaround for this problem is use the <tt>mkmf</tt>
553 module's <tt>append_library()</tt> method to add one of
554 the C++ runtime libraries to the list of libraries linked into your
561 <div class="code targetlang">
562 <pre>require 'mkmf'<br>$libs = append_library($libs, "supc++")<br>create_makefile('example')<br></pre>
574 <H2><a name="Ruby_nn9"></a>32.2 Building Ruby Extensions under Windows 95/NT</H2>
577 <p> Building a SWIG extension to Ruby under Windows 95/NT is
578 roughly similar to the process used with Unix. Normally, you will want
579 to produce a DLL that can be loaded into the Ruby interpreter. For all
580 recent versions of Ruby, the procedure described above (i.e. using an <tt>extconf.rb</tt>
581 script) will work with Windows as well; you should be able to build
582 your code into a DLL by typing: </p>
588 <div class="code shell">
589 <pre>C:\swigtest> <b>ruby extconf.rb</b><br>C:\swigtest> <b>nmake</b><br>C:\swigtest> <b>nmake install</b>
602 <p> The remainder of this section covers the process of compiling
603 SWIG-generated Ruby extensions with Microsoft Visual C++ 6 (i.e. within
604 the Developer Studio IDE, instead of using the command line tools). In
605 order to build extensions, you may need to download the source
606 distribution to the Ruby package, as you will need the Ruby header
613 <H3><a name="Ruby_nn10"></a>32.2.1 Running SWIG from Developer Studio</H3>
616 <p> If you are developing your application within Microsoft
617 developer studio, SWIG can be invoked as a custom build option. The
618 process roughly follows these steps : </p>
630 <li> Open up a new workspace and use the AppWizard to select a
637 <li> Add both the SWIG interface file (the .i file), any
638 supporting C files, and the name of the wrapper file that will be
639 created by SWIG (i.e. <tt>example_wrap.c</tt>). Note : If
640 using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>.
641 Don't worry if the wrapper file doesn't exist yet--Developer Studio
642 will keep a reference to it around. </li>
648 <li> Select the SWIG interface file and go to the settings
649 menu. Under settings, select the "Custom Build" option. </li>
655 <li> Enter "SWIG" in the description field. </li>
661 <li> Enter "<tt>swig -ruby -o
662 $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build
663 command(s) field". You may have to include the path to swig.exe. </li>
669 <li> Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>"
670 in the "Output files(s) field". </li>
676 <li> Next, select the settings for the entire project and go to
677 the C/C++ tab and select the Preprocessor category. Add NT=1 to the
678 Preprocessor definitions. This must be set else you will get
679 compilation errors. Also add IMPORT to the preprocessor definitions,
680 else you may get runtime errors. Also add the include directories for
681 your Ruby installation under "Additional include directories". </li>
687 <li> Next, select the settings for the entire project and go to
688 the Link tab and select the General category. Set the name of the
689 output file to match the name of your Ruby module (i.e.. example.dll).
690 Next add the Ruby library file to your link libraries under
691 Object/Library modules. For example "mswin32-ruby16.lib. You also need
692 to add the path to the library under the Input tab - Additional library
699 <li> Build your project. </li>
711 <p> Now, assuming all went well, SWIG will be automatically
712 invoked when you build your project. Any changes made to the interface
713 file will result in SWIG being automatically invoked to produce a new
714 version of the wrapper file. To run your new Ruby extension, simply run
715 Ruby and use the <tt>require</tt> command as normal. For
716 example if you have this ruby file run.rb:</p>
722 <div class="code targetlang">
723 <pre># file: run.rb<br>require 'Example'<br><br># Call a c function<br>print "Foo = ", Example.Foo, "\n"<br></pre>
735 <p> Ensure the dll just built is in your path or current
736 directory, then run the Ruby script from the DOS/Command prompt: </p>
742 <div class="code shell">
743 <pre>C:\swigtest> <b>ruby run.rb</b><br>Foo = 3.0<br></pre>
755 <H2><a name="Ruby_nn11"></a>32.3 The Ruby-to-C/C++ Mapping</H2>
758 <p> This section describes the basics of how SWIG maps C or C++
759 declarations in your SWIG interface files to Ruby constructs. </p>
765 <H3><a name="Ruby_nn12"></a>32.3.1 Modules</H3>
768 <p> The SWIG <tt>%module</tt> directive specifies
769 the name of the Ruby module. If you specify: </p>
776 <pre>%module example</pre>
788 <p> then everything is wrapped into a Ruby module named <tt>Example</tt>
789 that is nested directly under the global module. You can specify a more
790 deeply nested module by specifying the fully-qualified module name in
798 <pre>%module "foo::bar::spam"</pre>
810 <p> An alternate method of specifying a nested module name is to
811 use the <span style="font-family: monospace;">-prefix</span>
812 option on the SWIG command line. The prefix that you specify with this
813 option will be prepended to the module name specified with the <span style="font-family: monospace;">%module</span>
814 directive in your SWIG interface file. So for example, this declaration
815 at the top of your SWIG interface file:<br>
828 <pre>%module "foo::bar::spam"</pre>
840 <p> will result in a nested module name of <span style="font-family: monospace;">Foo::Bar::Spam</span>,
841 but you can achieve the <span style="font-style: italic;">same</span>
842 effect by specifying:<br>
855 <pre>%module spam</pre>
867 <p> and then running SWIG with the <span style="font-family: monospace;">-prefix</span> command
880 <div class="code shell">
881 <pre>$ <b>swig -ruby -prefix "foo::bar::" example.i</b></pre>
893 <p> Starting with SWIG 1.3.20, you can also choose to wrap
894 everything into the global module by specifying the <tt>-globalmodule</tt>
895 option on the SWIG command line, i.e. </p>
901 <div class="code shell">
902 <pre>$ <b>swig -ruby -globalmodule example.i</b></pre>
914 <p> Note that this does not relieve you of the requirement of
915 specifying the SWIG module name with the <tt>%module</tt>
916 directive (or the <tt>-module</tt> command-line option) as
917 described earlier. </p>
923 <p>When choosing a module name, do not use the same name as a
924 built-in Ruby command or standard module name, as the results may be
925 unpredictable. Similarly, if you're using the <tt>-globalmodule</tt>
926 option to wrap everything into the global module, take care that the
927 names of your constants, classes and methods don't conflict with any of
928 Ruby's built-in names. </p>
934 <H3><a name="Ruby_nn13"></a>32.3.2 Functions</H3>
937 <p> Global functions are wrapped as Ruby module methods. For
938 example, given the SWIG interface file <tt>example.i</tt>:
946 <pre>%module example<br><br>int fact(int n);<br></pre>
958 <p> and C source file <tt>example.c</tt>: </p>
965 <pre>int fact(int n) {<br> if (n == 0)<br> return 1;<br> return (n * fact(n-1));<br>}<br></pre>
977 <p> SWIG will generate a method <i>fact</i> in the <i>Example</i>
978 module that can be used like so: </p>
984 <div class="code targetlang">
985 <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>Example.fact(4)</b><br>24<br></pre>
997 <H3><a name="Ruby_nn14"></a>32.3.3 Variable Linking</H3>
1000 <p> C/C++ global variables are wrapped as a pair of singleton
1001 methods for the module: one to get the value of the global variable and
1002 one to set it. For example, the following SWIG interface file declares
1003 two global variables: </p>
1010 <pre>// SWIG interface file with global variables<br>%module example<br>...<br>%inline %{<br>extern int variable1;<br>extern double Variable2;<br>%}<br>...<br></pre>
1022 <p> Now look at the Ruby interface:</p>
1028 <div class="code targetlang">
1029 <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>Example.variable1 = 2</b><br>2<br>irb(main):003:0> <b>Example.Variable2 = 4 * 10.3</b><br>41.2<br>irb(main):004:0> <b>Example.Variable2</b><br>41.2<br></pre>
1041 <p> If you make an error in variable assignment, you will receive
1042 an error message. For example: </p>
1048 <div class="code targetlang">
1049 <pre>irb(main):005:0> <b>Example.Variable2 = "hello"</b><br>TypeError: no implicit conversion to float from string<br>from (irb):5:in `Variable2='<br>from (irb):5<br></pre>
1061 <p> If a variable is declared as <tt>const</tt>, it
1062 is wrapped as a read-only variable. Attempts to modify its value will
1063 result in an error. </p>
1069 <p>To make ordinary variables read-only, you can also use the <tt>%immutable</tt>
1070 directive. For example: </p>
1077 <pre>%immutable;<br>%inline %{<br>extern char *path;<br>%}<br>%mutable;<br></pre>
1089 <p> The <tt>%immutable</tt> directive stays in
1090 effect until it is explicitly disabled using <tt>%mutable</tt>.
1097 <H3><a name="Ruby_nn15"></a>32.3.4 Constants</H3>
1100 <p> C/C++ constants are wrapped as module constants initialized
1101 to the appropriate value. To create a constant, use <tt>#define</tt>
1102 or the <tt>%constant</tt> directive. For example: </p>
1109 <pre>#define PI 3.14159<br>#define VERSION "1.0"<br><br>%constant int FOO = 42;<br>%constant const char *path = "/usr/local";<br><br>const int BAR = 32;<br></pre>
1121 <p> Remember to use the :: operator in Ruby to get at these
1122 constant values, e.g. </p>
1128 <div class="code targetlang">
1129 <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>Example::PI</b><br>3.14159<br></pre>
1141 <H3><a name="Ruby_nn16"></a>32.3.5 Pointers</H3>
1144 <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
1145 aren't explicitly declared in your SWIG interface file) are wrapped as
1146 data objects. So, for example, consider a SWIG interface file
1147 containing only the declarations: </p>
1154 <pre>Foo *get_foo();<br>void set_foo(Foo *foo);<br></pre>
1166 <p> For this case, the <i>get_foo()</i> method
1167 returns an instance of an internally generated Ruby class: </p>
1173 <div class="code targetlang">
1174 <pre>irb(main):001:0> <b>foo = Example::get_foo()</b><br>#<SWIG::TYPE_p_Foo:0x402b1654><br></pre>
1186 <p> A <tt>NULL</tt> pointer is always represented by
1187 the Ruby <tt>nil</tt> object. </p>
1193 <H3><a name="Ruby_nn17"></a>32.3.6 Structures</H3>
1196 <p> C/C++ structs are wrapped as Ruby classes, with accessor
1197 methods (i.e. "getters" and "setters") for all of the struct members.
1198 For example, this struct declaration: </p>
1205 <pre>struct Vector {<br> double x, y;<br>};<br></pre>
1217 <p> gets wrapped as a <tt>Vector</tt> class, with
1218 Ruby instance methods <tt>x</tt>, <tt> x=</tt>,
1219 <tt>y</tt> and <tt>y=</tt>. These methods can
1220 be used to access structure data from Ruby as follows: </p>
1226 <div class="code targetlang">
1227 <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>f = Example::Vector.new</b><br>#<Example::Vector:0x4020b268><br>irb(main):003:0> <b>f.x = 10</b><br>nil<br>irb(main):004:0> <b>f.x</b><br>10.0<br></pre>
1239 <p> Similar access is provided for unions and the public data
1240 members of C++ classes.</p>
1246 <p><tt>const</tt> members of a structure are
1247 read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt>
1248 directive (in C++, <tt>private</tt> may also be used). For
1256 <pre>struct Foo {<br> ...<br> %immutable;<br> int x; /* Read-only members */<br> char *name;<br> %mutable;<br> ...<br>};<br></pre>
1268 <p> When <tt>char *</tt> members of a structure are
1269 wrapped, the contents are assumed to be dynamically allocated using <tt>malloc</tt>
1270 or <tt>new</tt> (depending on whether or not SWIG is run
1271 with the <tt>-c++</tt> option). When the structure member
1272 is set, the old contents will be released and a new value created. If
1273 this is not the behavior you want, you will have to use a typemap
1274 (described shortly). </p>
1280 <p>Array members are normally wrapped as read-only. For example,
1288 <pre>struct Foo {<br> int x[50];<br>};<br></pre>
1300 <p> produces a single accessor function like this: </p>
1307 <pre>int *Foo_x_get(Foo *self) {<br> return self->x;<br>};<br></pre>
1319 <p> If you want to set an array member, you will need to supply a
1320 "memberin" typemap described in the <a href="#ruby_cpp_smart_pointers">section on typemaps</a>.
1321 As a special case, SWIG does generate code to set array members of type
1322 <tt>char</tt> (allowing you to store a Ruby string in the
1329 <p>When structure members are wrapped, they are handled as
1330 pointers. For example, </p>
1337 <pre>struct Foo {<br> ...<br>};<br><br>struct Bar {<br> Foo f;<br>};<br></pre>
1349 <p> generates accessor functions such as this: </p>
1356 <pre>Foo *Bar_f_get(Bar *b) {<br> return &b->f;<br>}<br><br>void Bar_f_set(Bar *b, Foo *val) {<br> b->f = *val;<br>}<br></pre>
1368 <H3><a name="Ruby_nn18"></a>32.3.7 C++ classes</H3>
1371 <p> Like structs, C++ classes are wrapped by creating a new Ruby
1372 class of the same name with accessor methods for the public class
1373 member data. Additionally, public member functions for the class are
1374 wrapped as Ruby instance methods, and public static member functions
1375 are wrapped as Ruby singleton methods. So, given the C++ class
1383 <pre>class List {<br>public:<br> List();<br> ~List();<br> int search(char *item);<br> void insert(char *item);<br> void remove(char *item);<br> char *get(int n);<br> int length;<br> static void print(List *l);<br>};<br></pre>
1395 <p> SWIG would create a <tt>List</tt> class with: </p>
1407 <li> instance methods <i>search</i>, <i>insert</i>,
1408 <i>remove</i>, and <i>get</i>; </li>
1414 <li> instance methods <i>length</i> and <i>length=</i>
1415 (to get and set the value of the <i>length</i> data
1422 <li> a <i>print</i> singleton method for the
1435 <p> In Ruby, these functions are used as follows: </p>
1441 <div class="code targetlang">
1442 <pre>require 'Example'<br><br>l = Example::List.new<br><br>l.insert("Ale")<br>l.insert("Stout")<br>l.insert("Lager")<br>Example.print(l)<br>l.length()<br>----- produces the following output <br>Lager<br>Stout<br>Ale<br>3<br></pre>
1454 <H3><a name="Ruby_nn19"></a>32.3.8 C++ Inheritance</H3>
1457 <p> The SWIG type-checker is fully aware of C++ inheritance.
1458 Therefore, if you have classes like this: </p>
1465 <pre>class Parent {<br> ...<br>};<br><br>class Child : public Parent {<br> ...<br>};<br></pre>
1477 <p> those classes are wrapped into a hierarchy of Ruby classes
1478 that reflect the same inheritance structure. All of the usual Ruby
1479 utility methods work normally: </p>
1486 <pre>irb(main):001:0> <b>c = Child.new</b><br>#<Bar:0x4016efd4><br>irb(main):002:0> <b>c.instance_of? Child</b><br>true<br>irb(main):003:0> <b>b.instance_of? Parent</b><br>false<br>irb(main):004:0> <b>b.is_a? Child</b><br>true<br>irb(main):005:0> <b>b.is_a? Parent</b><br>true<br>irb(main):006:0> <b>Child < Parent</b><br>true<br>irb(main):007:0> <b>Child > Parent</b><br>false<br></pre>
1498 <p> Furthermore, if you have a function like this: </p>
1505 <pre>void spam(Parent *f);<br></pre>
1517 <p> then the function <tt>spam()</tt> accepts <tt>Parent</tt>*
1518 or a pointer to any class derived from <tt>Parent</tt>. </p>
1524 <p>Until recently, the Ruby module for SWIG didn't support
1525 multiple inheritance, and this is still the default behavior. This
1526 doesn't mean that you can't wrap C++ classes which inherit from
1527 multiple base classes; it simply means that only the <b>first</b>
1528 base class listed in the class declaration is considered, and any
1529 additional base classes are ignored. As an example, consider a SWIG
1530 interface file with a declaration like this: </p>
1537 <pre>class Derived : public Base1, public Base2<br>{<br> ...<br>};<br></pre>
1549 <p> For this case, the resulting Ruby class (<tt>Derived</tt>)
1550 will only consider <tt>Base1</tt> as its superclass. It
1551 won't inherit any of <tt>Base2</tt>'s member functions or
1552 data and it won't recognize <tt>Base2</tt> as an
1553 "ancestor" of <tt>Derived</tt> (i.e. the <em>is_a?</em>
1554 relationship would fail). When SWIG processes this interface file,
1555 you'll see a warning message like: </p>
1561 <div class="code shell">
1562 <pre>example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.<br>Multiple inheritance is not supported in Ruby.<br></pre>
1574 <p> Starting with SWIG 1.3.20, the Ruby module for SWIG provides
1575 limited support for multiple inheritance. Because the approach for
1576 dealing with multiple inheritance introduces some limitations, this is
1577 an optional feature that you can activate with the <tt>-minherit</tt>
1578 command-line option: </p>
1584 <div class="code shell">
1585 <pre>$ <b>swig -c++ -ruby -minherit example.i</b></pre>
1597 <p> Using our previous example, if your SWIG interface file
1598 contains a declaration like this: </p>
1605 <pre>class Derived : public Base1, public Base2<br>{<br> ...<br>};<br></pre>
1617 <p> and you run SWIG with the <tt>-minherit</tt>
1618 command-line option, then you will end up with a Ruby class <tt>Derived</tt>
1619 that appears to "inherit" the member data and functions from both <tt>Base1</tt>
1620 and <tt>Base2</tt>. What actually happens is that three
1621 different top-level classes are created, with Ruby's <tt>Object</tt>
1622 class as their superclass. Each of these classes defines a nested
1623 module named <tt>Impl</tt>, and it's in these nested <tt>Impl</tt>
1624 modules that the actual instance methods for the classes are defined,
1631 <div class="code targetlang">
1632 <pre>class Base1<br> module Impl<br> # Define Base1 methods here<br> end<br> include Impl<br>end<br><br>class Base2<br> module Impl<br> # Define Base2 methods here<br> end<br> include Impl<br>end<br><br>class Derived<br> module Impl<br> include Base1::Impl<br> include Base2::Impl<br> # Define Derived methods here<br> end<br> include Impl<br>end<br></pre>
1644 <p> Observe that after the nested <tt>Impl</tt>
1645 module for a class is defined, it is mixed-in to the class itself. Also
1646 observe that the <tt>Derived::Impl</tt> module first
1647 mixes-in its base classes' <tt>Impl</tt> modules, thus
1648 "inheriting" all of their behavior. </p>
1654 <p>The primary drawback is that, unlike the default mode of
1655 operation, neither <tt>Base1</tt> nor <tt>Base2</tt>
1656 is a true superclass of <tt>Derived</tt> anymore: </p>
1662 <div class="code targetlang">
1663 <pre>obj = Derived.new<br>obj.is_a? Base1 # this will return false...<br>obj.is_a? Base2 # ... and so will this<br></pre>
1675 <p> In most cases, this is not a serious problem since objects of
1676 type <tt>Derived</tt> will otherwise behave as though they
1677 inherit from both <tt>Base1</tt> and <tt>Base2</tt>
1678 (i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
1685 <H3><a name="Ruby_nn20"></a>32.3.9 C++ Overloaded Functions</H3>
1688 <p> C++ overloaded functions, methods, and constructors are
1689 mostly supported by SWIG. For example, if you have two functions like
1697 <pre>void foo(int);<br>void foo(char *c);<br></pre>
1709 <p> You can use them in Ruby in a straightforward manner: </p>
1715 <div class="code targetlang">
1716 <pre>irb(main):001:0> <b>foo(3)</b> # foo(int)<br>irb(main):002:0> <b>foo("Hello")</b> # foo(char *c)<br></pre>
1728 <p>Similarly, if you have a class like this,</p>
1735 <pre>class Foo {<br>public:<br> Foo();<br> Foo(const Foo &);<br> ...<br>};<br></pre>
1747 <p>you can write Ruby code like this:</p>
1753 <div class="code targetlang">
1754 <pre>irb(main):001:0> <b>f = Foo.new</b> # Create a Foo<br>irb(main):002:0> <b>g = Foo.new(f)</b> # Copy f<br></pre>
1766 <p> Overloading support is not quite as flexible as in C++.
1767 Sometimes there are methods that SWIG can't disambiguate. For example: </p>
1774 <pre>void spam(int);<br>void spam(short);<br></pre>
1793 <pre>void foo(Bar *b);<br>void foo(Bar &b);<br></pre>
1805 <p> If declarations such as these appear, you will get a warning
1806 message like this: </p>
1812 <div class="code shell">
1813 <pre>example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)<br>at example.i:11.<br> </pre>
1825 <p> To fix this, you either need to ignore or rename one of the
1826 methods. For example: </p>
1833 <pre>%rename(spam_short) spam(short);<br>...<br>void spam(int); <br>void spam(short); // Accessed as spam_short<br></pre>
1852 <pre>%ignore spam(short);<br>...<br>void spam(int); <br>void spam(short); // Ignored<br></pre>
1864 <p> SWIG resolves overloaded functions and methods using a
1865 disambiguation scheme that ranks and sorts declarations according to a
1866 set of type-precedence rules. The order in which declarations appear in
1867 the input does not matter except in situations where ambiguity
1868 arises--in this case, the first declaration takes precedence. </p>
1874 <p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG
1875 and C++"</a> chapter for more information about overloading. </p>
1881 <H3><a name="Ruby_nn21"></a>32.3.10 C++ Operators</H3>
1884 <p> For the most part, overloaded operators are handled
1885 automatically by SWIG and do not require any special treatment on your
1886 part. So if your class declares an overloaded addition operator, e.g. </p>
1893 <pre>class Complex {<br> ...<br> Complex operator+(Complex &);<br> ...<br>};<br></pre>
1905 <p> the resulting Ruby class will also support the addition (+)
1906 method correctly. </p>
1912 <p>For cases where SWIG's built-in support is not sufficient, C++
1913 operators can be wrapped using the <tt>%rename</tt>
1914 directive (available on SWIG 1.3.10 and later releases). All you need
1915 to do is give the operator the name of a valid Ruby identifier. For
1923 <pre>%rename(add_complex) operator+(Complex &, Complex &);<br>...<br>Complex operator+(Complex &, Complex &);<br></pre>
1935 <p>Now, in Ruby, you can do this:</p>
1941 <div class="code targetlang">
1942 <pre>a = Example::Complex.new(2, 3)<br>b = Example::Complex.new(4, -1)<br>c = Example.add_complex(a, b)<br></pre>
1954 <p> More details about wrapping C++ operators into Ruby operators
1955 is discussed in the <a href="#ruby_operator_overloading">section
1956 on operator overloading</a>. </p>
1962 <H3><a name="Ruby_nn22"></a>32.3.11 C++ namespaces</H3>
1965 <p> SWIG is aware of C++ namespaces, but namespace names do not
1966 appear in the module nor do namespaces result in a module that is
1967 broken up into submodules or packages. For example, if you have a file
1975 <pre>%module example<br><br>namespace foo {<br> int fact(int n);<br> struct Vector {<br> double x,y,z;<br> };<br>};<br></pre>
1987 <p>it works in Ruby as follows:</p>
1993 <div class="code targetlang">
1994 <pre>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>Example.fact(3)</b><br>6<br>irb(main):003:0> <b>v = Example::Vector.new</b><br>#<Example::Vector:0x4016f4d4><br>irb(main):004:0> <b>v.x = 3.4</b><br>3.4<br>irb(main):004:0> <b>v.y</b><br>0.0<br></pre>
2006 <p> If your program has more than one namespace, name conflicts
2007 (if any) can be resolved using <tt>%rename</tt> For
2015 <pre>%rename(Bar_spam) Bar::spam;<br><br>namespace Foo {<br> int spam();<br>}<br><br>namespace Bar {<br> int spam();<br>}<br></pre>
2027 <p> If you have more than one namespace and your want to keep
2028 their symbols separate, consider wrapping them as separate SWIG
2029 modules. For example, make the module name the same as the namespace
2030 and create extension modules for each namespace separately. If your
2031 program utilizes thousands of small deeply nested namespaces each with
2032 identical symbol names, well, then you get what you deserve. </p>
2038 <H3><a name="Ruby_nn23"></a>32.3.12 C++ templates</H3>
2041 <p> C++ templates don't present a huge problem for SWIG. However,
2042 in order to create wrappers, you have to tell SWIG to create wrappers
2043 for a particular template instantiation. To do this, you use the <tt>%template</tt>
2044 directive. For example: </p>
2051 <pre>%module example<br><br>%{<br>#include "pair.h"<br>%}<br><br>template<class T1, class T2><br>struct pair {<br> typedef T1 first_type;<br> typedef T2 second_type;<br> T1 first;<br> T2 second;<br> pair();<br> pair(const T1&, const T2&);<br> ~pair();<br>};<br><br>%template(Pairii) pair<int,int>;<br></pre>
2069 <div class="code targetlang">
2070 <pre>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>p = Example::Pairii.new(3, 4)</b><br>#<Example:Pairii:0x4016f4df><br>irb(main):003:0> <b>p.first</b><br>3<br>irb(main):004:0> <b>p.second</b><br>4<br></pre>
2082 <H3><a name="Ruby_nn23_1"></a>32.3.13 C++ Standard Template Library (STL)</H3>
2085 <p> On a related note, the standard SWIG library contains a
2086 number of modules that provide typemaps for standard C++ library
2087 classes (such as <tt>std::pair</tt>, <tt>std::string</tt>
2088 and <tt>std::vector</tt>). These library modules don't
2089 provide wrappers around the templates themselves, but they do make it
2090 convenient for users of your extension module to pass Ruby objects
2091 (such as arrays and strings) to wrapped C++ code that expects instances
2092 of standard C++ templates. For example, suppose the C++ library you're
2093 wrapping has a function that expects a vector of floats: </p>
2100 <pre>%module example<br><br>float sum(const std::vector<float>& values);<br></pre>
2112 <p> Rather than go through the hassle of writing an "in" typemap
2113 to convert an array of Ruby numbers into a
2114 std::vector<float>, you can just use the <tt>std_vector.i</tt>
2115 module from the standard SWIG library: </p>
2122 <pre>%module example<br><br><b>%include std_vector.i</b><br>float sum(const std::vector<float>& values);<br></pre>
2134 <p>Ruby's STL wrappings provide additional methods to make them
2135 behave more similarly to Ruby's native classes.</p>
2141 <p>Thus, you can do, for example:</p>
2147 <div class="targetlang">
2148 <pre>v = IntVector.new<span class="targetlang"><br>v << 2</span><span class="targetlang"><br>v << 3<br>v << 4<br>v.each { |x| puts x }<br><span style="font-weight: bold;"><br>=> 2</span><br style="font-weight: bold;"><span style="font-weight: bold;">3</span><br style="font-weight: bold;"><span style="font-weight: bold;">4<br></span>v.delete_if { |x| x == 3 }<br><span style="font-weight: bold;">=> [2,4]</span></span></pre>
2160 <p>The SWIG Ruby module provides also the ability for all the STL
2161 containers to carry around Ruby native objects (Fixnum, Classes, etc)
2162 making them act almost like Ruby's own Array, Hash, etc. To
2164 that, you need to define a container that contains a swig::GC_VALUE,
2171 <div style="font-family: monospace;" class="code">%module
2190 std::vector< swig::GC_VALUE > NativeVector;<br>
2208 %template(NativeVector) std::vector< swig::GC_VALUE >;<br>
2226 <p>This vector can then contain any Ruby object, making them
2227 almost identical to Ruby's own Array class.</p>
2233 <div class="targetlang"><span style="font-family: monospace;">require 'nativevector'</span><br style="font-family: monospace;">
2239 <span style="font-family: monospace;">include NativeVector</span><br style="font-family: monospace;">
2245 <br style="font-family: monospace;">
2251 <span style="font-family: monospace;">v = NativeVector.new</span><br style="font-family: monospace;">
2257 <span style="font-family: monospace;">v << 1</span><br style="font-family: monospace;">
2263 <span style="font-family: monospace;">v <<
2264 [1,2]</span><br style="font-family: monospace;">
2270 <span style="font-family: monospace;">v <<
2271 'hello'</span><br style="font-family: monospace;">
2277 <br style="font-family: monospace;">
2283 <span style="font-family: monospace;">class A; end</span><br style="font-family: monospace;">
2289 <br style="font-family: monospace;">
2295 <span style="font-family: monospace;">v <<
2296 A.new</span><br style="font-family: monospace;">
2302 <br style="font-family: monospace;">
2308 <span style="font-family: monospace;">puts v</span><br style="font-family: monospace;">
2314 <span style="font-weight: bold; font-family: monospace;">=>
2315 [1, [1,2], 'hello', #<A:0x245325>]</span></div>
2327 <p>Obviously, there is a lot more to template wrapping than
2328 shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>
2335 <H3><a name="C_STL_Functors"></a>32.3.14 C++ STL Functors</H3>
2338 <p>Some containers in the STL allow you to modify their default
2339 behavior by using so called functors or function objects.
2340 Functors are often just a very simple struct with<span style="font-family: monospace;"> operator()</span>
2341 redefined or an actual C/C++ function. This allows you, for
2342 example, to always keep the sort order of a STL container to your
2349 <p>The Ruby STL mappings allows you to modify those containers
2351 support functors using Ruby procs or methods, instead.
2353 this includes <span style="font-family: monospace;">std::set</span>,
2354 <span style="font-family: monospace;">set::map</span>,
2355 <span style="font-family: monospace;">std::multiset</span>
2356 and <span style="font-family: monospace;">std::multimap</span>.</p>
2362 <p>The functors in swig are called<span style="font-family: monospace;"> swig::UnaryFunction</span>
2363 and <span style="font-family: monospace;">swig::BinaryFunction</span>.<br>
2369 For C++ predicates (ie. functors that must return bool as a result) <span style="font-family: monospace;">swig::UnaryPredicate</span>
2370 and <span style="font-family: monospace;">swig::BinaryPredicate</span>
2377 <p>As an example, if given this swig file:</p>
2383 <div style="font-family: monospace;" class="code">%module
2396 %include <std_set.i><br>
2408 %typemap(IntSet) std::set< int, swig::BinaryPredicate
2415 <p>You can then use the set from Ruby with or without a proc
2416 object as a predicate:</p>
2422 <div style="font-family: monospace;" class="targetlang">require
2441 # Default sorting behavior defined in C++<br>
2477 <span style="font-weight: bold;">=>
2478 [1,2,3]</span><br>
2490 # Custom sorting behavior defined by a Ruby proc
2491 <div><span class="targetlang">b = IntSet.new( proc {
2492 |a,b| a > b } )</span><br>
2498 b << 1<br>
2504 b << 2<br>
2510 b << 3<br>
2516 b<br style="font-weight: bold;">
2522 <span style="font-weight: bold;">=>
2523 [3,2,1]</span> </div>
2535 <H3><a name="Ruby_C_Iterators"></a>32.3.15 C++ STL Iterators</H3>
2538 <p>The STL is well known for the use of iterators. There
2539 are a number of iterators possible with different properties, but in
2540 general there are two main categories: const iterators and non-const
2541 iterators. The const iterators can access and not modify the
2542 values they point at, while the non-const iterators can both read and
2543 modify the values.</p>
2549 <p>The Ruby STL wrappings support both type of iterators by using
2550 a proxy class in-between. This proxy class is <span style="font-family: monospace;">swig::Iterator or
2551 swig::ConstIterator. </span>Derived from them are template
2552 classes that need to be initialized with the actual iterator for the
2553 container you are wrapping and often times with the beginning and
2554 ending points of the iteration range. </p>
2560 <p>The SWIG STL library already provides typemaps to all the
2561 standard containers to do this wrapping automatically for you, but if
2562 you have your own STL-like iterator, you will need to write your own
2563 typemap for them. For out typemaps, the special functions <span style="font-family: monospace;">make_const_iterator</span> and <span style="font-family: monospace;">make_nonconst_iterator</span> are provided.</p>
2565 <p>These can be used either like:</p>
2567 <div style="font-family: monospace;" class="code">make_const_iterator( iterator, rubyclass );<br>
2569 make_const_iterator( iterator, iterator_begin, iterator_end, rubyclass );</div>
2575 <p>The iterators support a <span style="font-family: monospace;">next()</span> and <span style="font-family: monospace;">previous() </span>member function to
2576 just change the iterator without returning anything. <span style="font-family: monospace;">previous()</span>
2577 should obviously only be used for bidirectional iterators. You
2578 can also advance the iterator multiple steps by using standard math
2579 operations like <span style="font-family: monospace;">+=</span>.</p>
2582 value the iterator points at can be accessed with <span style="font-family: monospace;">value()</span> -- this is equivalent to dereferencing it with <span style="font-family: monospace;">*i</span>.
2583 For non-const iterators, a <span style="font-family: monospace;">value=()</span> function
2584 is also provided which allows you to change the value pointed by the
2585 iterator. This is equivalent to the C++ construct of dereferencing and assignment, like <span style="font-family: monospace;">*i = something</span>. </p>
2591 <p>Thus, given say a vector class of doubles defined as:</p>
2597 <div style="font-family: monospace;" class="code"><span class="code">%module doublevector</span><br class="code">
2603 <span class="code"><br>
2609 %include std_vector.i</span><br class="code">
2615 <span class="code"><br>
2621 %template(DoubleVector) std::vector<double>;</span></div>
2627 <p>Its iterator can then be used from Ruby like:</p>
2633 <div style="font-family: monospace;" class="targetlang">require
2640 include Doublevector<br>
2648 v = DoubleVector.new<br>
2672 # an elaborate and less efficient way of doing v.map! { |x| x+2 }<br>
2698 val = i.value<br>
2710 i.value = val<br>
2732 <span style="font-weight: bold;">>> [3, 4, 5 ]</span></div>
2740 <p>If you'd rather have STL classes without any iterators, you should define<span style="font-family: monospace;"> -DSWIG_NO_EXPORT_ITERATOR_METHODS </span>when running swig.</p>
2746 <H3><a name="Ruby_nn24"></a>32.3.16 C++ Smart Pointers</H3>
2749 <p> In certain C++ programs, it is common to use classes that
2750 have been wrapped by so-called "smart pointers." Generally, this
2751 involves the use of a template class that implements <tt>operator->()</tt>
2759 <pre>template<class T> class SmartPtr {<br> ...<br> T *operator->();<br> ...<br>}<br></pre>
2771 <p>Then, if you have a class like this,</p>
2778 <pre>class Foo {<br>public:<br> int x;<br> int bar();<br>};<br></pre>
2790 <p>A smart pointer would be used in C++ as follows:</p>
2797 <pre>SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown)<br>...<br>p->x = 3; // Foo::x<br>int y = p->bar(); // Foo::bar<br></pre>
2809 <p> To wrap this in Ruby, simply tell SWIG about the <tt>SmartPtr</tt>
2810 class and the low-level <tt>Foo</tt> object. Make sure you
2811 instantiate <tt>SmartPtr</tt> using <tt>%template</tt>
2812 if necessary. For example: </p>
2819 <pre>%module example<br>...<br>%template(SmartPtrFoo) SmartPtr<Foo>;<br>...<br></pre>
2831 <p>Now, in Ruby, everything should just "work":</p>
2837 <div class="code targetlang">
2838 <pre>irb(main):001:0> <b>p = Example::CreateFoo()</b> # Create a smart-pointer somehow<br>#<Example::SmartPtrFoo:0x4016f4df><br>irb(main):002:0> <b>p.x = 3</b> # Foo::x<br>3<br>irb(main):003:0> <b>p.bar()</b> # Foo::bar<br></pre>
2850 <p> If you ever need to access the underlying pointer returned by
2851 <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt>
2852 method. For example: </p>
2858 <div class="code targetlang">
2859 <pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre>
2871 <H3><a name="Ruby_nn25"></a>32.3.17 Cross-Language Polymorphism</H3>
2874 <p> SWIG's Ruby module supports cross-language polymorphism
2875 (a.k.a. the "directors" feature) similar to that for SWIG's Python
2876 module. Rather than duplicate the information presented in the <a href="Ruby">Python</a> chapter, this
2877 section just notes the differences that you need to be aware of when
2878 using this feature with Ruby. </p>
2884 <H4><a name="Ruby_nn26"></a>32.3.17.1 Exception Unrolling</H4>
2887 <p> Whenever a C++ director class routes one of its virtual
2888 member function calls to a Ruby instance method, there's always the
2889 possibility that an exception will be raised in the Ruby code. By
2890 default, those exceptions are ignored, which simply means that the
2891 exception will be exposed to the Ruby interpreter. If you would like to
2892 change this behavior, you can use the <tt>%feature("director:except")</tt>
2893 directive to indicate what action should be taken when a Ruby exception
2894 is raised. The following code should suffice in most cases: </p>
2901 <pre>%feature("director:except") {<br> throw Swig::DirectorMethodException($error);<br>}<br></pre>
2913 <p> When this feature is activated, the call to the Ruby instance
2914 method is "wrapped" using the <tt>rb_rescue2()</tt>
2915 function from Ruby's C API. If any Ruby exception is raised, it will be
2916 caught here and a C++ exception is raised in its place. </p>
2922 <H2><a name="Ruby_nn27"></a>32.4 Naming</H2>
2925 <p>Ruby has several common naming conventions. Constants are
2927 in upper case, module and class names are in camel case and methods are
2928 in lower case with underscores. For example: </p>
2941 <li><strong>MATH::PI</strong> is a constant name</li>
2947 <li><strong>MyClass</strong> is a class name</li>
2953 <li><strong>my_method</strong> is a method name</li>
2971 <p>Prior to version 1.3.28, SWIG did not support these Ruby
2972 conventions. The only modifications it made to names was to capitalize
2973 the first letter of constants (which includes module and class names).</p>
2979 <p>SWIG 1.3.28 introduces the new -autorename command line
2981 When this parameter is specified, SWIG will automatically change
2982 constant, class and method names to conform with the standard Ruby
2983 naming conventions. For example: </p>
2989 <div class="code shell">
2990 <pre>$ <b>swig -ruby -autorename example.i</b>
3003 <p>To disable renaming use the -noautorename command line option.</p>
3009 <p>Since this change significantly changes the wrapper code
3011 by SWIG, it is turned off by default in SWIG 1.3.28. However, it is
3012 planned to become the default option in future releases.</p>
3018 <H3><a name="Ruby_nn28"></a>32.4.1 Defining Aliases</H3>
3021 <p> It's a fairly common practice in the Ruby built-ins and
3022 standard library to provide aliases for method names. For example, <em>Array#size</em>
3023 is an alias for <em>Array#length</em>. If you would like
3024 to provide an alias for one of your class' instance methods, one
3025 approach is to use SWIG's <tt>%extend</tt> directive to
3026 add a new method of the aliased name that calls the original function.
3034 <pre>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br><br>%extend MyArray {<br> // MyArray#size is an alias for MyArray#length<br> size_t size() const {<br> return $self->length();<br> }<br>}<br> </pre>
3046 <p> A better solution is to use the <tt>%alias</tt>
3047 directive (unique to SWIG's Ruby module). The previous example could
3048 then be rewritten as: </p>
3055 <pre>// MyArray#size is an alias for MyArray#length<br>%alias MyArray::length "size";<br><br>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br><br></pre>
3067 <p> Multiple aliases can be associated with a method by providing
3068 a comma-separated list of aliases to the <tt>%alias</tt>
3069 directive, e.g. </p>
3076 <pre>%alias MyArray::length "amount,quantity,size";</pre>
3088 <p> From an end-user's standpoint, there's no functional
3089 difference between these two approaches; i.e. they should get the same
3090 result from calling either <em>MyArray#size</em> or <em>MyArray#length</em>.
3091 However, when the <tt>%alias</tt> directive is used, SWIG
3092 doesn't need to generate all of the wrapper code that's usually
3093 associated with added methods like our <em>MyArray::size()</em>
3100 <p>Note that the <tt>%alias</tt> directive is
3101 implemented using SWIG's "features" mechanism and so the same name
3102 matching rules used for other kinds of features apply (see the chapter
3103 on <a href="Customization.html#Customization">"Customization
3104 Features"</a>) for more details).</p>
3110 <H3><a name="Ruby_nn29"></a>32.4.2 Predicate Methods</H3>
3113 <p> Ruby methods that return a boolean value and end in a
3115 are known as predicate methods. Examples of predicate methods in
3116 standard Ruby classes include <em>Array#empty?</em> (which
3117 returns <tt>true</tt> for an array containing no elements)
3118 and <em>Object#instance_of?</em> (which returns <tt>true</tt>
3119 if the object is an instance of the specified class). For consistency
3120 with Ruby conventions, methods that return boolean values should be
3121 marked as predicate methods.</p>
3127 <p>One cumbersome solution to this problem is to rename the
3128 method (using SWIG's <tt>%rename</tt> directive) and
3129 provide a custom typemap that converts the function's actual return
3130 type to Ruby's <tt>true</tt> or <tt>false</tt>.
3138 <pre>%rename("is_it_safe?") is_it_safe();<br><br>%typemap(out) int is_it_safe <br> "$result = ($1 != 0) ? Qtrue : Qfalse;";<br><br>int is_it_safe();<br><br></pre>
3150 <p> A better solution is to use the <tt>%predicate</tt>
3151 directive (unique to SWIG's Ruby module) to designate a method as a
3152 predicate method. For the previous example, this would look like: </p>
3159 <pre>%predicate is_it_safe();<br><br>int is_it_safe();<br><br></pre>
3171 <p>This method would be invoked from Ruby code like this:</p>
3177 <div class="code targetlang">
3178 <pre>irb(main):001:0> <b>Example::is_it_safe?</b><br>true<br><br></pre>
3190 <p> The <tt>%predicate</tt> directive is implemented
3191 using SWIG's "features" mechanism and so the same name matching rules
3192 used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
3193 Features"</a>) for more details). </p>
3199 <H3><a name="Ruby_nn30"></a>32.4.3 Bang Methods</H3>
3202 <p> Ruby methods that modify an object in-place and end in an
3203 exclamation mark are known as bang methods. An example of a bang method
3204 is <em>Array#sort!</em> which changes the ordering of
3205 items in an array. Contrast this with <em>Array#sort</em>,
3206 which returns a copy of the array with the items sorted instead of
3207 modifying the original array. For consistency with Ruby conventions,
3208 methods that modify objects in place should be marked as bang methods.</p>
3214 <p>Bang methods can be marked using the <tt>%bang</tt>
3215 directive which is unique to the Ruby module and was introduced in SWIG
3216 1.3.28. For example:</p>
3223 <pre>%bang sort!(arr);<br><br>int sort(int arr[]); </pre>
3235 <p>This method would be invoked from Ruby code like this:</p>
3242 <pre>irb(main):001:0> <b>Example::sort!(arr)</b></pre>
3254 <p> The <tt>%bang</tt> directive is implemented
3255 using SWIG's "features" mechanism and so the same name matching rules
3256 used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
3257 Features"</a>) for more details). </p>
3263 <H3><a name="Ruby_nn31"></a>32.4.4 Getters and Setters</H3>
3266 <p> Often times a C++ library will expose properties through
3267 getter and setter methods. For example:</p>
3274 <pre>class Foo {<br> Foo() {}<br><br> int getValue() { return value_; }<br><br> void setValue(int value) { value_ = value; }<br><br>private:<br> int value_;<br>};</pre>
3286 <p>By default, SWIG will expose these methods to Ruby as <tt>get_value</tt>
3287 and <tt>set_value.</tt> However, it more natural for these
3288 methods to be exposed in Ruby as <tt>value</tt> and <tt>value=.
3289 </tt> That allows the methods to be used like this:</p>
3296 <pre>irb(main):001:0> <b>foo = Foo.new()</b><br>irb(main):002:0> <b>foo.value = 5</b><br>irb(main):003:0> <b>puts foo.value</b></pre>
3308 <p> This can be done by using the %rename directive:</p>
3315 <pre>%rename("value") Foo::getValue();<br>%rename("value=") Foo::setValue(int value);<br></pre>
3333 <H2><a name="Ruby_nn32"></a>32.5 Input and output parameters</H2>
3336 <p> A common problem in some C programs is handling parameters
3337 passed as simple pointers. For example: </p>
3344 <pre>void add(int x, int y, int *result) {<br> *result = x + y;<br>}<br>or<br>int sub(int *x, int *y) {<br> return *x-*y;<br>}<br></pre>
3356 <p> The easiest way to handle these situations is to use the <tt>typemaps.i</tt>
3357 file. For example: </p>
3364 <pre>%module Example<br>%include "typemaps.i"<br><br>void add(int, int, int *OUTPUT);<br>int sub(int *INPUT, int *INPUT);<br></pre>
3376 <p>In Ruby, this allows you to pass simple values. For example:</p>
3382 <div class="code targetlang">
3383 <pre>a = Example.add(3,4)<br>puts a<br>7<br>b = Example.sub(7,4)<br>puts b<br>3<br></pre>
3395 <p> Notice how the <tt>INPUT</tt> parameters allow
3396 integer values to be passed instead of pointers and how the <tt>OUTPUT</tt>
3397 parameter creates a return result. </p>
3403 <p>If you don't want to use the names <tt>INPUT</tt>
3404 or <tt>OUTPUT</tt>, use the <tt>%apply</tt>
3405 directive. For example: </p>
3412 <pre>%module Example<br>%include "typemaps.i"<br><br>%apply int *OUTPUT { int *result };<br>%apply int *INPUT { int *x, int *y};<br><br>void add(int x, int y, int *result);<br>int sub(int *x, int *y);<br></pre>
3424 <p> If a function mutates one of its parameters like this, </p>
3431 <pre>void negate(int *x) {<br> *x = -(*x);<br>}<br></pre>
3443 <p>you can use <tt>INOUT</tt> like this:</p>
3450 <pre>%include "typemaps.i"<br>...<br>void negate(int *INOUT);<br></pre>
3462 <p>In Ruby, a mutated parameter shows up as a return value. For
3469 <div class="code targetlang">
3470 <pre>a = Example.negate(3)<br>print a<br>-3<br><br></pre>
3482 <p> The most common use of these special typemap rules is to
3483 handle functions that return more than one value. For example,
3484 sometimes a function returns a result as well as a special error code: </p>
3491 <pre>/* send message, return number of bytes sent, success code, and error_code */<br>int send_message(char *text, int *success, int *error_code);<br></pre>
3503 <p> To wrap such a function, simply use the <tt>OUTPUT</tt>
3504 rule above. For example: </p>
3511 <pre>%module example<br>%include "typemaps.i"<br>...<br>int send_message(char *, int *OUTPUT, int *OUTPUT);<br></pre>
3523 <p> When used in Ruby, the function will return an array of
3524 multiple values. </p>
3530 <div class="code targetlang">
3531 <pre>bytes, success, error_code = send_message("Hello World")<br>if not success<br> print "error #{error_code} : in send_message"<br>else<br> print "Sent", bytes<br>end<br></pre>
3543 <p> Another way to access multiple return values is to use the <tt>%apply</tt>
3544 rule. In the following example, the parameters rows and columns are
3545 related to SWIG as <tt>OUTPUT</tt> values through the use
3546 of <tt>%apply</tt> </p>
3553 <pre>%module Example<br>%include "typemaps.i"<br>%apply int *OUTPUT { int *rows, int *columns };<br>...<br>void get_dimensions(Matrix *m, int *rows, int*columns);<br></pre>
3571 <div class="code targetlang">
3572 <pre>r, c = Example.get_dimensions(m)<br></pre>
3584 <H2><a name="Ruby_nn33"></a>32.6 Exception handling </H2>
3587 <H3><a name="Ruby_nn34"></a>32.6.1 Using the %exception directive </H3>
3590 <p>The SWIG <tt>%exception</tt> directive can be
3591 used to define a user-definable exception handler that can convert
3592 C/C++ errors into Ruby exceptions. The chapter on <a href="Customization.html#Customization">Customization
3593 Features</a> contains more details, but suppose you have a C++
3594 class like the following : </p>
3601 <pre>class DoubleArray {<br> private:<br> int n;<br> double *ptr;<br> public:<br> // Create a new array of fixed size<br> DoubleArray(int size) {<br> ptr = new double[size];<br> n = size;<br> }<br><br> // Destroy an array<br> ~DoubleArray() {<br> delete ptr;<br> } <br><br> // Return the length of the array<br> int length() {<br> return n;<br> }<br><br> // Get an array item and perform bounds checking.<br> double getitem(int i) {<br> if ((i >= 0) && (i < n))<br> return ptr[i];<br> else<br> throw RangeError();<br> }<br><br> // Set an array item and perform bounds checking.<br> void setitem(int i, double val) {<br> if ((i >= 0) && (i < n))<br> ptr[i] = val;<br> else {<br> throw RangeError();<br> }<br> }<br> };<br></pre>
3613 <p> Since several methods in this class can throw an exception
3614 for an out-of-bounds access, you might want to catch this in the Ruby
3615 extension by writing the following in an interface file: </p>
3622 <pre>%exception {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error.");<br> }<br>}<br><br>class DoubleArray {<br> ...<br>};<br></pre>
3634 <p> The exception handling code is inserted directly into
3635 generated wrapper functions. When an exception handler is defined,
3636 errors can be caught and used to gracefully raise a Ruby exception
3637 instead of forcing the entire program to terminate with an uncaught
3644 <p>As shown, the exception handling code will be added to every
3645 wrapper function. Because this is somewhat inefficient, you might
3646 consider refining the exception handler to only apply to specific
3647 methods like this: </p>
3654 <pre>%exception getitem {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error in getitem.");<br> }<br>}<br><br>%exception setitem {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error in setitem.");<br> }<br>}<br></pre>
3666 <p> In this case, the exception handler is only attached to
3667 methods and functions named <tt>getitem</tt> and <tt>setitem</tt>.
3674 <p>Since SWIG's exception handling is user-definable, you are not
3675 limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization
3676 Features</a> for more examples.</p>
3682 <H3><a name="Ruby_nn34_2"></a>32.6.2 Handling Ruby Blocks </H3>
3685 <p>One of the highlights of Ruby and most of its standard library
3687 the use of blocks, which allow the easy creation of continuations and
3688 other niceties. Blocks in ruby are also often used to
3689 simplify the passing of many arguments to a class.</p>
3695 <p>In order to make your class constructor support blocks, you
3696 can take advantage of the %exception directive, which will get run
3697 after the C++ class' constructor was called. </p>
3703 <p>For example, this yields the class over after its
3718 <pre>class Window<br>{<br>public:<br> Window(int x, int y, int w, int h);<br>// .... other methods here ....<br>};<br><br>// Add support for yielding self in the Class' constructor.<br>%exception Window::Window {<br> $action<br> if (rb_block_given_p()) {<br> rb_yield(self);<br> }<br>}</pre>
3730 <p> Then, in ruby, it can be used like:</p>
3736 <div style="font-family: monospace;" class="targetlang">Window.new(0,0,360,480)
3743 w.color = Fltk::RED<br>
3749 w.border = false<br>
3755 <span class="targetlang">}</span></div>
3767 <p>For other methods, you can usually use a dummy parameter with
3768 a special in typemap, like:</p>
3774 <div class="code" style="font-family: monospace;">//<br>
3780 // original function was:<br>
3792 // void func(int x);<br>
3804 %typemap(in,numinputs=0) int RUBY_YIELD_SELF {<br>
3810 if ( !rb_block_given_p() )<br>
3816
3817 rb_raise("No block given");<br>
3823 return rb_yield(self);<br>
3847 void func(int x, int
3848 RUBY_YIELD_SELF );<br>
3860 <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
3863 <H3><a name="Ruby_nn35"></a>32.6.3 Raising exceptions </H3>
3866 <p>There are three ways to raise exceptions from C++ code to
3873 <p>The first way is to use <tt>SWIG_exception(int code,
3874 const char *msg)</tt>. The following table shows the mappings
3875 from SWIG error codes to Ruby exceptions:</p>
3881 <div class="diagram">
3882 <table class="diagram" summary="Mapping between SWIG error codes and Ruby exceptions." border="1" width="80%">
3900 <td class="diagram" style="font-family: monospace;">
3905 <div>SWIG_MemoryError</div>
3917 <td style="font-family: monospace;">
3922 <div>rb_eNoMemError</div>
3946 <td class="diagram" style="font-family: monospace;">
3951 <div>SWIG_IOError</div>
3963 <td style="font-family: monospace;">
3968 <div>rb_eIOError</div>
3992 <td class="diagram" style="font-family: monospace;">
3997 <div>SWIG_RuntimeError</div>
4009 <td style="font-family: monospace;">
4014 <div>rb_eRuntimeError</div>
4038 <td class="diagram" style="font-family: monospace;">
4043 <div>SWIG_IndexError</div>
4055 <td style="font-family: monospace;">
4060 <div>rb_eIndexError</div>
4084 <td class="diagram" style="font-family: monospace;">
4089 <div>SWIG_TypeError</div>
4101 <td style="font-family: monospace;">
4106 <div>rb_eTypeError</div>
4130 <td class="diagram" style="font-family: monospace;">
4135 <div>SWIG_DivisionByZero</div>
4147 <td style="font-family: monospace;">
4152 <div>rb_eZeroDivError</div>
4176 <td class="diagram" style="font-family: monospace;">
4181 <div>SWIG_OverflowError</div>
4193 <td style="font-family: monospace;">
4198 <div>rb_eRangeError</div>
4222 <td class="diagram" style="font-family: monospace;">
4227 <div>SWIG_SyntaxError</div>
4239 <td style="font-family: monospace;">
4244 <div>rb_eSyntaxError</div>
4268 <td class="diagram" style="font-family: monospace;">
4273 <div>SWIG_ValueError</div>
4285 <td style="font-family: monospace;">
4290 <div>rb_eArgError</div>
4314 <td class="diagram" style="font-family: monospace;">
4319 <div>SWIG_SystemError</div>
4331 <td style="font-family: monospace;">
4336 <div>rb_eFatal</div>
4360 <td class="diagram" style="font-family: monospace;">
4365 <div>SWIG_AttributeError</div>
4377 <td style="font-family: monospace;">
4382 <div>rb_eRuntimeError</div>
4406 <td class="diagram" style="font-family: monospace;">
4411 <div>SWIG_NullReferenceError</div>
4423 <td style="font-family: monospace;">
4428 <div>rb_eNullReferenceError*</div>
4452 <td class="diagram" style="font-family: monospace;">
4457 <div>SWIG_ObjectPreviouslyDeletedError</div>
4469 <td style="font-family: monospace;">
4474 <div>rb_eObjectPreviouslyDeleted*</div>
4498 <td class="diagram" style="font-family: monospace;">
4503 <div>SWIG_UnknownError</div>
4515 <td style="font-family: monospace;">
4520 <div>rb_eRuntimeError</div>
4538 <tr class="diagram" style="font-family: monospace;">
4549 <div>* These error classes are created by
4550 SWIG and are not built-in Ruby exception classes </div>
4585 <p>The second way to raise errors is to use <tt>SWIG_Raise(obj,
4587 Obj is a C++ instance of an exception class, type is a string
4588 specifying the type of exception (for example, "MyError") and desc is
4589 the SWIG description of the exception class. For example: </p>
4595 <div style="font-family: monospace;" class="code">
4596 %raise(SWIG_NewPointerObj(e,
4597 SWIGTYPE_p_AssertionFailedException,
4598 0), ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);</div>
4604 <p>This is useful when you want to pass the current exception
4606 directly to Ruby, particularly when the object is an instance of class
4607 marked as an <tt>%exceptionclass</tt> (see the next
4608 section for more information).</p>
4614 <p>Last, you can raise an exception by directly calling Ruby's C
4615 api. This is done by invoking the <tt>rb_raise()</tt>
4616 function. The first argument passed to <tt>rb_raise()</tt>
4617 is the exception type. You can raise a custom exception type or one of
4618 the built-in Ruby exception types.</p>
4624 <H3><a name="Ruby_nn36"></a>32.6.4 Exception classes </H3>
4627 <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
4628 directive, which is used to identify C++ classes that are used as
4629 exceptions. Classes that are marked with the <tt>%exceptionclass</tt>
4630 directive are exposed in Ruby as child classes of <tt>rb_eRuntimeError</tt>.
4631 This allows C++ exceptions to be directly mapped to Ruby exceptions,
4632 providing for a more natural integration between C++ code and Ruby code.</p>
4639 <pre> %exceptionclass CustomError;<br> <br> %inline %{<br> class CustomError { };<br> <br> class Foo { <br> public:<br> void test() { throw CustomError; }<br> };<br> }<br></pre>
4651 <p>From Ruby you can now call this method like this: </p>
4657 <div class="code targetlang">
4658 <pre>foo = Foo.new<br>begin<br> foo.test()<br>rescue CustomError => e<br> puts "Caught custom error"<br>end </pre>
4670 <p>For another example look at swig/Examples/ruby/exception_class.<br>
4682 <H2><a name="Ruby_nn37"></a>32.7 Typemaps</H2>
4685 <p> This section describes how you can modify SWIG's default
4686 wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt>
4687 directive. This is an advanced topic that assumes familiarity with the
4688 Ruby C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>"
4696 <p>Before proceeding, it should be stressed that typemaps are not
4697 a required part of using SWIG---the default wrapping behavior is enough
4698 in most cases. Typemaps are only used if you want to change some aspect
4699 of the primitive C-Ruby interface.</p>
4705 <H3><a name="Ruby_nn38"></a>32.7.1 What is a typemap?</H3>
4708 <p> A typemap is nothing more than a code generation rule that is
4709 attached to a specific C datatype. The general form of this declaration
4710 is as follows ( parts enclosed in [...] are optional
4711 ): </p>
4717 <div class="code"><span style="font-family: monospace;" class="code">%typemap( method [, modifiers...] ) typelist
4724 <p><em> method</em> is a simply a name that specifies
4725 what kind of typemap is being defined. It is usually a name like <tt>"in"</tt>,
4726 <tt>"out"</tt>, or <tt>"argout"</tt> (or its
4727 director variations). The purpose of these methods is described later.</p>
4733 <p><em> modifiers</em> is an optional comma separated
4735 name="value"</tt> values. These are sometimes to attach extra
4736 information to a typemap and is often target-language dependent.</p>
4742 <p><em> typelist</em> is a list of the C++ type
4743 patterns that the typemap will match. The general form of this list is
4750 <div class="diagram">
4751 <pre>typelist : typepattern [, typepattern, typepattern, ... ] ;<br><br>typepattern : type [ (parms) ]<br> | type name [ (parms) ]<br> | ( typelist ) [ (parms) ]<br></pre>
4763 <p> Each type pattern is either a simple type, a simple type and
4764 argument name, or a list of types in the case of multi-argument
4765 typemaps. In addition, each type pattern can be parameterized with a
4766 list of temporary variables (parms). The purpose of these variables
4767 will be explained shortly.</p>
4773 <p><em>code</em> specifies the C code used in the
4774 typemap. It can take any one of the following forms:</p>
4780 <div class="diagram">
4781 <pre>code : { ... }<br> | " ... "<br> | %{ ... %}<br></pre>
4793 <p>For example, to convert integers
4794 from Ruby to C, you might define a typemap like this: </p>
4801 <pre>%module example<br><br>%typemap(in) int {<br> $1 = (int) NUM2INT($input);<br> printf("Received an integer : %d\n",$1);<br>}<br><br>%inline %{<br>extern int fact(int n);<br>%}<br></pre>
4813 <p> Typemaps are always associated with some specific aspect of
4814 code generation. In this case, the "in" method refers to the conversion
4815 of input arguments to C/C++. The datatype <tt>int</tt> is
4816 the datatype to which the typemap will be applied. The supplied C code
4817 is used to convert values. In this code a number of special variables
4818 prefaced by a <tt>$</tt> are used. The <tt>$1</tt>
4819 variable is placeholder for a local variable of type <tt>int</tt>.
4820 The <tt>$input</tt> variable is the input Ruby object. </p>
4826 <p>When this example is compiled into a Ruby module, the
4827 following sample code: </p>
4833 <div class="code targetlang">
4834 <pre>require 'example'<br><br>puts Example.fact(6)<br></pre>
4846 <p>prints the result:</p>
4852 <div class="code shell">
4853 <pre>Received an integer : 6<br>720<br></pre>
4865 <p> In this example, the typemap is applied to all occurrences of
4866 the <tt>int</tt> datatype. You can refine this by
4867 supplying an optional parameter name. For example: </p>
4874 <pre>%module example<br><br>%typemap(in) int n {<br> $1 = (int) NUM2INT($input);<br> printf("n = %d\n",$1);<br>}<br><br>%inline %{<br>extern int fact(int n);<br>%}<br></pre>
4886 <p> In this case, the typemap code is only attached to arguments
4887 that exactly match "<tt>int n</tt>". </p>
4893 <p>The application of a typemap to specific datatypes and
4894 argument names involves more than simple text-matching--typemaps are
4895 fully integrated into the SWIG type-system. When you define a typemap
4896 for <tt>int</tt>, that typemap applies to <tt>int</tt>
4897 and qualified variations such as <tt>const int</tt>. In
4898 addition, the typemap system follows <tt>typedef</tt>
4899 declarations. For example: </p>
4906 <pre>%typemap(in) int n {<br> $1 = (int) NUM2INT($input);<br> printf("n = %d\n",$1);<br>}<br><br>typedef int Integer;<br>extern int fact(Integer n); // Above typemap is applied<br></pre>
4918 <p> However, the matching of <tt>typedef</tt> only
4919 occurs in one direction. If you defined a typemap for <tt>Integer</tt>,
4920 it is not applied to arguments of type <tt>int</tt>. </p>
4926 <p>Typemaps can also be defined for groups of consecutive
4927 arguments. For example: </p>
4934 <pre>%typemap(in) (char *str, int len) {<br> $1 = STR2CSTR($input);<br> $2 = (int) RSTRING($input)->len;<br>};<br><br>int count(char c, char *str, int len);<br></pre>
4946 <p> When a multi-argument typemap is defined, the arguments are
4947 always handled as a single Ruby object. This allows the function <tt>count</tt>
4948 to be used as follows (notice how the length parameter is omitted): </p>
4954 <div class="code targetlang">
4955 <pre>puts Example.count('o','Hello World')<br>2<br></pre>
4967 <H3><a name="Ruby_Typemap_scope"></a>32.7.2 Typemap scope</H3>
4970 <p> Once defined, a typemap remains in effect for all of the
4971 declarations that follow. A typemap may be redefined for different
4972 sections of an input file. For example:</p>
4979 <pre>// typemap1<br>%typemap(in) int {<br>...<br>}<br><br>int fact(int); // typemap1<br>int gcd(int x, int y); // typemap1<br><br>// typemap2<br>%typemap(in) int {<br>...<br>}<br><br>int isprime(int); // typemap2<br></pre>
4991 <p> One exception to the typemap scoping rules pertains to the <tt>
4992 %extend</tt> declaration. <tt>%extend</tt> is used
4993 to attach new declarations to a class or structure definition. Because
4994 of this, all of the declarations in an <tt>%extend</tt>
4995 block are subject to the typemap rules that are in effect at the point
4996 where the class itself is defined. For example:</p>
5003 <pre>class Foo {<br> ...<br>};<br><br>%typemap(in) int {<br> ...<br>}<br><br>%extend Foo {<br> int blah(int x); // typemap has no effect. Declaration is attached to Foo which <br> // appears before the %typemap declaration.<br>};<br></pre>
5015 <H3><a name="Ruby_Copying_a_typemap"></a>32.7.3 Copying a typemap</H3>
5018 <p> A typemap is copied by using assignment. For example:</p>
5025 <pre>%typemap(in) Integer = int;<br></pre>
5044 <pre>%typemap(in) Integer, Number, int32_t = int;<br></pre>
5056 <p> Types are often managed by a collection of different
5057 typemaps. For example:</p>
5064 <pre>%typemap(in) int { ... }<br>%typemap(out) int { ... }<br>%typemap(varin) int { ... }<br>%typemap(varout) int { ... }<br></pre>
5076 <p> To copy all of these typemaps to a new type, use <tt>%apply</tt>.
5084 <pre>%apply int { Integer }; // Copy all int typemaps to Integer<br>%apply int { Integer, Number }; // Copy all int typemaps to both Integer and Number<br></pre>
5096 <p> The patterns for <tt>%apply</tt> follow the same
5098 %typemap</tt>. For example:</p>
5105 <pre>%apply int *output { Integer *output }; // Typemap with name<br>%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments<br></pre>
5117 <H3><a name="Ruby_Deleting_a_typemap"></a>32.7.4 Deleting a typemap</H3>
5120 <p> A typemap can be deleted by simply defining no code. For
5128 <pre>%typemap(in) int; // Clears typemap for int<br>%typemap(in) int, long, short; // Clears typemap for int, long, short<br>%typemap(in) int *output; <br></pre>
5140 <p> The <tt>%clear</tt> directive clears all
5141 typemaps for a given type. For example:</p>
5148 <pre>%clear int; // Removes all types for int<br>%clear int *output, long *output;<br></pre>
5160 <p><b> Note:</b> Since SWIG's default behavior is
5161 defined by typemaps, clearing a fundamental type like <tt>int</tt>
5162 will make that type unusable unless you also define a new set of
5163 typemaps immediately after the clear operation.</p>
5169 <H3><a name="Ruby_Placement_of_typemaps"></a>32.7.5 Placement of typemaps</H3>
5172 <p> Typemap declarations can be declared in the global scope,
5173 within a C++ namespace, and within a C++ class. For example:</p>
5180 <pre>%typemap(in) int {<br> ...<br>}<br><br>namespace std {<br> class string;<br> %typemap(in) string {<br> ...<br> }<br>}<br><br>class Bar {<br>public:<br> typedef const int & const_reference;<br> %typemap(out) const_reference {<br> ...<br> }<br>};<br></pre>
5192 <p> When a typemap appears inside a namespace or class, it stays
5193 in effect until the end of the SWIG input (just like before). However,
5194 the typemap takes the local scope into account. Therefore, this code</p>
5201 <pre>namespace std {<br> class string;<br> %typemap(in) string {<br> ...<br> }<br>}<br></pre>
5213 <p> is really defining a typemap for the type <tt>std::string</tt>.
5214 You could have code like this:</p>
5221 <pre>namespace std {<br> class string;<br> %typemap(in) string { /* std::string */<br> ...<br> }<br>}<br><br>namespace Foo {<br> class string;<br> %typemap(in) string { /* Foo::string */<br> ...<br> }<br>}<br></pre>
5233 <p> In this case, there are two completely distinct typemaps that
5234 apply to two completely different types (<tt>std::string</tt>
5236 Foo::string</tt>).</p>
5242 <p> It should be noted that for scoping to work, SWIG has to know
5244 string</tt> is a typename defined within a particular namespace.
5245 In this example, this is done using the class declaration <tt>class
5253 <H3><a name="Ruby_nn39"></a>32.7.6 Ruby typemaps</H3>
5256 <p>The following list details all of the typemap methods that
5257 can be used by the Ruby module: </p>
5263 <H4><a name="Ruby_in_typemap"></a>32.7.6.1 "in" typemap</H4>
5266 <p>Converts Ruby objects to input
5267 function arguments. For example:
5275 <pre>%typemap(in) int {<br> $1 = NUM2INT($input);<br>}<br></pre>
5287 <p> The following special variables are available:</p>
5293 <div class="diagram">
5294 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - in typemap">
5312 <td style="font-family: monospace;">$input </td>
5318 <td style="font-family: monospace;"> Input object
5319 holding value to be converted.</td>
5337 <td style="font-family: monospace;">$symname </td>
5343 <td style="font-family: monospace;"> Name of
5344 function/method being wrapped</td>
5362 <td style="font-family: monospace;">$1...n </td>
5368 <td style="font-family: monospace;"> Argument being
5369 sent to the function</td>
5387 <td style="font-family: monospace;">$1_name </td>
5393 <td style="font-family: monospace;"> Name of the
5394 argument (if provided)</td>
5412 <td style="font-family: monospace;">$1_type </td>
5418 <td style="font-family: monospace;"> The actual C
5419 datatype matched by the typemap.</td>
5437 <td style="font-family: monospace;">$1_ltype </td>
5443 <td style="font-family: monospace;"> The assignable
5444 version of the C datatype matched by the typemap.</td>
5473 <p> This is probably the most commonly redefined typemap because
5474 it can be used to implement customized conversions.</p>
5480 <p> In addition, the "in" typemap allows the number of converted
5481 arguments to be specified. For example:</p>
5488 <pre>// Ignored argument.<br>%typemap(in, numinputs=0) int *out (int temp) {<br> $1 = &temp;<br>}<br></pre>
5500 <p> At this time, only zero or one arguments may be converted.</p>
5506 <H4><a name="Ruby_typecheck_typemap"></a>32.7.6.2 "typecheck" typemap</H4>
5509 <p> The "typecheck" typemap is used to support overloaded
5510 functions and methods. It merely checks an argument to see whether or
5511 not it matches a specific type. For example:</p>
5518 <pre>%typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {<br> $1 = FIXNUM_P($input) ? 1 : 0;<br>}<br></pre>
5530 <p> For typechecking, the $1 variable is always a simple integer
5531 that is set to 1 or 0 depending on whether or not the input argument is
5532 the correct type.</p>
5538 <p> If you define new "in" typemaps<em> and</em> your
5539 program uses overloaded methods, you should also define a collection of
5540 "typecheck" typemaps. More details about this follow in a later section
5541 on "Typemaps and Overloading."</p>
5547 <H4><a name="Ruby_out_typemap"></a>32.7.6.3 "out" typemap</H4>
5550 <p>Converts return value of a C function
5551 to a Ruby object.</p>
5557 <div class="code"><tt><br>
5563 %typemap(out) int {<br>
5569 $result = INT2NUM( $1 );<br>
5587 <p> The following special variables are available.</p>
5593 <div class="diagram">
5594 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - out typemap">
5612 <td style="font-family: monospace;">$result </td>
5618 <td style="font-family: monospace;"> Result object
5619 returned to target language.</td>
5637 <td style="font-family: monospace;">$symname </td>
5643 <td style="font-family: monospace;"> Name of
5644 function/method being wrapped</td>
5662 <td style="font-family: monospace;">$1...n </td>
5668 <td style="font-family: monospace;"> Argument being
5687 <td style="font-family: monospace;">$1_name </td>
5693 <td style="font-family: monospace;"> Name of the
5694 argument (if provided)</td>
5712 <td style="font-family: monospace;">$1_type </td>
5718 <td style="font-family: monospace;"> The actual C
5719 datatype matched by the typemap.</td>
5737 <td style="font-family: monospace;">$1_ltype </td>
5743 <td style="font-family: monospace;"> The assignable
5744 version of the C datatype matched by the typemap.</td>
5779 <H4><a name="Ruby_arginit_typemap"></a>32.7.6.4 "arginit" typemap</H4>
5782 <p> The "arginit" typemap is used to set the initial value of a
5783 function argument--before any conversion has occurred. This is not
5784 normally necessary, but might be useful in highly specialized
5785 applications. For example:</p>
5792 <pre>// Set argument to NULL before any conversion occurs<br>%typemap(arginit) int *data {<br> $1 = NULL;<br>}<br></pre>
5804 <H4><a name="Ruby_default_typemap"></a>32.7.6.5 "default" typemap</H4>
5807 <p> The "default" typemap is used to turn an argument into a
5808 default argument. For example:</p>
5815 <pre>%typemap(default) int flags {<br> $1 = DEFAULT_FLAGS;<br>}<br>...<br>int foo(int x, int y, int flags);<br></pre>
5827 <p> The primary use of this typemap is to either change the
5828 wrapping of default arguments or specify a default argument in a
5829 language where they aren't supported (like C). Target languages that do
5830 not support optional arguments, such as Java and C#, effectively ignore
5831 the value specified by this typemap as all arguments must be given.</p>
5837 <p> Once a default typemap has been applied to an argument, all
5838 arguments that follow must have default values. See the <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#SWIG_default_args">
5839 Default/optional arguments</a> section for further information on
5840 default argument wrapping.</p>
5846 <H4><a name="Ruby_check_typemap"></a>32.7.6.6 "check" typemap</H4>
5849 <p> The "check" typemap is used to supply value checking code
5850 during argument conversion. The typemap is applied<em> after</em>
5851 arguments have been converted. For example:</p>
5858 <pre>%typemap(check) int positive {<br> if ($1 <= 0) {<br> SWIG_exception(SWIG_ValueError,"Expected positive value.");<br> }<br>}<br></pre>
5870 <H4><a name="Ruby_argout_typemap_"></a>32.7.6.7 "argout" typemap</H4>
5873 <p> The "argout" typemap is used to return values from arguments.
5874 This is most commonly used to write wrappers for C/C++ functions that
5875 need to return multiple values. The "argout" typemap is almost always
5876 combined with an "in" typemap---possibly to ignore the input value. For
5884 <pre>/* Set the input argument to point to a temporary variable */<br>%typemap(in, numinputs=0) int *out (int temp) {<br> $1 = &temp;<br>}<br><br>%typemap(argout, fragment="output_helper") int *out {<br> // Append output value $1 to $result (assuming a single integer in this case)<br> $result = output_helper( $result, INT2NUM(*$1) );<br>}<br></pre>
5896 <p> The following special variables are available.</p>
5902 <div class="diagram">
5903 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - argout typemap">
5921 <td style="font-family: monospace;">$result </td>
5927 <td style="font-family: monospace;"> Result object
5928 returned to target language.</td>
5946 <td style="font-family: monospace;">$input </td>
5952 <td style="font-family: monospace;"> The original
5953 input object passed.</td>
5971 <td style="font-family: monospace;">$symname </td>
5977 <td style="font-family: monospace;"> Name of
5978 function/method being wrapped.</td>
6007 <p> The code supplied to the "argout" typemap is always placed
6008 after the "out" typemap. If multiple return values are used, the extra
6009 return values are often appended to return value of the function.</p>
6015 <p>Output helper is a fragment that usually defines a macro to
6016 some function like SWIG_Ruby_AppendOutput.</p>
6022 <p> See the <tt>typemaps.i</tt> library for examples.</p>
6028 <H4><a name="Ruby_freearg_typemap_"></a>32.7.6.8 "freearg" typemap</H4>
6031 <p> The "freearg" typemap is used to cleanup argument data. It is
6032 only used when an argument might have allocated resources that need to
6033 be cleaned up when the wrapper function exits. The "freearg" typemap
6034 usually cleans up argument resources allocated by the "in" typemap. For
6042 <pre>// Get a list of integers<br>%typemap(in) int *items {<br> int nitems = Length($input); <br> $1 = (int *) malloc(sizeof(int)*nitems);<br>}<br>// Free the list <br>%typemap(freearg) int *items {<br> free($1);<br>}<br></pre>
6054 <p> The "freearg" typemap inserted at the end of the wrapper
6055 function, just before control is returned back to the target language.
6056 This code is also placed into a special variable <tt>$cleanup</tt>
6057 that may be used in other typemaps whenever a wrapper function needs to
6058 abort prematurely.</p>
6064 <H4><a name="Ruby_newfree_typemap"></a>32.7.6.9 "newfree" typemap</H4>
6067 <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
6068 directive and is used to deallocate memory used by the return result of
6069 a function. For example:</p>
6076 <pre>%typemap(newfree) string * {<br> delete $1;<br>}<br>%typemap(out) string * {<br> $result = PyString_FromString($1->c_str());<br>}<br>...<br><br>%newobject foo;<br>...<br>string *foo();<br></pre>
6088 <p> See <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#ownership">Object
6089 ownership and %newobject</a> for further details.</p>
6095 <H4><a name="Ruby_memberin_typemap"></a>32.7.6.10 "memberin" typemap</H4>
6098 <p> The "memberin" typemap is used to copy data from<em> an
6099 already converted input value</em> into a structure member. It is
6100 typically used to handle array members and other special cases. For
6108 <pre>%typemap(memberin) int [4] {<br> memmove($1, $input, 4*sizeof(int));<br>}<br></pre>
6120 <p> It is rarely necessary to write "memberin" typemaps---SWIG
6121 already provides a default implementation for arrays, strings, and
6128 <H4><a name="Ruby_varin_typemap"></a>32.7.6.11 "varin" typemap</H4>
6131 <p> The "varin" typemap is used to convert objects in the target
6132 language to C for the purposes of assigning to a C/C++ global variable.
6133 This is implementation specific.</p>
6139 <H4><a name="Ruby_varout_typemap_"></a>32.7.6.12 "varout" typemap</H4>
6142 <p> The "varout" typemap is used to convert a C/C++ object to an
6143 object in the target language when reading a C/C++ global variable.
6144 This is implementation specific.</p>
6150 <H4><a name="Ruby_throws_typemap"></a>32.7.6.13 "throws" typemap</H4>
6153 <p> The "throws" typemap is only used when SWIG parses a C++
6154 method with an exception specification or has the <tt>%catches</tt>
6155 feature attached to the method. It provides a default mechanism for
6156 handling C++ methods that have declared the exceptions they will throw.
6157 The purpose of this typemap is to convert a C++ exception into an error
6158 or exception in the target language. It is slightly different to the
6159 other typemaps as it is based around the exception type rather than the
6160 type of a parameter or variable. For example:</p>
6167 <pre>%typemap(throws) const char * %{<br> rb_raise(rb_eRuntimeError, $1);<br> SWIG_fail;<br>%}<br>void bar() throw (const char *);<br></pre>
6179 <p> As can be seen from the generated code below, SWIG generates
6180 an exception handler with the catch block comprising the "throws"
6181 typemap content.</p>
6188 <pre>...<br>try {<br> bar();<br>}<br>catch(char const *_e) {<br> rb_raise(rb_eRuntimeError, _e);<br> SWIG_fail;<br>}<br>...<br></pre>
6200 <p> Note that if your methods do not have an exception
6201 specification yet they do throw exceptions, SWIG cannot know how to
6202 deal with them. For a neat way to handle these, see the <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#exception">Exception
6203 handling with %exception</a> section.</p>
6209 <H4><a name="Ruby_directorin_typemap"></a>32.7.6.14 directorin typemap</H4>
6212 <p>Converts C++ objects in director
6213 member functions to ruby objects. It is roughly the opposite
6214 of the "in" typemap, making its typemap rule often similar to the "out"
6222 <div class="code"><tt><br>
6228 %typemap(directorin) int {<br>
6234 $result = INT2NUM($1);<br>
6252 <p> The following special variables are available.</p>
6258 <div class="diagram">
6259 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - directorin typemap">
6277 <td style="font-family: monospace;">$result </td>
6283 <td style="font-family: monospace;"> Result object
6284 returned to target language.</td>
6302 <td style="font-family: monospace;">$symname </td>
6308 <td style="font-family: monospace;"> Name of
6309 function/method being wrapped</td>
6327 <td style="font-family: monospace;">$1...n </td>
6333 <td style="font-family: monospace;"> Argument being
6352 <td style="font-family: monospace;">$1_name </td>
6358 <td style="font-family: monospace;"> Name of the
6359 argument (if provided)</td>
6377 <td style="font-family: monospace;">$1_type </td>
6383 <td style="font-family: monospace;"> The actual C
6384 datatype matched by the typemap.</td>
6402 <td style="font-family: monospace;">$1_ltype </td>
6408 <td style="font-family: monospace;"> The assignable
6409 version of the C datatype matched by the typemap.</td>
6427 <td style="font-family: monospace;">this </td>
6433 <td style="font-family: monospace;"> C++ this,
6434 referring to the class itself.</td>
6463 <H4><a name="Ruby_directorout_typemap"></a>32.7.6.15 directorout typemap</H4>
6466 <p>Converts Ruby objects in director
6467 member functions to C++ objects. It is roughly the opposite
6468 of the "out" typemap, making its rule often similar to the "in"
6476 <div class="code"><tt style="font-family: monospace;"><br>
6482 %typemap(directorout) int {</tt><tt><br>
6488 $result = NUM2INT($1);</tt><br>
6494 <tt style="font-family: monospace;">}<br>
6506 <p> The following special variables are available:</p>
6512 <div class="diagram">
6513 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - directorout typemap">
6531 <td style="font-family: monospace;">$symname </td>
6537 <td style="font-family: monospace;"> Name of
6538 function/method being wrapped</td>
6556 <td style="font-family: monospace;">$1...n </td>
6562 <td style="font-family: monospace;"> Argument being
6563 sent to the function</td>
6581 <td style="font-family: monospace;">$1_name </td>
6587 <td style="font-family: monospace;"> Name of the
6588 argument (if provided)</td>
6606 <td style="font-family: monospace;">$1_type </td>
6612 <td style="font-family: monospace;"> The actual C
6613 datatype matched by the typemap.</td>
6631 <td style="font-family: monospace;">$1_ltype </td>
6637 <td style="font-family: monospace;"> The assignable
6638 version of the C datatype matched by the typemap.</td>
6656 <td style="font-family: monospace;">this </td>
6662 <td style="font-family: monospace;"> C++ this,
6663 referring to the class itself.</td>
6692 <p>Currently, the directorout nor the out typemap support the
6693 option <span style="font-family: monospace;">numoutputs</span>,
6694 but the Ruby module provides that functionality through a %feature
6695 directive. Thus, a function can be made to return "nothing"
6702 <div style="font-family: monospace;" class="code">%feature("numoutputs","0")
6703 MyClass::function;</div>
6709 <p>This feature can be useful if a function returns a status
6710 code, which you want to discard but still use the typemap to raise an
6723 <H4><a name="Ruby_directorargout_typemap"></a>32.7.6.16 directorargout typemap</H4>
6726 <p>Output argument processing in director
6727 member functions.</p>
6733 <div class="code"><tt style="font-family: monospace;">%typemap(directorargout,
6734 fragment="output_helper") int {</tt><tt><br>
6740 $result = output_helper( $result, NUM2INT($1) );</tt><br>
6746 <tt style="font-family: monospace;">}</tt></div>
6752 <p> The following special variables are available:</p>
6758 <div class="diagram">
6759 <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2" summary="Special variables - directorargout typemap">
6777 <td style="font-family: monospace;">$result</td>
6783 <td style="font-family: monospace;">Result that the
6784 director function returns</td>
6802 <td style="font-family: monospace;">$symname</td>
6808 <td style="font-family: monospace;">name of the
6809 function/method being wrapped</td>
6827 <td style="font-family: monospace;">$1...n</td>
6833 <td style="font-family: monospace;">Argument being
6834 sent to the function</td>
6852 <td style="font-family: monospace;">$1_name</td>
6858 <td style="font-family: monospace;">Name of the
6859 argument (if provided)</td>
6877 <td style="font-family: monospace;">$1_type</td>
6883 <td style="font-family: monospace;">The actual C
6884 datatype matched by the typemap</td>
6902 <td style="font-family: monospace;">$1_ltype</td>
6908 <td style="font-family: monospace;">The assignable
6909 version of the C datatype matched by the typemap</td>
6927 <td style="font-family: monospace;">this</td>
6933 <td style="font-family: monospace;">C++ this,
6934 referring to the instance of the class itself</td>
6963 <H4><a name="Ruby_ret_typemap"></a>32.7.6.17 ret typemap</H4>
6966 <p>Cleanup of function return values
6973 <H4><a name="Ruby_globalin_typemap"></a>32.7.6.18 globalin typemap</H4>
6976 <p>Setting of C global variables
6983 <H3><a name="Ruby_nn40"></a>32.7.7 Typemap variables</H3>
6987 Within a typemap, a number of special variables prefaced with a <tt>$</tt>
6988 may appear. A full list of variables can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
6989 This is a list of the most common variables:
7002 <div class="indent">A C local variable corresponding to
7003 the actual type specified in the <tt>%typemap</tt>
7004 directive. For input values, this is a C local variable that is
7005 supposed to hold an argument value. For output values, this is the raw
7006 result that is supposed to be returned to Ruby. </div>
7012 <p><tt>$input</tt></p>
7018 <div class="indent">A <tt>VALUE</tt> holding
7019 a raw Ruby object with an argument or variable value. </div>
7025 <p><tt>$result</tt></p>
7031 <div class="indent">A <tt>VALUE</tt> that
7032 holds the result to be returned to Ruby. </div>
7038 <p><tt>$1_name</tt></p>
7044 <div class="indent">The parameter name that was matched. </div>
7050 <p><tt>$1_type</tt></p>
7056 <div class="indent">The actual C datatype matched by the
7063 <p><tt>$1_ltype</tt></p>
7069 <div class="indent">An assignable version of the datatype
7070 matched by the typemap (a type that can appear on the left-hand-side of
7071 a C assignment operation). This type is stripped of qualifiers and may
7072 be an altered version of <tt>$1_type</tt>. All arguments
7073 and local variables in wrapper functions are declared using this type
7074 so that their values can be properly assigned. </div>
7080 <p><tt>$symname</tt></p>
7086 <div class="indent">The Ruby name of the wrapper function
7087 being created. </div>
7093 <H3><a name="Ruby_nn41"></a>32.7.8 Useful Functions</H3>
7096 <p> When you write a typemap, you usually have to work directly
7097 with Ruby objects. The following functions may prove to be useful.
7098 (These functions plus many more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
7099 Ruby</em></a>, by David Thomas and Andrew Hunt.) </p>
7100 <p>In addition, we list equivalent functions that Swig defines, which
7101 provide a language neutral conversion (these functions are defined for
7102 each swig language supported). If you are trying to create a swig
7103 file that will work under multiple languages, it is recommended you
7104 stick to the swig functions instead of the native Ruby functions.
7105 That should help you avoid having to rewrite a lot of typemaps
7106 across multiple languages.</p>
7117 <H4><a name="Ruby_nn42"></a>32.7.8.1 C Datatypes to Ruby Objects</H4>
7120 <div class="diagram">
7121 <table style="width: 100%;" border="1" cellpadding="2" cellspacing="2" summary="Datatypes">
7125 <th style="font-weight: bold;">RUBY</th>
7126 <th style="font-weight: bold;">Swig</th>
7130 <td style="font-family: monospace;">INT2NUM(long or int) </td>
7131 <td style="font-family: monospace;">SWIG_From_int(int x)</td>
7132 <td> int to Fixnum or Bignum</td>
7136 <td style="font-family: monospace;">INT2FIX(long or int) </td>
7137 <td style="font-family: monospace;"></td>
7138 <td> int to Fixnum (faster than INT2NUM)</td>
7142 <td style="font-family: monospace;">CHR2FIX(char) </td>
7143 <td style="font-family: monospace;">SWIG_From_char(char x)</td>
7144 <td> char to Fixnum</td>
7148 <td style="font-family: monospace;">rb_str_new2(char*) </td>
7149 <td style="font-family: monospace;">SWIG_FromCharPtrAndSize(char*, size_t)</td>
7150 <td> char* to String</td>
7154 <td style="font-family: monospace;">rb_float_new(double) </td>
7155 <td style="font-family: monospace;">SWIG_From_double(double),<br>
7156 SWIG_From_float(float)</td>
7157 <td>float/double to Float</td>
7173 <H4><a name="Ruby_nn43"></a>32.7.8.2 Ruby Objects to C Datatypes</H4>
7176 <p>Here, while the Ruby versions return the value directly, the SWIG
7177 versions do not, but return a status value to indicate success (<span style="font-family: monospace;">SWIG_OK</span>). While more akward to use, this allows you to write typemaps that report more helpful error messages, like:</p>
7178 <div style="font-family: monospace;" class="code"><br>
7179 %typemap(in) size_t (int ok)<br>
7181 ok = SWIG_AsVal_size_t($input, &$1);<br>
7182 if (!SWIG_IsOK(ok)) {<br>
7183 SWIG_exception_fail(SWIG_ArgError(ok),
7184 Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
7189 <div style="font-family: monospace;"> </div>
7190 <div class="diagram">
7191 <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Ruby objects">
7195 <td style="font-family: monospace;">int NUM2INT(Numeric)</td>
7196 <td style="font-family: monospace;">SWIG_AsVal_int(VALUE, int*)</td>
7200 <td style="font-family: monospace;">int FIX2INT(Numeric)</td>
7201 <td style="font-family: monospace;">SWIG_AsVal_int(VALUE, int*)</td>
7205 <td style="font-family: monospace;">unsigned int NUM2UINT(Numeric)</td>
7206 <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</td>
7210 <td style="font-family: monospace;">unsigned int FIX2UINT(Numeric)</td>
7211 <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</td>
7215 <td style="font-family: monospace;">long NUM2LONG(Numeric)</td>
7216 <td style="font-family: monospace;">SWIG_AsVal_long(VALUE, long*)</td>
7220 <td style="font-family: monospace;">long FIX2LONG(Numeric)</td>
7221 <td style="font-family: monospace;">SWIG_AsVal_long(VALUE, long*)</td>
7225 <td style="font-family: monospace;">unsigned long FIX2ULONG(Numeric)</td>
7226 <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_long(VALUE, unsigned long*)</td>
7230 <td style="font-family: monospace;">char NUM2CHR(Numeric or String)</td>
7231 <td style="font-family: monospace;">SWIG_AsVal_char(VALUE, int*)</td>
7235 <td style="font-family: monospace;">char * STR2CSTR(String)</td>
7236 <td style="font-family: monospace;">SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td>
7240 <td style="font-family: monospace;">char * rb_str2cstr(String, int*length)</td>
7241 <td style="font-family: monospace;"></td>
7245 <td style="font-family: monospace;">double NUM2DBL(Numeric)</td>
7246 <td style="font-family: monospace;">(double) SWIG_AsVal_int(VALUE) or similar</td>
7262 <H4><a name="Ruby_nn44"></a>32.7.8.3 Macros for VALUE</H4>
7265 <p> <tt>RSTRING_LEN(str)</tt> </p>
7271 <div class="indent">length of the Ruby string</div>
7277 <p><tt>RSTRING_PTR(str)</tt></p>
7283 <div class="indent">pointer to string storage</div>
7289 <p><tt>RARRAY_LEN(arr)</tt></p>
7295 <div class="indent">length of the Ruby array</div>
7301 <p><tt>RARRAY(arr)->capa</tt></p>
7307 <div class="indent">capacity of the Ruby array</div>
7313 <p><tt>RARRAY_PTR(arr)</tt></p>
7319 <div class="indent">pointer to array storage</div>
7325 <H4><a name="Ruby_nn45"></a>32.7.8.4 Exceptions</H4>
7328 <p> <tt>void rb_raise(VALUE exception, const char *fmt,
7335 <div class="indent"> Raises an exception. The given format
7336 string <i>fmt</i> and remaining arguments are interpreted
7337 as with <tt>printf()</tt>. </div>
7343 <p><tt>void rb_fatal(const char *fmt, ...)</tt></p>
7349 <div class="indent"> Raises a fatal exception, terminating
7350 the process. No rescue blocks are called, but ensure blocks will be
7351 called. The given format string <i>fmt</i> and remaining
7352 arguments are interpreted as with <tt>printf()</tt>. </div>
7358 <p><tt>void rb_bug(const char *fmt, ...)</tt></p>
7364 <div class="indent"> Terminates the process immediately --
7365 no handlers of any sort will be called. The given format string <i>fmt</i>
7366 and remaining arguments are interpreted as with <tt>printf()</tt>.
7367 You should call this function only if a fatal bug has been exposed. </div>
7373 <p><tt>void rb_sys_fail(const char *msg)</tt></p>
7379 <div class="indent"> Raises a platform-specific exception
7380 corresponding to the last known system error, with the given string <i>msg</i>.
7387 <p><tt>VALUE rb_rescue(VALUE (*body)(VALUE), VALUE args,
7388 VALUE(*rescue)(VALUE, VALUE), VALUE rargs)</tt></p>
7394 <div class="indent"> Executes <i>body</i>
7395 with the given <i>args</i>. If a <tt>StandardError</tt>
7396 exception is raised, then execute <i>rescue</i> with the
7397 given <i>rargs</i>. </div>
7403 <p><tt>VALUE rb_ensure(VALUE(*body)(VALUE), VALUE args,
7404 VALUE(*ensure)(VALUE), VALUE eargs)</tt></p>
7410 <div class="indent"> Executes <i>body</i>
7411 with the given <i>args</i>. Whether or not an exception is
7412 raised, execute <i>ensure</i> with the given <i>rargs</i>
7413 after <i>body</i> has completed. </div>
7419 <p><tt>VALUE rb_protect(VALUE (*body)(VALUE), VALUE args,
7420 int *result)</tt></p>
7426 <div class="indent"> Executes <i>body</i>
7427 with the given <i>args</i> and returns nonzero in result
7428 if any exception was raised. </div>
7434 <p><tt>void rb_notimplement()</tt></p>
7440 <div class="indent"> Raises a <tt>NotImpError</tt>
7441 exception to indicate that the enclosed function is not implemented
7442 yet, or not available on this platform. </div>
7448 <p><tt>void rb_exit(int status)</tt></p>
7454 <div class="indent"> Exits Ruby with the given <i>status</i>.
7455 Raises a <tt>SystemExit</tt> exception and calls
7456 registered exit functions and finalizers. </div>
7462 <p><tt>void rb_warn(const char *fmt, ...)</tt></p>
7468 <div class="indent"> Unconditionally issues a warning
7469 message to standard error. The given format string <i>fmt</i>
7470 and remaining arguments are interpreted as with <tt>printf()</tt>.
7477 <p><tt>void rb_warning(const char *fmt, ...)</tt></p>
7483 <div class="indent"> Conditionally issues a warning
7484 message to standard error if Ruby was invoked with the <tt>-w</tt>
7485 flag. The given format string <i>fmt</i> and remaining
7486 arguments are interpreted as with <tt>printf()</tt>. </div>
7492 <H4><a name="Ruby_nn46"></a>32.7.8.5 Iterators</H4>
7495 <p> <tt>void rb_iter_break()</tt> </p>
7501 <div class="indent"> Breaks out of the enclosing iterator
7508 <p><tt>VALUE rb_each(VALUE obj)</tt></p>
7514 <div class="indent"> Invokes the <tt>each</tt>
7515 method of the given <i>obj</i>. </div>
7521 <p><tt>VALUE rb_yield(VALUE arg)</tt></p>
7527 <div class="indent"> Transfers execution to the iterator
7528 block in the current context, passing <i>arg</i> as an
7529 argument. Multiple values may be passed in an array. </div>
7535 <p><tt>int rb_block_given_p()</tt></p>
7541 <div class="indent"> Returns <tt>true</tt> if
7542 <tt>yield</tt> would execute a block in the current
7543 context; that is, if a code block was passed to the current method and
7544 is available to be called. </div>
7550 <p><tt>VALUE rb_iterate(VALUE (*method)(VALUE), VALUE args,
7551 VALUE (*block)(VALUE, VALUE), VALUE arg2)</tt></p>
7557 <div class="indent"> Invokes <i>method</i>
7558 with argument <i>args</i> and block <i>block</i>.
7559 A <tt>yield</tt> from that method will invoke <i>block</i>
7560 with the argument given to <tt>yield</tt>, and a second
7561 argument <i>arg2</i>. </div>
7567 <p><tt>VALUE rb_catch(const char *tag, VALUE (*proc)(VALUE,
7568 VALUE), VALUE value)</tt></p>
7574 <div class="indent"> Equivalent to Ruby's <tt>catch</tt>.
7581 <p><tt>void rb_throw(const char *tag, VALUE value)</tt></p>
7587 <div class="indent"> Equivalent to Ruby's <tt>throw</tt>.
7594 <H3><a name="Ruby_nn47"></a>32.7.9 Typemap Examples</H3>
7597 <p> This section includes a few examples of typemaps. For more
7598 examples, you might look at the examples in the <tt>Example/ruby</tt>
7605 <H3><a name="Ruby_nn48"></a>32.7.10 Converting a Ruby array to a char **</H3>
7608 <p> A common problem in many C programs is the processing of
7609 command line arguments, which are usually passed in an array of <tt>NULL</tt>
7610 terminated strings. The following SWIG interface file allows a Ruby
7611 Array instance to be used as a <tt>char **</tt> object. </p>
7618 <pre>%module argv<br><br>// This tells SWIG to treat char ** as a special case<br>%typemap(in) char ** {<br> /* Get the length of the array */<br> int size = RARRAY($input)->len; <br> int i;<br> $1 = (char **) malloc((size+1)*sizeof(char *));<br> /* Get the first element in memory */<br> VALUE *ptr = RARRAY($input)->ptr; <br> for (i=0; i < size; i++, ptr++)<br> /* Convert Ruby Object String to char* */<br> $1[i]= STR2CSTR(*ptr); <br> $1[i]=NULL; /* End of list */<br>}<br><br>// This cleans up the char ** array created before <br>// the function call<br><br>%typemap(freearg) char ** {<br> free((char *) $1);<br>}<br><br>// Now a test function<br>%inline %{<br>int print_args(char **argv) {<br> int i = 0;<br> while (argv[i]) {<br> printf("argv[%d] = %s\n", i,argv[i]);<br> i++;<br> }<br> return i;<br>}<br>%}<br><br></pre>
7630 <p> When this module is compiled, the wrapped C function now
7631 operates as follows : </p>
7637 <div class="code targetlang">
7638 <pre>require 'Argv'<br>Argv.print_args(["Dave","Mike","Mary","Jane","John"])<br>argv[0] = Dave<br>argv[1] = Mike<br>argv[2] = Mary<br>argv[3] = Jane<br>argv[4] = John<br></pre>
7650 <p> In the example, two different typemaps are used. The "in"
7651 typemap is used to receive an input argument and convert it to a C
7652 array. Since dynamic memory allocation is used to allocate memory for
7653 the array, the "freearg" typemap is used to later release this memory
7654 after the execution of the C function. </p>
7660 <H3><a name="Ruby_nn49"></a>32.7.11 Collecting arguments in a hash</H3>
7663 <p> Ruby's solution to the "keyword arguments" capability of some
7664 other languages is to allow the programmer to pass in one or more
7665 key-value pairs as arguments to a function. All of those key-value
7666 pairs are collected in a single <tt>Hash</tt> argument
7667 that's presented to the function. If it makes sense, you might want to
7668 provide similar functionality for your Ruby interface. For example,
7669 suppose you'd like to wrap this C function that collects information
7670 about people's vital statistics: </p>
7677 <pre>void setVitalStats(const char *person, int nattributes, const char **names, int *values);<br></pre>
7689 <p> and you'd like to be able to call it from Ruby by passing in
7690 an arbitrary number of key-value pairs as inputs, e.g. </p>
7696 <div class="code targetlang">
7697 <pre>setVitalStats("Fred",<br> 'weight' => 270,<br> 'age' => 42<br> )<br></pre>
7709 <p> To make this work, you need to write a typemap that expects a
7710 Ruby <tt>Hash</tt> as its input and somehow extracts the
7711 last three arguments (<i>nattributes</i>, <i>names</i>
7712 and <i>values</i>) needed by your C function. Let's start
7713 with the basics: </p>
7720 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br>}<br> </pre>
7732 <p> This <tt>%typemap</tt> directive tells SWIG that
7733 we want to match any function declaration that has the specified types
7734 and names of arguments somewhere in the argument list. The fact that we
7735 specified the argument names (<i>nattributes</i>, <i>names</i>
7736 and <i>values</i>) in our typemap is significant; this
7737 ensures that SWIG won't try to apply this typemap to <i>other</i>
7738 functions it sees that happen to have a similar declaration with
7739 different argument names. The arguments that appear in the second set
7740 of parentheses (<i>keys_arr</i>, <i>i</i>, <i>key</i>
7741 and <i>val</i>) define local variables that our typemap
7748 <p>Since we expect the input argument to be a <tt>Hash</tt>,
7749 let's next add a check for that: </p>
7756 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> <b>Check_Type($input, T_HASH);</b><br>}<br></pre>
7768 <p> <tt>Check_Type()</tt> is just a macro (defined
7769 in the Ruby header files) that confirms that the input argument is of
7770 the correct type; if it isn't, an exception will be raised. </p>
7776 <p>The next task is to determine how many key-value pairs are
7777 present in the hash; we'll assign this number to the first typemap
7778 argument (<tt>$1</tt>). This is a little tricky since the
7779 Ruby/C API doesn't provide a public function for querying the size of a
7780 hash, but we can get around that by calling the hash's <i>size</i>
7781 method directly and converting its result to a C <tt>int</tt>
7789 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> <b>$1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));</b><br>}<br></pre>
7801 <p> So now we know the number of attributes. Next we need to
7802 initialize the second and third typemap arguments (i.e. the two C
7803 arrays) to <tt>NULL</tt> and set the stage for extracting
7804 the keys and values from the hash: </p>
7811 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> <b>$2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> }</b><br>}<br></pre>
7823 <p> There are a number of ways we could extract the keys and
7824 values from the input hash, but the simplest approach is to first call
7825 the hash's <i>keys</i> method (which returns a Ruby array
7826 of the keys) and then start looping over the elements in that array: </p>
7833 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> <b>keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> }</b><br>}<br>}<br></pre>
7845 <p> Recall that <i>keys_arr</i> and <i>i</i>
7846 are local variables for this typemap. For each element in the <i>keys_arr</i>
7847 array, we want to get the key itself, as well as the value
7848 corresponding to that key in the hash: </p>
7855 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> <b>key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);</b><br>}<br>}<br>}<br></pre>
7867 <p> To be safe, we should again use the <tt>Check_Type()</tt>
7868 macro to confirm that the key is a <tt>String</tt> and the
7869 value is a <tt>Fixnum</tt>: </p>
7876 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> <b>Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);</b><br>}<br>}<br>}<br></pre>
7888 <p> Finally, we can convert these Ruby objects into their C
7889 equivalents and store them in our local C arrays: </p>
7896 <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);<br> <b>$2[i] = STR2CSTR(key);<br> $3[i] = NUM2INT(val);</b><br>}<br>}<br>}<br></pre>
7908 <p> We're not done yet. Since we used <tt>malloc()</tt>
7909 to dynamically allocate the memory used for the <i>names</i>
7910 and <i>values</i> arguments, we need to provide a
7911 corresponding "freearg" typemap to free that memory so that there is no
7912 memory leak. Fortunately, this typemap is a lot easier to write: </p>
7919 <pre>%typemap(freearg) (int nattributes, const char **names, const int *values) {<br> free((void *) $2);<br> free((void *) $3);<br>}<br></pre>
7931 <p> All of the code for this example, as well as a sample Ruby
7932 program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
7933 directory of the SWIG distribution. </p>
7939 <H3><a name="Ruby_nn50"></a>32.7.12 Pointer handling</H3>
7942 <p> Occasionally, it might be necessary to convert pointer values
7943 that have been stored using the SWIG typed-pointer representation.
7944 Since there are several ways in which pointers can be represented, the
7945 following two functions are used to safely perform this conversion: </p>
7951 <p><tt>int SWIG_ConvertPtr(VALUE obj, void **ptr,
7952 swig_type_info *ty, int flags)</tt> </p>
7958 <div class="indent">Converts a Ruby object <i>obj</i>
7959 to a C pointer whose address is <i>ptr</i> (i.e. <i>ptr</i>
7960 is a pointer to a pointer). The third argument, <i>ty</i>,
7961 is a pointer to a SWIG type descriptor structure. If <i>ty</i>
7962 is not <tt>NULL</tt>, that type information is used to
7963 validate type compatibility and other aspects of the type conversion.
7964 If <i>flags</i> is non-zero, any type errors encountered
7965 during this validation result in a Ruby <tt>TypeError</tt>
7966 exception being raised; if <i>flags</i> is zero, such type
7967 errors will cause <tt>SWIG_ConvertPtr()</tt> to return -1
7968 but not raise an exception. If <i>ty</i> is <tt>NULL</tt>,
7969 no type-checking is performed. </div>
7975 <p> <tt>VALUE SWIG_NewPointerObj(void *ptr, swig_type_info
7976 *ty, int own)</tt> </p>
7982 <div class="indent">Creates a new Ruby pointer object.
7983 Here, <i>ptr</i> is the pointer to convert, <i>ty</i>
7984 is the SWIG type descriptor structure that describes the type, and <i>own</i>
7985 is a flag that indicates whether or not Ruby should take ownership of
7986 the pointer (i.e. whether Ruby should free this data when the
7987 corresponding Ruby instance is garbage-collected). </div>
7993 <p> Both of these functions require the use of a special SWIG
7994 type-descriptor structure. This structure contains information about
7995 the mangled name of the datatype, type-equivalence information, as well
7996 as information about converting pointer values under C++ inheritance.
7997 For a type of <tt>Foo *</tt>, the type descriptor
7998 structure is usually accessed as follows: </p>
8004 <div class="indent code">
8005 <pre>Foo *foo;<br>SWIG_ConvertPtr($input, (void **) &foo, SWIGTYPE_p_Foo, 1);<br><br>VALUE obj;<br>obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);<br></pre>
8017 <p> In a typemap, the type descriptor should always be accessed
8018 using the special typemap variable <tt>$1_descriptor</tt>.
8025 <div class="indent code">
8026 <pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);<br>}<br></pre>
8038 <H4><a name="Ruby_nn51"></a>32.7.12.1 Ruby Datatype Wrapping</H4>
8041 <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
8042 (*mark)(void *), void (*free)(void *), void *ptr)</tt> </p>
8048 <div class="indent">Given a pointer <i>ptr</i>
8049 to some C data, and the two garbage collection routines for this data (<i>mark</i>
8050 and <i>free</i>), return a <tt>VALUE</tt> for
8051 the Ruby object. </div>
8057 <p><tt>VALUE Data_Make_Struct(VALUE class, <i>c-type</i>,
8058 void (*mark)(void *), void (*free)(void *), <i>c-type</i>
8065 <div class="indent">Allocates a new instance of a C data
8066 type <i>c-type</i>, assigns it to the pointer <i>ptr</i>,
8067 then wraps that pointer with <tt>Data_Wrap_Struct()</tt>
8074 <p><tt>Data_Get_Struct(VALUE obj, <i>c-type</i>,
8075 <i>c-type</i> *ptr)</tt></p>
8081 <div class="indent">Retrieves the original C pointer of
8082 type <i>c-type</i> from the data object <i>obj</i>
8083 and assigns that pointer to <i>ptr</i>. </div>
8089 <H3><a name="Ruby_nn52"></a>32.7.13 Example: STL Vector to Ruby Array</H3>
8092 <p>Another use for macros and type maps is to create a Ruby array
8093 from a STL vector of pointers. In essence, copy of all the pointers in
8094 the vector into a Ruby array. The use of the macro is to make the
8095 typemap so generic that any vector with pointers can use the type map.
8096 The following is an example of how to construct this type of
8097 macro/typemap and should give insight into constructing similar
8098 typemaps for other STL structures: </p>
8105 <pre>%define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)<br>%typemap(out) vectorclassname &, const vectorclassname & {<br> VALUE arr = rb_ary_new2($1->size());<br> vectorclassname::iterator i = $1->begin(), iend = $1->end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%typemap(out) vectorclassname, const vectorclassname {<br> VALUE arr = rb_ary_new2($1.size());<br> vectorclassname::iterator i = $1.begin(), iend = $1.end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%enddef<br></pre>
8117 <p> Note, that the "<tt>c ## classname.klass"</tt> is
8118 used in the preprocessor step to determine the actual object from the
8125 <p>To use the macro with a class Foo, the following is used: </p>
8132 <pre>PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)<br></pre>
8144 <p> It is also possible to create a STL vector of Ruby objects: </p>
8151 <pre>%define RUBY_ARRAY_TO_PTR_VECTOR(vectorclassname, classname)<br>%typemap(in) vectorclassname &, const vectorclassname & {<br> Check_Type($input, T_ARRAY);<br> vectorclassname *vec = new vectorclassname;<br> int len = RARRAY($input)->len;<br> for (int i=0; i!=len; i++) {<br> VALUE inst = rb_ary_entry($input, i);<br> //The following _should_ work but doesn't on HPUX<br> // Check_Type(inst, T_DATA);<br> classname *element = NULL;<br> Data_Get_Struct(inst, classname, element);<br> vec->push_back(element);<br> }<br> $1 = vec;<br>}<br><br>%typemap(freearg) vectorclassname &, const vectorclassname & {<br> delete $1;<br>}<br>%enddef<br></pre>
8163 <p> It is also possible to create a Ruby array from a vector of
8164 static data types: </p>
8171 <pre>%define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)<br>%typemap(out) vectorclassname &, const vectorclassname & {<br> VALUE arr = rb_ary_new2($1->size()); <br> vectorclassname::iterator i = $1->begin(), iend = $1->end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));<br> $result = arr;<br>}<br>%typemap(out) vectorclassname, const vectorclassname {<br> VALUE arr = rb_ary_new2($1.size()); <br> vectorclassname::iterator i = $1.begin(), iend = $1.end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));<br> $result = arr;<br>}<br>%enddef<br></pre>
8189 Note that this is mostly an example of typemaps. If you want to use the
8190 STL with ruby, you are advised to use the standard swig STL library,
8191 which does much more than this. Refer to the section called
8192 the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.<br>
8198 <H2><a name="Ruby_nn65"></a>32.8 Docstring Features</H2>
8202 Using ri and rdoc web pages in Ruby libraries is a common practice.
8203 Given the way that SWIG generates the extensions by default, your users
8204 will normally not get
8205 any documentation for it, even if they run 'rdoc' on the resulting .c
8212 <p>The features described in this section make it easy for you to
8214 rdoc strings to your modules, functions and methods that can then be
8215 read by Ruby's rdoc tool to generate html web pages, ri documentation,
8216 Windows chm file and an .xml description.</p>
8222 <p>rdoc can then be run from a console or shell window on a swig
8223 generated file. </p>
8229 <p>For example, to generate html web pages from a C++ file, you'd
8236 <div class="code shell"><span style="font-family: monospace; font-weight: bold;">
8238 rdoc -E cxx=c -f html file_wrap.cxx</span></div>
8245 generate ri documentation from a c wrap file, you could do:</p>
8251 <div class="code shell"><span style="font-family: monospace; font-weight: bold;">$ rdoc
8252 -r file_wrap.c</span>
8259 <H3><a name="Ruby_nn66"></a>32.8.1 Module docstring</H3>
8263 Ruby allows a docstring at the beginning of the file
8264 before any other statements, and it is typically used to give a
8265 general description of the entire module. SWIG supports this by
8266 setting an option of the <tt>%module</tt> directive. For
8275 <pre>%module(docstring="This is the example module's docstring") example<br></pre>
8288 When you have more than just a line or so then you can retain the easy
8289 readability of the <tt>%module</tt> directive by using a
8298 <pre>%define DOCSTRING<br>"The `XmlResource` class allows program resources defining menus, <br>layout of controls on a panel, etc. to be loaded from an XML file."<br>%enddef<br><br>%module(docstring=DOCSTRING) xrc<br></pre>
8310 <H3><a name="Ruby_nn67"></a>32.8.2 %feature("autodoc")</H3>
8313 <p>Since SWIG does know everything about the function it wraps,
8314 it is possible to generate an rdoc containing the parameter types,
8316 and default values. Since Ruby ships with one of the best documentation
8317 systems of any language, it makes sense to take advantage of it.
8324 <p>SWIG's Ruby module provides support for the "autodoc"
8326 which when attached to a node in the parse tree will cause an rdoc
8328 to be generated in the wrapper file that includes the name of the
8330 names, default values if any, and return type if any. There are also
8331 several options for autodoc controlled by the value given to the
8332 feature, described below.
8339 <H4><a name="Ruby_nn68"></a>32.8.2.1 %feature("autodoc", "0")</H4>
8343 When the "0" option is given then the types of the parameters will
8344 <em>not</em> be included in the autodoc string. For
8346 this function prototype:
8354 <pre>%feature("autodoc", "0");<br>bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);<br></pre>
8367 Then Ruby code like this will be generated:
8374 <div class="targetlang">
8375 <pre>function_name(x, y, foo=nil, bar=nil) -> bool<br> ...<br></pre>
8387 <H4><a name="Ruby_autodoc1"></a>32.8.2.2 %feature("autodoc", "1")</H4>
8391 When the "1" option is used then the parameter types <em>will</em>
8392 be used in the rdoc string. In addition, an attempt is made to
8393 simplify the type name such that it makes more sense to the Ruby
8394 user. Pointer, reference and const info is removed,
8395 <tt>%rename</tt>'s are evaluated, etc. (This is not always
8396 successful, but works most of the time. See the next section for what
8397 to do when it doesn't.) Given the example above, then turning on the
8398 parameter types with the "1" option will result in rdoc code like
8406 <div class="targetlang">
8407 <pre>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool<br> ...<br></pre>
8419 <H4><a name="Ruby_autodoc2"></a>32.8.2.3 %feature("autodoc", "2")</H4>
8423 When the "2" option is used then the parameter types will not
8425 used in the rdoc string. However, they will be listed in full after the
8426 function. Given the example above, then turning on the
8427 parameter types with the "2" option will result in Ruby code like
8435 <H4><a name="Ruby_feature_autodoc3"></a>32.8.2.4 %feature("autodoc", "3")</H4>
8439 When the "3" option is used then the function will be documented using
8440 a combination of "1" and "2" above. Given the example above,
8442 parameter types with the "2" option will result in Ruby code like
8450 <div class="targetlang">
8451 <pre>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool<br><br>Parameters:<br> x - int<br> y - int<br> foo - Foo<br> bar - Bar<br></pre>
8463 <H4><a name="Ruby_nn70"></a>32.8.2.5 %feature("autodoc", "docstring")</H4>
8467 Finally, there are times when the automatically generated autodoc
8468 string will make no sense for a Ruby programmer, particularly when a
8469 typemap is involved. So if you give an explicit value for the autodoc
8470 feature then that string will be used in place of the automatically
8471 generated string. For example:
8479 <pre>%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;<br>void GetPosition(int* OUTPUT, int* OUTPUT);<br></pre>
8491 <H3><a name="Ruby_nn71"></a>32.8.3 %feature("docstring")</H3>
8495 In addition to the autodoc strings described above, you can also
8496 attach any arbitrary descriptive text to a node in the parse tree with
8497 the "docstring" feature. When the proxy module is generated then any
8498 docstring associated with classes, function or methods are output.
8499 If an item already has an autodoc string then it is combined with the
8500 docstring and they are output together. </p>
8506 <H2><a name="Ruby_nn53"></a>32.9 Advanced Topics</H2>
8509 <H3><a name="Ruby_nn54"></a>32.9.1 Operator overloading</H3>
8512 <p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
8513 or <tt>%rename</tt> commands in SWIG and the following
8514 operator names (derived from Python): </p>
8520 <div class="code diagram">
8521 <table style="width: 100%; font-family: monospace;" border="1" cellpadding="2" cellspacing="2" summary="operator names">
8539 <td><b> General</b></td>
8653 <td>__nonzero__ </td>
8695 <td><b> Callable</b></td>
8755 <td><b> Collection</b></td>
8797 <td>__getitem__ </td>
8821 <td>__setitem__ </td>
8863 <td><b> Numeric</b></td>
9007 <td>__divmod__ </td>
9055 <td>__lshift__ </td>
9079 <td>__rshift__ </td>
9253 <td>__invert__ </td>
9325 <td>__coerce__ </td>
9367 <td><b>Additions in 1.3.13 </b></td>
9516 <p> Note that although SWIG supports the <tt>__eq__</tt>
9517 magic method name for defining an equivalence operator, there is no
9518 separate method for handling <i>inequality</i> since Ruby
9519 parses the expression <i>a != b</i> as <i>!(a == b)</i>.
9526 <H3><a name="Ruby_nn55"></a>32.9.2 Creating Multi-Module Packages</H3>
9529 <p> The chapter on <a href="Modules.html">Working
9530 with Modules</a> discusses the basics of creating multi-module
9531 extensions with SWIG, and in particular the considerations for sharing
9532 runtime type information among the different modules. </p>
9538 <p>As an example, consider one module's interface file (<tt>shape.i</tt>)
9539 that defines our base class: </p>
9546 <pre>%module shape<br><br>%{<br>#include "Shape.h"<br>%}<br><br>class Shape {<br>protected:<br> double xpos;<br> double ypos;<br>protected:<br> Shape(double x, double y);<br>public:<br> double getX() const;<br> double getY() const;<br>};<br></pre>
9558 <p> We also have a separate interface file (<tt>circle.i</tt>)
9559 that defines a derived class: </p>
9566 <pre>%module circle<br><br>%{<br>#include "Shape.h"<br>#include "Circle.h"<br>%}<br><br>// Import the base class definition from Shape module<br>%import shape.i<br><br>class Circle : public Shape {<br>protected:<br> double radius;<br>public:<br> Circle(double x, double y, double r);<br> double getRadius() const;<br>};<br></pre>
9578 <p> We'll start by building the <b>Shape</b>
9579 extension module: </p>
9585 <div class="code shell">
9586 <pre>$ <b>swig -c++ -ruby shape.i</b>
9599 <p> SWIG generates a wrapper file named <tt>shape_wrap.cxx</tt>.
9600 To compile this into a dynamically loadable extension for Ruby, prepare
9601 an <tt>extconf.rb</tt> script using this template: </p>
9607 <div class="code targetlang">
9608 <pre>require 'mkmf'<br><br># Since the SWIG runtime support library for Ruby<br># depends on the Ruby library, make sure it's in the list<br># of libraries.<br>$libs = append_library($libs, Config::CONFIG['RUBY_INSTALL_NAME'])<br><br># Create the makefile<br>create_makefile('shape')<br></pre>
9620 <p> Run this script to create a <tt>Makefile</tt>
9621 and then type <tt>make</tt> to build the shared library: </p>
9627 <div class="code targetlang">
9628 <pre>$ <b>ruby extconf.rb</b><br>creating Makefile<br>$ <b>make</b><br>g++ -fPIC -g -O2 -I. -I/usr/local/lib/ruby/1.7/i686-linux \<br>-I. -c shape_wrap.cxx<br>gcc -shared -L/usr/local/lib -o shape.so shape_wrap.o -L. \<br>-lruby -lruby -lc<br></pre>
9640 <p> Note that depending on your installation, the outputs may be
9641 slightly different; these outputs are those for a Linux-based
9642 development environment. The end result should be a shared library
9643 (here, <tt>shape.so</tt>) containing the extension module
9644 code. Now repeat this process in a separate directory for the <b>Circle</b>
9657 <li> Run SWIG to generate the wrapper code (<tt>circle_wrap.cxx</tt>);
9664 <li> Write an <tt>extconf.rb</tt> script that your
9665 end-users can use to create a platform-specific <tt>Makefile</tt>
9666 for the extension; </li>
9672 <li> Build the shared library for this extension by typing <tt>make</tt>.
9685 <p> Once you've built both of these extension modules, you can
9686 test them interactively in IRB to confirm that the <tt>Shape</tt>
9687 and <tt>Circle</tt> modules are properly loaded and
9694 <div class="code targetlang">
9695 <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'shape'</b><br>true<br>irb(main):002:0> <b>require 'circle'</b><br>true<br>irb(main):003:0> <b>c = Circle::Circle.new(5, 5, 20)</b><br>#<Circle::Circle:0xa097208><br>irb(main):004:0> <b>c.kind_of? Shape::Shape</b><br>true<br>irb(main):005:0> <b>c.getX()</b><br>5.0<br></pre>
9707 <H3><a name="Ruby_nn56"></a>32.9.3 Specifying Mixin Modules</H3>
9710 <p> The Ruby language doesn't support multiple inheritance, but
9711 it does allow you to mix one or more modules into a class using Ruby's <tt>include</tt>
9712 method. For example, if you have a Ruby class that defines an <em>each</em>
9713 instance method, e.g. </p>
9719 <div class="code targetlang">
9720 <pre>class Set<br> def initialize<br> @members = []<br> end<br> <br> def each<br> @members.each { |m| yield m }<br> end<br>end<br></pre>
9732 <p> then you can mix-in Ruby's <tt>Enumerable</tt>
9733 module to easily add a lot of functionality to your class: </p>
9739 <div class="code targetlang">
9740 <pre>class Set<br> <b>include Enumerable</b><br>def initialize<br>@members = []<br>end<br>def each<br>@members.each { |m| yield m }<br>end<br>end<br></pre>
9752 <p> To get the same benefit for your SWIG-wrapped classes, you
9753 can use the <tt>%mixin</tt> directive to specify the names
9754 of one or more modules that should be mixed-in to a class. For the
9755 above example, the SWIG interface specification might look like this: </p>
9762 <pre>%mixin Set "Enumerable";<br><br>class Set {<br>public:<br> // Constructor<br> Set();<br> <br> // Iterates through set members<br> void each();<br>};<br></pre>
9774 <p> Multiple modules can be mixed into a class by providing a
9775 comma-separated list of module names to the <tt>%mixin</tt>
9776 directive, e.g. </p>
9783 <pre>%mixin Set "Fee,Fi,Fo,Fum";</pre>
9795 <p> Note that the <tt>%mixin</tt> directive is
9796 implemented using SWIG's "features" mechanism and so the same name
9797 matching rules used for other kinds of features apply (see the chapter
9798 on <a href="Customization.html#Customization">"Customization
9799 Features"</a>) for more details). </p>
9805 <H2><a name="Ruby_nn57"></a>32.10 Memory Management</H2>
9808 <p>One of the most common issues in generating SWIG bindings for
9809 Ruby is proper memory management. The key to proper memory management
9810 is clearly defining whether a wrapper Ruby object owns the underlying C
9811 struct or C++ class. There are two possibilities:</p>
9823 <li> The Ruby object is responsible for freeing the C struct or
9830 <li> The Ruby object should not free the C struct or C++ object
9831 because it will be freed by the underlying C or C++ code</li>
9843 <p>To complicate matters, object ownership may transfer from Ruby
9844 to C++ (or vice versa) depending on what function or methods are
9845 invoked. Clearly, developing a SWIG wrapper requires a thorough
9846 understanding of how the underlying library manages memory.</p>
9852 <H3><a name="Ruby_nn58"></a>32.10.1 Mark and Sweep Garbage Collector </H3>
9855 <p>Ruby uses a mark and sweep garbage collector. When the garbage
9856 collector runs, it finds all the "root" objects, including local
9857 variables, global variables, global constants, hardware registers and
9858 the C stack. For each root object, the garbage collector sets its mark
9859 flag to true and calls <tt>rb_gc_mark</tt> on the object.
9860 The job of <tt>rb_gc_mark</tt> is to recursively mark all
9861 the objects that a Ruby object has a reference to (ignoring those
9862 objects that have already been marked). Those objects, in turn, may
9863 reference other objects. This process will continue until all active
9864 objects have been "marked." After the mark phase comes the sweep phase.
9865 In the sweep phase, all objects that have not been marked will be
9866 garbage collected. For more information about the Ruby garbage
9867 collector please refer to <a href="http://rubygarden.org/ruby/ruby?GCAndExtensions"> <span style="text-decoration: underline;">http://rubygarden.org/ruby/ruby?GCAndExtensions</span></a>.</p>
9873 <p>The Ruby C/API provides extension developers two hooks into
9874 the garbage collector - a "mark" function and a "sweep" function. By
9875 default these functions are set to NULL.</p>
9881 <p>If a C struct or C++ class references any other Ruby objects,
9882 then it must provide a "mark" function. The "mark" function should
9883 identify any referenced Ruby objects by calling the rb_gc_mark function
9884 for each one. Unsurprisingly, this function will be called by the Ruby
9885 garbage during the "mark" phase.</p>
9891 <p>During the sweep phase, Ruby destroys any unused objects. If
9892 any memory has been allocated in creating the underlying C struct or
9893 C++ struct, then a "free" function must be defined that deallocates
9900 <H3><a name="Ruby_nn59"></a>32.10.2 Object Ownership</H3>
9903 <p>As described above, memory management depends on clearly
9904 defining who is responsible for freeing the underlying C struct or C++
9905 class. If the Ruby object is responsible for freeing the C++ object,
9906 then a "free" function must be registered for the object. If the Ruby
9907 object is not responsible for freeing the underlying memory, then a
9908 "free" function must not be registered for the object.</p>
9914 <p>For the most part, SWIG takes care of memory management
9915 issues. The rules it uses are:</p>
9927 <li> When calling a C++ object's constructor from Ruby, SWIG
9928 will assign a "free" function thereby making the Ruby object
9929 responsible for freeing the C++ object</li>
9935 <li> When calling a C++ member function that returns a pointer,
9936 SWIG will not assign a "free" function thereby making the underlying
9937 library responsible for freeing the object.</li>
9949 <p>To make this clearer, let's look at an example. Assume we have
9950 a Foo and a Bar class. </p>
9957 <pre>/* File "RubyOwernshipExample.h" */<br><br>class Foo<br>{<br>public:<br> Foo() {}<br> ~Foo() {}<br>};<br><br>class Bar<br>{<br> Foo *foo_;<br>public:<br> Bar(): foo_(new Foo) {}<br> ~Bar() { delete foo_; }<br> Foo* get_foo() { return foo_; }<br> Foo* get_new_foo() { return new Foo; }<br> void set_foo(Foo *foo) { delete foo_; foo_ = foo; }<br>};<br><br></pre>
9969 <p>First, consider this Ruby code: </p>
9975 <div class="code targetlang">
9976 <pre>foo = Foo.new</pre>
9988 <p>In this case, the Ruby code calls the underlying <tt>Foo</tt>
9989 C++ constructor, thus creating a new <tt>foo</tt> object.
9990 By default, SWIG will assign the new Ruby object a "free" function.
9991 When the Ruby object is garbage collected, the "free" function will be
9992 called. It in turn will call <tt>Foo's</tt> destructor.</p>
9998 <p>Next, consider this code: </p>
10004 <div class="code targetlang">
10005 <pre>bar = Bar.new<br>foo = bar.get_foo()</pre>
10017 <p>In this case, the Ruby code calls a C++ member function, <tt>get_foo</tt>.
10018 By default, SWIG will not assign the Ruby object a "free" function.
10019 Thus, when the Ruby object is garbage collected the underlying C++ <tt>foo</tt>
10020 object is not affected.</p>
10026 <p>Unfortunately, the real world is not as simple as the examples
10027 above. For example:</p>
10033 <div class="code targetlang">
10034 <pre>bar = Bar.new<br>foo = bar.get_new_foo()</pre>
10046 <p>In this case, the default SWIG behavior for calling member
10047 functions is incorrect. The Ruby object should assume ownership of the
10048 returned object. This can be done by using the %newobject directive.
10049 See <a href="file:///d:/msys/1.0/src/SWIG/Doc/Manual/Customization.html#ownership">
10050 Object ownership and %newobject</a> for more information. </p>
10056 <p>The SWIG default mappings are also incorrect in this case:</p>
10062 <div class="code targetlang">
10063 <pre>foo = Foo.new<br>bar = Bar.new<br>bar.set_foo(foo)</pre>
10075 <p>Without modification, this code will cause a segmentation
10076 fault. When the Ruby <tt>foo</tt> object goes out of
10077 scope, it will free the underlying C++ <tt>foo</tt>
10078 object. However, when the Ruby bar object goes out of scope, it will
10079 call the C++ bar destructor which will also free the C++ <tt>foo</tt>
10080 object. The problem is that object ownership is transferred from the
10081 Ruby object to the C++ object when the <tt>set_foo</tt>
10082 method is called. This can be done by using the special DISOWN type
10083 map, which was added to the Ruby bindings in SWIG-1.3.26.</p>
10089 <p>Thus, a correct SWIG interface file correct mapping for these
10097 <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>
10115 <p> This code can be seen in swig/examples/ruby/tracking.</p>
10127 <H3><a name="Ruby_nn60"></a>32.10.3 Object Tracking</H3>
10130 <p>The remaining parts of this section will use the class library
10131 shown below to illustrate different memory management techniques. The
10132 class library models a zoo and the animals it contains. </p>
10139 <pre>%module zoo<br><br>%{<br>#include <string><br>#include <vector><br><br>#include "zoo.h"<br>%}<br><br>class Animal<br>{<br>private:<br> typedef std::vector<Animal*> AnimalsType;<br> typedef AnimalsType::iterator IterType;<br>protected:<br> AnimalsType animals;<br>protected:<br> std::string name_;<br>public:<br> // Construct an animal with this name<br> Animal(const char* name) : name_(name) {}<br> <br> // Return the animal's name<br> const char* get_name() const { return name.c_str(); }<br>};<br><br>class Zoo<br>{<br>protected:<br> std::vector<animal *=""> animals;<br> <br>public:<br> // Construct an empty zoo<br> Zoo() {}<br> <br> /* Create a new animal. */<br> static Animal* Zoo::create_animal(const char* name)<br> {<br> return new Animal(name);<br> }<br><br> // Add a new animal to the zoo<br> void add_animal(Animal* animal) {<br> animals.push_back(animal); <br> }<br><br> Animal* remove_animal(size_t i) {<br> Animal* result = this->animals[i];<br> IterType iter = this->animals.begin();<br> std::advance(iter, i);<br> this->animals.erase(iter);<br><br> return result;<br> }<br> <br> // Return the number of animals in the zoo<br> size_t get_num_animals() const {<br> return animals.size(); <br> }<br> <br> // Return a pointer to the ith animal<br> Animal* get_animal(size_t i) const {<br> return animals[i]; <br> }<br>};<br><br></pre>
10151 <p>Let's say you SWIG this code and then run IRB:<br>
10163 <div class="code targetlang">
10164 <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>
10176 <p>Pay particular attention to the code <tt>tiger1.equal?(tiger2)</tt>.
10177 Note that the two Ruby objects are not the same - but they reference
10178 the same underlying C++ object. This can cause problems. For example:<br>
10190 <div class="code targetlang">
10191 <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>
10203 <p>After the the garbage collector runs, as a result of our call
10204 to <tt>GC.start</tt>, calling<tt>tiger2.get_name()</tt>
10205 causes a segmentation fault. The problem is that when <tt>tiger1</tt>
10206 is garbage collected, it frees the underlying C++ object. Thus, when <tt>tiger2</tt>
10207 calls the <tt>get_name()</tt> method it invokes it on a
10208 destroyed object.</p>
10214 <p>This problem can be avoided if SWIG enforces a one-to-one
10215 mapping between Ruby objects and C++ classes. This can be done via the
10216 use of the <tt>%trackobjects</tt> functionality available
10217 in SWIG-1.3.26. and later.</p>
10223 <p>When the <tt>%trackobjects</tt> is turned on,
10224 SWIG automatically keeps track of mappings between C++ objects and Ruby
10225 objects. Note that enabling object tracking causes a slight performance
10226 degradation. Test results show this degradation to be about 3% to 5%
10227 when creating and destroying 100,000 animals in a row.</p>
10233 <p>Since <tt>%trackobjects</tt> is implemented as a <tt>%feature</tt>,
10234 it uses the same name matching rules as other kinds of features (see
10235 the chapter on <a href="Customization.html#Customization">
10236 "Customization Features"</a>) . Thus it can be applied on a
10237 class-by-class basis if needed. To fix the example above:</p>
10250 <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>
10262 <p>When this code runs we see:<br>
10280 <div class="code targetlang">
10281 <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>
10293 <p>For those who are interested, object tracking is implemented
10294 by storing Ruby objects in a hash table and keying them on C++
10295 pointers. The underlying API is:<br>
10308 <pre>static void SWIG_RubyAddTracking(void* ptr, VALUE object);<br>static VALUE SWIG_RubyInstanceFor(void* ptr) ;<br>static void SWIG_RubyRemoveTracking(void* ptr);<br>static void SWIG_RubyUnlinkObjects(void* ptr);</pre>
10320 <p>When an object is created, SWIG will automatically call the <tt>SWIG_RubyAddTracking</tt>
10321 method. Similarly, when an object is deleted, SWIG will call the <tt>SWIG_RubyRemoveTracking</tt>.
10322 When an object is returned to Ruby from C++, SWIG will use the <tt>SWIG_RubyInstanceFor</tt>
10323 method to ensure a one-to-one mapping from Ruby to C++ objects. Last,
10324 the <tt>RubyUnlinkObjects</tt> method unlinks a Ruby
10325 object from its underlying C++ object.</p>
10331 <p>In general, you will only need to use the <tt>SWIG_RubyInstanceFor</tt>,
10332 which is required for implementing mark functions as shown below.
10333 However, if you implement your own free functions (see below) you may
10334 also have to call the<tt> SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt>
10341 <H3><a name="Ruby_nn61"></a>32.10.4 Mark Functions</H3>
10344 <p>With a bit more testing, we see that our class library still
10345 has problems. For example:<br>
10357 <div class="targetlang">
10358 <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>
10370 <p>The problem is that Ruby does not know that the <tt>zoo</tt>
10371 object contains a reference to a Ruby object. Thus, when Ruby garbage
10372 collects <span style="font-family: monospace;">tiger1</span>
10373 it frees the underlying C++ object.</p>
10379 <p>This can be fixed by implementing a <tt>mark</tt>
10380 function as described above in the <a href="Ruby.html#Ruby_nn52">Mark
10381 and Sweep Garbage Collector</a> section. You can specify a mark
10382 function by using the <tt>%markfunc</tt> directive. Since
10383 the <tt>%markfunc</tt> directive is implemented using
10384 SWIG's' "features" mechanism it uses the same name matching rules as
10385 other kinds of features (see the chapter on <a href="Customization.html#Customization">"Customization
10386 Features"</a> for more details). </p>
10392 <p>A <tt>mark</tt> function takes a single argument,
10393 which is a pointer to the C++ object being marked; it should, in turn,
10394 call <tt>rb_gc_mark()</tt> for any instances that are
10395 reachable from the current object. The mark function for our <tt>
10396 Zoo</tt> class should therefore loop over all of the C++ animal
10397 objects in the zoo object, look up their Ruby object equivalent, and
10398 then call <tt>rb_gc_mark()</tt>. One possible
10399 implementation is:</p>
10406 <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>
10418 <p> Note the <tt>mark</tt> function is dependent on
10419 the <tt>SWIG_RUBY_InstanceFor</tt> method, and thus
10420 requires that <tt>%trackobjects</tt> is enabled. For more
10421 information, please refer to the track_object.i test case in the SWIG
10428 <p>When this code is compiled we now see:</p>
10434 <div class="targetlang">
10435 <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>
10453 <p>This code can be seen in swig/examples/ruby/mark_function.</p>
10459 <H3><a name="Ruby_nn62"></a>32.10.5 Free Functions</H3>
10462 <p>By default, SWIG creates a "free" function that is called when
10463 a Ruby object is garbage collected. The free function simply calls the
10464 C++ object's destructor.</p>
10470 <p>However, sometimes an appropriate destructor does not exist or
10471 special processing needs to be performed before the destructor is
10472 called. Therefore, SWIG allows you to manually specify a "free"
10473 function via the use of the <tt>%freefunc</tt> directive.
10474 The <tt>%freefunc</tt> directive is implemented using
10475 SWIG's' "features" mechanism and so the same name matching rules used
10476 for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
10477 Features"</a>) for more details).</p>
10483 <p>IMPORTANT ! - If you define your own free function, then you
10484 must ensure that you call the underlying C++ object's destructor. In
10485 addition, if object tracking is activated for the object's class, you
10486 must also call the <tt>SWIG_RubyRemoveTracking</tt>
10487 function (of course call this before you destroy the C++ object). Note
10488 that it is harmless to call this method if object tracking if off so it
10489 is advised to always call it.</p>
10495 <p>Note there is a subtle interaction between object ownership
10496 and free functions. A custom defined free function will only be called
10497 if the Ruby object owns the underlying C++ object. This also to Ruby
10498 objects which are created, but then transfer ownership to C++ objects
10499 via the use of the <tt>disown</tt> typemap described
10506 <p>To show how to use the <tt>%freefunc</tt>
10507 directive, let's slightly change our example. Assume that the zoo
10508 object is responsible for freeing animal that it contains. This means
10509 that the <span style="font-family: monospace;">Zoo::add_animal</span>
10510 function should be marked with a <span style="font-family: monospace;">DISOWN</span> typemap
10511 and the destructor should be updated as below::</p>
10518 <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>
10530 <p>When we use these objects in IRB we see:</p>
10536 <div class="code targetlang">
10537 <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>
10549 <p>The error happens because the C++ <tt>animal</tt>
10550 object is freed when the <tt>zoo</tt> object is freed.
10551 Although this error is unavoidable, we can at least prevent the
10552 segmentation fault. To do this requires enabling object tracking and
10553 implementing a custom free function that calls the <tt>SWIG_RubyUnlinkObjects</tt>
10554 function for each animal object that is destroyed. The <tt>SWIG_RubyUnlinkObjects</tt>
10555 function notifies SWIG that a Ruby object's underlying C++ object is no
10556 longer valid. Once notified, SWIG will intercept any calls from the
10557 existing Ruby object to the destroyed C++ object and raise an exception.<br>
10570 <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>
10582 <p>Now when we use these objects in IRB we see:</p>
10588 <div class="code targetlang">
10589 <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>
10601 <p>Notice that SWIG can now detect the underlying C++ object has
10602 been freed, and thus raises a runtime exception.</p>
10608 <p>This code can be seen in swig/examples/ruby/free_function.</p>
10614 <H3><a name="Ruby_nn63"></a>32.10.6 Embedded Ruby and the C++ Stack</H3>
10617 <p>As has been said, the Ruby GC runs and marks objects before
10619 sweep phase. When the garbage collector is called, it will
10621 try to mark any Ruby objects (VALUE) it finds in the machine registers
10622 and in the C++ stack.</p>
10628 <p>The stack is basically the history of the functions that have
10630 called and also contains local variables, such as the ones you define
10631 whenever you do inside a function:</p>
10637 <div class="diagram">VALUE obj; </div>
10643 <p>For ruby to determine where its stack space begins, during
10644 initialization a normal Ruby interpreter will call the ruby_init()
10645 function which in turn will call a function called Init_stack or
10646 similar. This function will store a pointer to the location
10648 the stack points at at that point in time.</p>
10654 <p>ruby_init() is presumed to always be called within the main()
10655 function of your program and whenever the GC is called, ruby will
10656 assume that the memory between the current location in memory and the
10657 pointer that was stored previously represents the stack, which may
10658 contain local (and temporary) VALUE ruby objects. Ruby will
10659 then be careful not to remove any of those objects in that location.</p>
10665 <p>So far so good. For a normal Ruby session, all the
10667 completely transparent and magic to the extensions developer.
10674 <p>However, with an embedded Ruby, it may not always be possible
10676 modify main() to make sure ruby_init() is called there. As
10678 ruby_init() will likely end up being called from within some other
10679 function. This can lead Ruby to measure incorrectly where the
10680 stack begins and can result in Ruby incorrectly collecting
10682 temporary VALUE objects that are created once another function
10684 called. The end result: random crashes and segmentation
10691 <p>This problem will often be seen in director functions that are
10692 used for callbacks, for example. </p>
10698 <p>To solve the problem, SWIG can now generate code with director
10699 functions containing the optional macros SWIG_INIT_STACK and
10700 SWIG_RELEASE_STACK. These macros will try to force Ruby to
10701 reinitiliaze the beginning of the stack the first time a
10703 function is called. This will lead Ruby to measure and not
10704 collect any VALUE objects defined from that point on. </p>
10710 <p>To mark functions to either reset the ruby stack or not, you
10717 <div class="indent code" style="font-family: monospace;">%initstack
10718 Class::memberfunction; // only re-init the stack
10719 in this director method<br>
10725 %ignorestack Class::memberfunction; // do not re-init the
10726 stack in this director method<br>
10732 %initstack Class;
10733 // init the stack on all
10734 the methods of this class<br>
10740 %initstack; // all director functions will
10741 re-init the stack</div>
projects / external / swig.git / blob