ruby2cext 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/Changelog +27 -0
- data/README +44 -0
- data/bin/rb2cx +178 -0
- data/doc/eval2c.html +281 -0
- data/doc/index.html +218 -0
- data/doc/limitations.html +581 -0
- data/doc/optimizations.html +222 -0
- data/doc/rb2cx.html +151 -0
- data/doc/style.css +27 -0
- data/lib/ruby2cext/c_function.rb +621 -0
- data/lib/ruby2cext/common_node_comp.rb +1409 -0
- data/lib/ruby2cext/compiler.rb +242 -0
- data/lib/ruby2cext/error.rb +15 -0
- data/lib/ruby2cext/eval2c.rb +129 -0
- data/lib/ruby2cext/parser.rb +36 -0
- data/lib/ruby2cext/plugin.rb +24 -0
- data/lib/ruby2cext/plugins/builtin_methods.rb +820 -0
- data/lib/ruby2cext/plugins/case_optimize.rb +105 -0
- data/lib/ruby2cext/plugins/const_cache.rb +38 -0
- data/lib/ruby2cext/plugins/inline_methods.rb +69 -0
- data/lib/ruby2cext/plugins/require_include.rb +71 -0
- data/lib/ruby2cext/plugins/warnings.rb +123 -0
- data/lib/ruby2cext/scopes.rb +227 -0
- data/lib/ruby2cext/str_to_c_strlit.rb +12 -0
- data/lib/ruby2cext/tools.rb +84 -0
- data/lib/ruby2cext/version.rb +22 -0
- data/testfiles/bench.rb +116 -0
- data/testfiles/eval2c/test_eval2c.rb +37 -0
- data/testfiles/test.rb +615 -0
- data/testfiles/vmode_test.rb +73 -0
- data/testfiles/warn_test.rb +35 -0
- metadata +87 -0
data/doc/index.html
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<title>Ruby2CExtension</title>
|
|
5
|
+
<link href="style.css" media="all" rel="Stylesheet" type="text/css">
|
|
6
|
+
</head>
|
|
7
|
+
<body>
|
|
8
|
+
<h1>Ruby2CExtension</h1>
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
<p>Ruby2CExtension is a Ruby to C extension translator/compiler. It takes any
|
|
12
|
+
Ruby source file, parses it using Ruby’s builtin parser and then translates
|
|
13
|
+
the abstract syntax tree into “equivalent” C extension code.</p>
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
<p>Let’s say you have a Ruby file <code>foo.rb</code>. To translate it to a C extension and
|
|
17
|
+
then compile it, just run:</p>
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
<pre><code>rb2cx foo.rb
|
|
21
|
+
</code></pre>
|
|
22
|
+
|
|
23
|
+
<p>This will produce the files <code>foo.c</code> and <code>foo.so</code> (on Linux). <code>foo.c</code> is the
|
|
24
|
+
generated C extension source code and <code>foo.so</code> is the compiled C extension.</p>
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
<p>If <code>foo.rb</code> is a library, you can just rename, move or delete <code>foo.rb</code> (only
|
|
28
|
+
if you have a backup, of course) and your Ruby program will just use <code>foo.so</code>
|
|
29
|
+
instead.</p>
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
<p>If <code>foo.rb</code> is a script, then it isn’t possible to just run <code>foo.so</code>, because
|
|
33
|
+
Ruby does not support running C extensions directly, but you can do this:</p>
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
<pre><code>ruby -r foo.so -e ""
|
|
37
|
+
</code></pre>
|
|
38
|
+
|
|
39
|
+
<p>which should produce the same output as</p>
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
<pre><code>ruby -r foo.rb -e ""
|
|
43
|
+
</code></pre>
|
|
44
|
+
|
|
45
|
+
<p>Sections: <a href="#section1">Why?</a>, <a href="#section2">Requirements</a>, <a href="#section3">Download</a>, <a href="#section4">Installation</a>, <a href="#section5">Features</a>, <a href="#section6">Usage</a>, <a href="#section7">Feedback</a>, <a href="#section8">Thanks</a>, <a href="#section9">License</a>.</p>
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
<h2 id="section1">Why?</h2>
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
<p>Well, like everybody else I wanted a faster Ruby and I also wanted to learn
|
|
52
|
+
about Ruby’s internals, so I thought translating Ruby to C might be worth a
|
|
53
|
+
try…</p>
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
<p>The initial results were not as good as I had hoped, but they weren’t bad
|
|
57
|
+
either: without optimizations the generated C extension is practically never
|
|
58
|
+
slower than the Ruby code and I found cases where it is more than twice as
|
|
59
|
+
fast, usually it is somewhere in between. But, starting from version 0.2.0,
|
|
60
|
+
Ruby2CExtension can use <a href="optimizations.html">optimizations</a> to <strong>significantly
|
|
61
|
+
speedup</strong> execution in many cases (<strong>sometimes more than five times faster</strong> than
|
|
62
|
+
normal Ruby).</p>
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
<p>Of course Ruby2CExtension can also be used as an obfuscator for Ruby code,
|
|
66
|
+
though this was not my main motivation.</p>
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
<h2 id="section2">Requirements</h2>
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
<p>Ruby2CExtension is developed for the Ruby 1.8 versions (only 1.8.4 and later).
|
|
73
|
+
It is currently tested with <strong>Ruby 1.8.4, 1.8.5 and 1.8.6</strong>. Only those versions
|
|
74
|
+
should be used, because Ruby2CExtension depends on Ruby internals that can
|
|
75
|
+
change between Ruby versions. If an untested Ruby version is used, then there
|
|
76
|
+
will be a warning. It might work for later 1.8 versions, but it definitely
|
|
77
|
+
won’t work with Ruby 1.9.</p>
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
<p>Ruby2CExtension requires RubyNode to access Ruby’s node trees (the <span class="caps">AST</span>).
|
|
81
|
+
RubyNode is available at
|
|
82
|
+
<a href="http://rubynode.rubyforge.org/">http://rubynode.rubyforge.org/</a>.</p>
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
<p>Ruby2CExtension is pure Ruby code, so it should work on all platforms that
|
|
86
|
+
Ruby supports, but it is currently only tested on Linux. There might be
|
|
87
|
+
problems with the automatic compilation of the generated C code on some
|
|
88
|
+
platforms (in particular on Windows).</p>
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
<h2 id="section3">Download</h2>
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
<ul>
|
|
95
|
+
<li><a href="http://rubyforge.org/projects/ruby2cext/">Project page</a></li>
|
|
96
|
+
<li><a href="http://rubyforge.org/frs/?group_id=1799">Download</a></li>
|
|
97
|
+
</ul>
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
<h2 id="section4">Installation</h2>
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
<p>Just run (as root):</p>
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
<pre><code>gem install ruby2cext
|
|
107
|
+
</code></pre>
|
|
108
|
+
|
|
109
|
+
<p>Or if you do not use the gem:</p>
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
<pre><code>ruby setup.rb
|
|
113
|
+
</code></pre>
|
|
114
|
+
|
|
115
|
+
<p>This will install Ruby2CExtension to the default locations. Optionally you
|
|
116
|
+
can supply some options to <code>setup.rb</code> to customize the installation (see
|
|
117
|
+
<code>"ruby setup.rb --help"</code>).</p>
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
<h2 id="section5">Features</h2>
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
<p>Ruby2CExtension supports a very large subset of Ruby’s features:</p>
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
<ul>
|
|
127
|
+
<li>all the basics (classes, methods, ...)</li>
|
|
128
|
+
<li>blocks, closures</li>
|
|
129
|
+
<li><code>instance_eval</code>, <code>define_method</code>, ... (only when the block is given directly)</li>
|
|
130
|
+
<li>correct constant and class variable lookup</li>
|
|
131
|
+
<li><code>raise</code>, <code>rescue</code>, <code>retry</code>, <code>ensure</code></li>
|
|
132
|
+
<li>...</li>
|
|
133
|
+
</ul>
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
<p>Things that (currently) don’t work:</p>
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
<ul>
|
|
140
|
+
<li><code>break</code> with a value from inside a block</li>
|
|
141
|
+
<li><code>return</code> from inside a block</li>
|
|
142
|
+
<li><code>return</code>, <code>break</code>, <code>next</code>, <code>redo</code> inside <code>ensure</code></li>
|
|
143
|
+
<li><code>defined?</code> is not implemented for all cases</li>
|
|
144
|
+
<li>block pass (passing a proc as block to a method) works, but only through a
|
|
145
|
+
hack and it doesn’t work (correctly) for things like <code>instance_eval</code></li>
|
|
146
|
+
</ul>
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
<p>Some of the above things might be fixed in future versions.</p>
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
<p>Things that don’t work as expected and probably never will:</p>
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
<ul>
|
|
156
|
+
<li>methods like <code>local_variables</code>, that depend on a Ruby <span class="caps">SCOPE</span></li>
|
|
157
|
+
<li>interoperability with <code>eval(str)</code> and similar methods that parse a string and
|
|
158
|
+
eval it; these methods work, but they might not behave as expected (i.e.
|
|
159
|
+
access to local variables and similar things won’t work, see above)</li>
|
|
160
|
+
<li><code>callcc</code> works but might behave strangely (in particular local variables
|
|
161
|
+
might behave wrong)</li>
|
|
162
|
+
<li>some more things, please see <a href="limitations.html">limitations</a></li>
|
|
163
|
+
</ul>
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
<p>Ruby2CExtension will translate and compile Ruby files using one or more of the
|
|
167
|
+
above functionalities without a warning (for some cases warnings can be
|
|
168
|
+
enabled, see <a href="rb2cx.html">rb2cx</a>), so if your Ruby code uses such
|
|
169
|
+
functionality, please verify that the compiled C extension works as expected.</p>
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
<p>For more details please see <a href="limitations.html">limitations</a>.</p>
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
<h2 id="section6">Usage</h2>
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
<p>There are two “interfaces” to use Ruby2CExtension:</p>
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
<ul>
|
|
182
|
+
<li><a href="rb2cx.html">rb2cx</a>: the command line compiler.</li>
|
|
183
|
+
<li><a href="eval2c.html">Eval2C</a>: a class that allows dynamic compilation of Ruby code
|
|
184
|
+
at runtime.</li>
|
|
185
|
+
</ul>
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
<p>Please see their respective documentations.</p>
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
<h2 id="section7">Feedback</h2>
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
<p>If you find a bug, think that something doesn’t work as it should or have
|
|
195
|
+
other suggestions, then please don’t hesitate to <a href="mailto:dbatml@remove_nospam.gmx.de">contact
|
|
196
|
+
me</a> and tell me about it.</p>
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
<p>I am also interested to know if Ruby2CExtension works under Windows (or other
|
|
200
|
+
non Linux platforms).</p>
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
<h2 id="section8">Thanks</h2>
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
<p>I would like to thank Eric Mahurin for various good ideas for
|
|
207
|
+
<a href="optimizations.html">optimizations</a> and for inspiring <a href="eval2c.html">Eval2C</a>.</p>
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
<h2 id="section9">License</h2>
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
<p>Copyright 2006-2007 <a href="mailto:dbatml@remove_nospam.gmx.de">Dominik Bathon</a>.</p>
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
<p>Ruby2CExtension is licensed under the same terms as Ruby.</p>
|
|
217
|
+
</body>
|
|
218
|
+
</html>
|
|
@@ -0,0 +1,581 @@
|
|
|
1
|
+
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<title>Ruby2CExtension Limitations</title>
|
|
5
|
+
<link href="style.css" media="all" rel="Stylesheet" type="text/css">
|
|
6
|
+
</head>
|
|
7
|
+
<body>
|
|
8
|
+
<h1>Ruby2CExtension Limitations</h1>
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
<p>Ruby2CExtension has some limitations. Some things do not work “by design”
|
|
12
|
+
other things don’t work because they are not (yet) implemented.</p>
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
<p>Generally Ruby2CExtension tries to match Ruby’s semantics as close as
|
|
16
|
+
possible, so if a Ruby file doesn’t fail to compile and doesn’t have any of
|
|
17
|
+
the issues described below, then the compiled C extension should just work and
|
|
18
|
+
behave exactly as the Ruby code would.</p>
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
<p>Sections: <a href="#section1">Warnings and Exceptions</a>, <a href="#section2">C Extension Limitations</a>, <a href="#section3">Arity</a>, <a href="#section4">Continuations</a>, <a href="#section5">Scope</a>, <a href="#section6">Vmode</a>, <a href="#section7">Cref</a>, <a href="#section8">Block Pass</a>, <a href="#section9">Block Argument Semantics</a>, <a href="#section10"><code>super</code> with implicit arguments and optional arguments</a>, <a href="#section11">Not Supported Features</a>.</p>
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
<h2 id="section1">Warnings and Exceptions</h2>
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
<p>Not all warnings that Ruby code might emit are reproduced in the compiled C
|
|
28
|
+
extension.</p>
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
<p>Ruby2CExtension also omits some checks that might raise exceptions for Ruby
|
|
32
|
+
code (it won’t warn or raise exceptions on wrong argument count in lambdas for
|
|
33
|
+
example).</p>
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
<p>As a rule of thumb: if Ruby code works without warnings then the compiled C
|
|
37
|
+
extension will also work without warnings, but if the Ruby code emits
|
|
38
|
+
warnings, then the compiled C extension might emit less warnings.</p>
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
<p>Also, sometimes the compiled C extension will raise slightly different
|
|
42
|
+
exceptions than the Ruby code would.</p>
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
<h2 id="section2">C Extension Limitations</h2>
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
<p>Because the compiled code is a C extension, it will also behave like a C
|
|
49
|
+
extension:</p>
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
<ul>
|
|
53
|
+
<li>backtraces will look like backtraces of C extensions (i.e. no line
|
|
54
|
+
numbers, ...)</li>
|
|
55
|
+
<li>a trace proc set with <code>set_trace_func</code> will only get C extension events
|
|
56
|
+
(<code>"c-call"</code>, <code>"c-return"</code>, <code>"raise"</code>), instead of the usual Ruby code events</li>
|
|
57
|
+
</ul>
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
<h2 id="section3">Arity</h2>
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
<p>All methods and procs defined in Ruby code that is compiled to a C extension
|
|
64
|
+
will return <code>-1</code> as <code>arity</code>. So if your Ruby code depends on the method
|
|
65
|
+
<code>arity</code>, you might have to change it.</p>
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
<h2 id="section4">Continuations</h2>
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
<p>Continuations (<code>callcc</code>) are possible in compiled Ruby code, but you might see
|
|
72
|
+
wrong behavior with local variables (i.e. they will have an old value),
|
|
73
|
+
depending on whether these local variables are needed for a closure or not.</p>
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
<p>In short, you probably should not use continuations in Ruby code that you want
|
|
77
|
+
to compile to a C extension.</p>
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
<h2 id="section5">Scope</h2>
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
<p>In Ruby every scope (class scope, methods, ...) has an associated C struct
|
|
84
|
+
<span class="caps">SCOPE</span>, which stores the local variables (including <code>$~</code> and <code>$_</code>) for that
|
|
85
|
+
scope. Methods that are implemented in a C extension don’t get such a <span class="caps">SCOPE</span>,
|
|
86
|
+
because it is expensive to set up and they don’t need it (they just use
|
|
87
|
+
variables on the stack).</p>
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
<p>That means that the methods in Ruby code that is compiled to a C extension
|
|
91
|
+
won’t get a <span class="caps">SCOPE</span> either, which is usually no problem because local variables
|
|
92
|
+
are handled differently anyway. It only gets a problem, if the code uses
|
|
93
|
+
methods that work with the current <span class="caps">SCOPE</span>. Here are some of these methods:</p>
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
<ul>
|
|
97
|
+
<li><code>local_variables</code></li>
|
|
98
|
+
<li><code>eval</code></li>
|
|
99
|
+
<li><code>binding</code></li>
|
|
100
|
+
</ul>
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
<p>These methods will work, but they will see the <span class="caps">SCOPE</span> of the nearest Ruby code
|
|
104
|
+
scope. This is also true for <code>$_</code> and <code>$~</code> (and the derived <code>$&</code>, <code>$`</code>, <code>$'</code>,
|
|
105
|
+
<code>$1</code>, ...). Example:</p>
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
<pre><code>def bar
|
|
109
|
+
a = 2
|
|
110
|
+
"xxx" =~ /./ # changes $~ of the nearest Ruby code scope
|
|
111
|
+
p eval("a") # won't return 2 (a's value), instead it will be evaled in the
|
|
112
|
+
# nearest Ruby code scope
|
|
113
|
+
local_variables # returns local variables of the nearest Ruby code scope
|
|
114
|
+
end
|
|
115
|
+
</code></pre>
|
|
116
|
+
|
|
117
|
+
<p>If bar is compiled into a C extension and then called from the following Ruby
|
|
118
|
+
code:</p>
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
<pre><code>a = b = 42
|
|
122
|
+
$~ = nil
|
|
123
|
+
p bar
|
|
124
|
+
p $~
|
|
125
|
+
</code></pre>
|
|
126
|
+
|
|
127
|
+
<p>Then it will output</p>
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
<pre><code>42
|
|
131
|
+
["a", "b"]
|
|
132
|
+
#<MatchData: ...>
|
|
133
|
+
</code></pre>
|
|
134
|
+
|
|
135
|
+
<p>instead of the expected</p>
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
<pre><code>2
|
|
139
|
+
["a"]
|
|
140
|
+
nil
|
|
141
|
+
</code></pre>
|
|
142
|
+
|
|
143
|
+
<p>Another consequence is that if compiled methods call each other, they will all
|
|
144
|
+
share the same <code>$_</code> and <code>$~</code> (those of the nearest Ruby code scope). This
|
|
145
|
+
might make some code behave unexpectedly.</p>
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
<h2 id="section6">Vmode</h2>
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
<p>The so called vmode is also associated with the Ruby <span class="caps">SCOPE</span> (though not
|
|
152
|
+
directly stored inside the <span class="caps">SCOPE</span> struct). The vmode is set by the methods
|
|
153
|
+
<code>private</code>, <code>protected</code>, <code>public</code> and <code>module_function</code> and determines which
|
|
154
|
+
visibility newly defined methods get.</p>
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
<p>Ruby2CExtension can not (easily) access Ruby’s internal vmode, instead it
|
|
158
|
+
tries to figure out at compile time what visibility a method defined using
|
|
159
|
+
<code>def</code> will get. But be careful with <code>Module#define_method</code> and
|
|
160
|
+
<code>Module#attr*</code>: those methods will use Ruby’s internal vmode.</p>
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
<p>So, there are actually two different vmodes at work for compiled Ruby
|
|
164
|
+
code: the vmode that Ruby2CExtension uses at compile time to guess which
|
|
165
|
+
visibility methods defined with <code>def</code> get and Ruby’s internal vmode at
|
|
166
|
+
runtime which is used by <code>Module#define_method</code> and <code>Module#attr*</code>.</p>
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
<p>Ruby2CExtension’s compile time vmode heuristic works by replacing calls to the
|
|
170
|
+
vmode changing methods with <code>nil</code> and instead changing the compile time vmode.
|
|
171
|
+
The calls are only replaced if they are without receiver and without
|
|
172
|
+
arguments. And it also depends on where the calls are made:</p>
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
<p>In the <strong>toplevel scope</strong> only calls to <code>private</code> and <code>public</code> are replaced, the
|
|
176
|
+
default vmode in the toplevel scope is private.</p>
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
<p>In a <strong>module scope</strong> calls to <code>private</code>, <code>protected</code>, <code>public</code> and
|
|
180
|
+
<code>module_function</code> are replaced, the default vmode in a module scope is public.</p>
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
<p>In a <strong>class scope</strong> calls to <code>private</code>, <code>protected</code> and <code>public</code> are replaced,
|
|
184
|
+
the default vmode in a class scope is public.</p>
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
<p>In <strong>methods</strong> and <strong>blocks</strong> no calls are replaced and all methods defined with
|
|
188
|
+
<code>def</code> will be public.</p>
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
<p>If your code doesn’t do anything tricky, then the compile time heuristic
|
|
192
|
+
should just work as expected. Here is an example:</p>
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
<pre><code># start of file
|
|
196
|
+
# default vmode is private
|
|
197
|
+
def m1; end # private
|
|
198
|
+
|
|
199
|
+
public # this call will be replaced with nil
|
|
200
|
+
# vmode is now public
|
|
201
|
+
def m2; end # public
|
|
202
|
+
|
|
203
|
+
class A
|
|
204
|
+
# default vmode is public
|
|
205
|
+
def m2; end # public
|
|
206
|
+
|
|
207
|
+
private # this call will be replaced with nil
|
|
208
|
+
# vmode is now private
|
|
209
|
+
def m3 # private
|
|
210
|
+
def foo # public, because it is in a method
|
|
211
|
+
end
|
|
212
|
+
end
|
|
213
|
+
|
|
214
|
+
end
|
|
215
|
+
|
|
216
|
+
protected # this call is not replaced and will probably fail because
|
|
217
|
+
# #protected is not defined at toplevel
|
|
218
|
+
|
|
219
|
+
# end of file
|
|
220
|
+
</code></pre>
|
|
221
|
+
|
|
222
|
+
<p>Here is an example, where it fails:</p>
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
<pre><code>class A
|
|
226
|
+
def pub; end # public
|
|
227
|
+
|
|
228
|
+
private if nil # Ruby2CExtension replaces the call to private with nil
|
|
229
|
+
# vmode is now private
|
|
230
|
+
|
|
231
|
+
def pub2; end # will be private in the compiled C extension
|
|
232
|
+
end
|
|
233
|
+
</code></pre>
|
|
234
|
+
|
|
235
|
+
<p>But this should be a pretty uncommon case. The visibility of methods defined
|
|
236
|
+
using <code>def</code> should be correct for most Ruby code.</p>
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
<p>It is a bit more complicated for methods/attributes defined using
|
|
240
|
+
<code>define_method</code> or the <code>attr*</code> methods. Their visibility is determined by
|
|
241
|
+
Ruby’s internal vmode at run time.</p>
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
<p>As explained above, C extension code does not get its own <span class="caps">SCOPE</span>, so it also
|
|
245
|
+
doesn’t get its own vmode. When a C extension is <code>require</code>d, Ruby
|
|
246
|
+
sets the vmode to public before loading the C extension. All the class/module
|
|
247
|
+
scopes that are executed during the <code>require</code> are executed in the same <span class="caps">SCOPE</span>
|
|
248
|
+
and so also with the same vmode.</p>
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
<p>Because all the vmode changing method calls are replaced with <code>nil</code>, Ruby’s
|
|
252
|
+
internal vmode will probably stay public all the time and so all
|
|
253
|
+
methods/attributes defined using <code>define_method</code> or the <code>attr*</code> methods will
|
|
254
|
+
be public. Here is an example:</p>
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
<pre><code># Ruby's internal vmode is public
|
|
258
|
+
class A
|
|
259
|
+
# still the same internal vmode, still public
|
|
260
|
+
define_method(:a) {} # public
|
|
261
|
+
|
|
262
|
+
private # is replaced with nil, does not affect Ruby's internal vmode
|
|
263
|
+
def b; end # private
|
|
264
|
+
|
|
265
|
+
# but Ruby's internal vmode is still public
|
|
266
|
+
define_method(:c) {} # public
|
|
267
|
+
attr_accessor :d, :e # also public
|
|
268
|
+
end
|
|
269
|
+
</code></pre>
|
|
270
|
+
|
|
271
|
+
<p>If those methods really need another visibility, then it can be changed
|
|
272
|
+
explicitly:</p>
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
<pre><code>class A
|
|
276
|
+
define_method(:a) {}
|
|
277
|
+
private :a
|
|
278
|
+
end
|
|
279
|
+
</code></pre>
|
|
280
|
+
|
|
281
|
+
<p>In methods the internal vmode is that of the nearest Ruby <span class="caps">SCOPE</span> (as explained
|
|
282
|
+
above), so it is usually unpredictable. And additionally calling one of the
|
|
283
|
+
vmode changing methods will also affect the <span class="caps">SCOPE</span> of the caller:</p>
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
<pre><code># in compiled C extension
|
|
287
|
+
def my_private
|
|
288
|
+
private
|
|
289
|
+
end
|
|
290
|
+
</code></pre>
|
|
291
|
+
|
|
292
|
+
<pre><code># in Ruby code
|
|
293
|
+
class A
|
|
294
|
+
def a;end # public
|
|
295
|
+
my_private
|
|
296
|
+
def b;end # private, but would be public if the above code was not compiled
|
|
297
|
+
end
|
|
298
|
+
</code></pre>
|
|
299
|
+
|
|
300
|
+
<p>To be save, don’t use the vmode changing methods without arguments inside
|
|
301
|
+
methods, instead set the visibility explicitly (e.g. <code>private :a</code>).</p>
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
<h2 id="section7">Cref</h2>
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
<p>The so called cref is another Ruby internal that Ruby2CExtension has to
|
|
308
|
+
emulate. The cref is a linked list that describes the current lexical
|
|
309
|
+
class/module nesting. Example:</p>
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
<pre><code>class A
|
|
313
|
+
class B
|
|
314
|
+
# cref here is B -> A -> Object
|
|
315
|
+
end
|
|
316
|
+
# cref here is A -> Object
|
|
317
|
+
module C
|
|
318
|
+
# cref here is C -> A -> Object
|
|
319
|
+
end
|
|
320
|
+
end
|
|
321
|
+
# cref here is Object
|
|
322
|
+
</code></pre>
|
|
323
|
+
|
|
324
|
+
<p>The current cref is used for constant and class variable lookup and for <code>def</code>,
|
|
325
|
+
<code>undef</code> and <code>alias</code>.</p>
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
<p>Ruby2CExtension emulates cref with the same semantics as Ruby. There are only
|
|
329
|
+
two problems.</p>
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
<p>First, when a method is defined in Ruby code, it saves the current cref for
|
|
333
|
+
later use. From C it isn’t possible to store an extra value when defining a
|
|
334
|
+
method, so Ruby2CExtension works around this problem by storing the cref in a
|
|
335
|
+
global variable. But there is still a problem when a <code>def</code> is used/run
|
|
336
|
+
multiple times, because the cref can differ each time.</p>
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
<p>So if a <code>def</code> that requires a cref is used multiple times, then the compiled C
|
|
340
|
+
extension will raise an exception (this is the only case where code compiled
|
|
341
|
+
with Ruby2CExtension raises an exception that Ruby wouldn’t raise). If a <code>def</code>
|
|
342
|
+
doesn’t need a cref, then everything is fine and it can be used multiple
|
|
343
|
+
times. Examples:</p>
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
<pre><code>["a", "b"].each { |s|
|
|
347
|
+
class << s
|
|
348
|
+
def bar; self; end # is OK, doesn't need cref
|
|
349
|
+
end
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
["a", "b"].each { |s|
|
|
353
|
+
class << s
|
|
354
|
+
def baz; Array.new(self); end # fails the 2nd time
|
|
355
|
+
end
|
|
356
|
+
}
|
|
357
|
+
</code></pre>
|
|
358
|
+
|
|
359
|
+
<p>The second case fails because the constant lookup for <code>Array</code> needs a cref. If
|
|
360
|
+
you really need this to work, then you can use <code>::Array</code> instead of <code>Array</code>,
|
|
361
|
+
because that won’t need a cref.</p>
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
<p>Again in the usual case everything should be fine and if you really need to
|
|
365
|
+
use a <code>def</code> that requires a cref multiple times, then you might be able to
|
|
366
|
+
modify it so that it won’t need a cref.</p>
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
<p>The second problem that arises from Ruby2CExtension emulating crefs is that
|
|
370
|
+
methods that access Ruby’s internal cref, will see the wrong cref and thus
|
|
371
|
+
not behave as expected. Those methods are <code>Module.nesting</code>, <code>Module.constants</code>
|
|
372
|
+
(but <code>Module#constants</code> works), <code>autoload</code> and <code>autoload?</code> (use
|
|
373
|
+
<code>Module#autoload</code> and <code>Module#autoload?</code> instead).</p>
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
<h2 id="section8">Block Pass</h2>
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
<p>There currently is no way to pass a Proc instance as the block parameter to a
|
|
380
|
+
method call on the C side, i.e. there is no way to do the following from C:</p>
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
<pre><code>def foo(proc)
|
|
384
|
+
bar(&proc)
|
|
385
|
+
end
|
|
386
|
+
</code></pre>
|
|
387
|
+
|
|
388
|
+
<p>Ruby2CExtension works around this by compiling the above to something similar
|
|
389
|
+
to this:</p>
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
<pre><code>def foo(proc)
|
|
393
|
+
tmp_proc = proc.to_proc
|
|
394
|
+
bar { |*arg| tmp_proc.call(*arg) }
|
|
395
|
+
end
|
|
396
|
+
</code></pre>
|
|
397
|
+
|
|
398
|
+
<p>The downside of this workaround is that it doesn’t work (as expected) with
|
|
399
|
+
methods like <code>instance_eval</code> and it is problematic if a proc is passed deep
|
|
400
|
+
into a recursive method, because that block will then be wrapped multiple
|
|
401
|
+
times.</p>
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
<p>This issue might be fixed if a future Ruby version provides a way to cleanly
|
|
405
|
+
pass a proc to a method call.</p>
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
<h2 id="section9">Block Argument Semantics</h2>
|
|
409
|
+
|
|
410
|
+
|
|
411
|
+
<p>Block argument semantics are a bit tricky, but Ruby2CExtension should get it
|
|
412
|
+
right for most cases, here are two cases where the result is wrong:</p>
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
<pre><code>def t1(*a); yield *a; end
|
|
416
|
+
p t1([1, 2]) { |a| a }
|
|
417
|
+
|
|
418
|
+
def bl_pa_tst(); p yield([1, 2]); end
|
|
419
|
+
pc = proc { |*a| a }
|
|
420
|
+
bl_pa_tst(&pc)
|
|
421
|
+
bl_pa_tst { |*a| a }
|
|
422
|
+
</code></pre>
|
|
423
|
+
|
|
424
|
+
<p>Ruby outputs:</p>
|
|
425
|
+
|
|
426
|
+
|
|
427
|
+
<pre><code>[1, 2]
|
|
428
|
+
[[1, 2]]
|
|
429
|
+
[[1, 2]]
|
|
430
|
+
</code></pre>
|
|
431
|
+
|
|
432
|
+
<p>The compiled C extension outputs:</p>
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
<pre><code>[[1, 2]]
|
|
436
|
+
[1, 2]
|
|
437
|
+
[1, 2]
|
|
438
|
+
</code></pre>
|
|
439
|
+
|
|
440
|
+
<p>But again, for most cases it should just work and maybe it will get better in
|
|
441
|
+
future Ruby2CExtension versions.</p>
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
<h2 id="section10"><code>super</code> with implicit arguments and optional arguments</h2>
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
<p>In a compiled C extension <code>super</code> with implicit arguments will not use
|
|
448
|
+
optional arguments that have not been given by the original caller. Example:</p>
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
<pre><code>class A
|
|
452
|
+
def foo(*a)
|
|
453
|
+
p a
|
|
454
|
+
end
|
|
455
|
+
end
|
|
456
|
+
|
|
457
|
+
class B < A
|
|
458
|
+
def foo(a = nil)
|
|
459
|
+
super
|
|
460
|
+
end
|
|
461
|
+
end
|
|
462
|
+
|
|
463
|
+
B.new.foo
|
|
464
|
+
</code></pre>
|
|
465
|
+
|
|
466
|
+
<p>In Ruby this code will output <code>[nil]</code>, in the compiled form it will output
|
|
467
|
+
<code>[]</code>.</p>
|
|
468
|
+
|
|
469
|
+
|
|
470
|
+
<h2 id="section11">Not Supported Features</h2>
|
|
471
|
+
|
|
472
|
+
|
|
473
|
+
<p>Ruby files that use one or more of the above described problematic things will
|
|
474
|
+
usually compile just fine and fail or behave wrong at runtime. In contrast,
|
|
475
|
+
the following things will be catched at compile time. Most of them are just
|
|
476
|
+
not supported yet and might be added later.</p>
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
<h3>Control Flow</h3>
|
|
480
|
+
|
|
481
|
+
|
|
482
|
+
<p>Most of the things that are not supported are related to control flow. Ruby
|
|
483
|
+
implements most of its control flow using <code>setjmp()</code> and <code>longjmp()</code>. Most of
|
|
484
|
+
this is in <code>eval.c</code> and there is no real <span class="caps">API</span> to access it, so Ruby2CExtension
|
|
485
|
+
has to do some tricks to make control flow work. For most cases workarounds
|
|
486
|
+
are implemented, but some of the harder cases are not (yet) supported.</p>
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
<p>The first thing that isn’t supported is <code>return</code> from inside a block. Also
|
|
490
|
+
<code>break</code> with a value from inside a block is not supported (but <code>break</code> without
|
|
491
|
+
a value is):</p>
|
|
492
|
+
|
|
493
|
+
|
|
494
|
+
<pre><code>def foo
|
|
495
|
+
bar(1, 2, 3) {
|
|
496
|
+
next # works
|
|
497
|
+
next 42 # works
|
|
498
|
+
redo # works
|
|
499
|
+
break # works
|
|
500
|
+
break 42 # does not work
|
|
501
|
+
return # does not work
|
|
502
|
+
return 42 # does not work
|
|
503
|
+
}
|
|
504
|
+
return # works
|
|
505
|
+
return 42 # works
|
|
506
|
+
end
|
|
507
|
+
</code></pre>
|
|
508
|
+
|
|
509
|
+
<p>For <code>while</code>/<code>until</code> loops everything works.</p>
|
|
510
|
+
|
|
511
|
+
|
|
512
|
+
<p>Another problematic area in Ruby2CExtension 0.1.0 was control flow “through” a
|
|
513
|
+
<code>rescue</code> or <code>ensure</code> clause. This is mostly implemented now, only in <code>ensure</code>
|
|
514
|
+
clauses it still does not work (it <em>does</em> work in <code>ensure</code> bodies):</p>
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
<pre><code>def foo
|
|
518
|
+
while bar?
|
|
519
|
+
begin
|
|
520
|
+
next # works
|
|
521
|
+
next 42 # works
|
|
522
|
+
redo # works
|
|
523
|
+
break # works
|
|
524
|
+
break 42 # works
|
|
525
|
+
return # works
|
|
526
|
+
return 42 # works
|
|
527
|
+
rescue
|
|
528
|
+
next # works
|
|
529
|
+
next 42 # works
|
|
530
|
+
redo # works
|
|
531
|
+
break # works
|
|
532
|
+
break 42 # works
|
|
533
|
+
return # works
|
|
534
|
+
return 42 # works
|
|
535
|
+
ensure
|
|
536
|
+
next # does not work
|
|
537
|
+
next 42 # does not work
|
|
538
|
+
redo # does not work
|
|
539
|
+
break # does not work
|
|
540
|
+
break 42 # does not work
|
|
541
|
+
return # does not work
|
|
542
|
+
return 42 # does not work
|
|
543
|
+
end
|
|
544
|
+
end
|
|
545
|
+
end
|
|
546
|
+
</code></pre>
|
|
547
|
+
|
|
548
|
+
<h3><code>defined?</code></h3>
|
|
549
|
+
|
|
550
|
+
|
|
551
|
+
<p>The <code>defined?</code> statement is also not fully supported, it works for most of the
|
|
552
|
+
common cases like constants, global variables, instance variables, class
|
|
553
|
+
variables and <code>$~</code> (and derived). Ruby2CExtension fails at compile time if a
|
|
554
|
+
case is not supported.</p>
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
<h3><code>super</code> with implicit arguments in Ruby 1.8.5 and later</h3>
|
|
558
|
+
|
|
559
|
+
|
|
560
|
+
<p>For Ruby 1.8.5 <code>super</code> with implicit arguments is only supported in methods (not in blocks or
|
|
561
|
+
<code>rescue</code>/<code>ensure</code> clauses). For Ruby 1.8.4 <code>super</code> with implicit arguments is
|
|
562
|
+
supported everywhere.</p>
|
|
563
|
+
|
|
564
|
+
|
|
565
|
+
<p>To work around this problem, just specify the arguments explicitly:</p>
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
<pre><code>def foo(a, b)
|
|
569
|
+
3.times { super(a, b) }
|
|
570
|
+
end
|
|
571
|
+
</code></pre>
|
|
572
|
+
|
|
573
|
+
<p>instead of:</p>
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
<pre><code>def foo(a, b)
|
|
577
|
+
3.times { super }
|
|
578
|
+
end
|
|
579
|
+
</code></pre>
|
|
580
|
+
</body>
|
|
581
|
+
</html>
|