RubyInline 3.1.0

data/tutorial/example1.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/ruby -w
+
+# We started out with some code that averaged a ton of numbers in a
+# bunch of arrays. Once we finally lost our patience with the average
+# running time of the code, we decided to profile and optimize it
+# using RubyInline. 
+
+class Array
+
+  def average
+    result = 0
+    self.each { |x| result += x }
+    result / self.size.to_f
+  end
+
+end
+
+max_loop = (ARGV.shift || 5).to_i
+max_size = (ARGV.shift || 100_000).to_i
+a = (1..max_size).to_a
+
+1.upto(max_loop) do
+  avg = a.average
+  $stderr.print "."
+end
+$stderr.puts ""
+
+# The first step to profiling is to get a simple run of the code using
+# 'time' and a large dataset. This is because a profile run should
+# only be used for figuring out where your bottlenecks are, but the
+# runtime of a profile run should be considered invalid. This is
+# because set_trace_func, the main mechanism used by profile is a very
+# costly function.
+
+#   & time ruby ./example1.rb 5 100000
+#   .....
+#  
+#   real 0m4.580s
+#   user 0m3.310s
+#   sys  0m0.090s
+# (user+sys = 3.400s)
+
+# This gives us a tangible goal, to reduce the runtime of 4.58 seconds
+# as much as possible. The next step is to run with a smaller dataset
+# (because profiling is VERY SLOW) while including the profile module.
+
+#   & ruby -rprofile ./example1.rb 3 10000
+#   ...
+#     %   cumulative   self              self     total
+#    time   seconds   seconds    calls  ms/call  ms/call  name
+#    69.78     4.78      4.78        3  1593.33  2273.33  Array#each
+#    29.78     6.82      2.04    30000     0.07     0.07  Fixnum#+
+#     0.15     6.83      0.01        3     3.33  2276.67  Array#average
+#     0.15     6.84      0.01        1    10.00    10.00  Range#each
+#     0.00     6.84      0.00        1     0.00    10.00  Enumerable.to_a
+# -- CUT ALL FOLLOWING LINES WHERE %time == 0.00
+
+# This says that Array#each and Fixnum#+ are the only two things we
+# should focus on at all. The rest of the time is statistically
+# insignificant. So, since average itself is a rather uncomplicated
+# method, we decided to convert the entire method rather than just try
+# to speed up the math or the loop separately. See example2.rb for the
+# continuation of this example.

data/tutorial/example2.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/ruby -w -I..
+
+require 'inline'
+
+class Array
+
+  inline do |builder|
+    builder.c_raw "
+      static VALUE average(int argc, VALUE *argv, VALUE self) {
+        double result;
+        long  i, len;
+        VALUE *arr = RARRAY(self)->ptr;
+        len = RARRAY(self)->len;
+        
+        for(i=0; i<len; i++) {
+          result += NUM2DBL(arr[i]);
+        }
+  
+        return rb_float_new(result/(double)len);
+      }
+    "
+  end
+end
+
+max_loop = (ARGV.shift || 5).to_i
+max_size = (ARGV.shift || 100_000).to_i
+a = (1..max_size).to_a
+
+1.upto(max_loop) do
+  avg = a.average
+  $stderr.print "."
+end
+$stderr.puts ""
+
+#   ruby -rprofile ./example2.rb 3 10000
+#   ...
+#     %   cumulative   self              self     total
+#    time   seconds   seconds    calls  ms/call  ms/call  name
+#    23.53     0.08      0.08        4    20.00   122.50  Kernel.require
+#    14.71     0.13      0.05      123     0.41     0.98  Config.expand
+#    11.76     0.17      0.04      135     0.30     0.59  String#gsub!
+#    11.76     0.21      0.04        1    40.00    40.00  Hash#each
+#     8.82     0.24      0.03        1    30.00   110.00  Hash#each_value
+#     5.88     0.26      0.02        3     6.67     6.67  Mod_Array_average.average
+#     2.94     0.27      0.01       10     1.00     1.00  Kernel.singleton_method_added
+#     2.94     0.28      0.01        1    10.00    30.00  Fixnum#upto
+#     2.94     0.29      0.01        2     5.00    10.00  Module#parse_signature
+#     2.94     0.30      0.01        2     5.00     5.00  File#stat
+#     2.94     0.31      0.01        1    10.00    10.00  Range#each
+#     2.94     0.32      0.01        1    10.00    50.00  Module#inline_c_real
+#     2.94     0.33      0.01      182     0.05     0.05  Hash#[]=
+#     2.94     0.34      0.01        1    10.00    20.00  Module#inline_c_gen
+#     0.00     0.34      0.00        1     0.00     0.00  Module#include
+# -- CUT ALL FOLLOWING LINES WHERE %time == 0.00
+
+# The first example's cumulative time for Array#average was 6.83
+# seconds (wallclock) and the second example's average
+# (Mod_Array_average#average) was .26 seconds (a 26x speedup). The
+# rest of the time was spent dealing with RubyInline's compile of the
+# code. Subsequent runs of the code skip most of RubyInline's work
+# because the code has already been compiled and it hasn't changed.
+# Looking at the profile, there was really nothing more that we wanted
+# to speed up. If there was, then we would have done a few more
+# iterations of using RubyInline to extract slower ruby code into
+# faster C code and profiling again.
+#
+# At this point, we were satisfied with the time of the code and
+# decided to stop profiling. All that was left to do was to run with
+# 'time' again and our larger dataset:
+
+#   & time ruby ./example2.rb 5 100000
+#   .....
+#  
+#   real 0m1.403s
+#   user 0m1.120s
+#   sys  0m0.070s
+# (user+sys = 1.190s)
+
+# We've reduced the running time of the program from 3.40s of CPU time
+# to 1.19s of CPU. This is a speed-up of 2.85. Not too shabby...
+
+# You don't want to compare the runtime of the profiled code because
+# the cost of running with set_trace_func is so great that it skews
+# the results heavily. Looking at the ratio between the normal run
+# versus the profiled runs between the pure ruby and the inlined
+# versions shows this skew quite clearly:
+
+#        norm   prof
+#   ruby 3.40   6.83  (1:2 roughly)
+#   C    1.19   0.26  (5:1 roughly)
+
+# This happens simply because our call to Mod_Array_average.average
+# causes 30000-1 less method calls than the pure ruby version. This
+# translates directly into a multiplier per method call when using
+# set_trace_func (which we estimate to be about 200us per call (6.83 /
+# 30000) on my machine.

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.1
+specification_version: 1
+name: RubyInline
+version: !ruby/object:Gem::Version 
+  version: 3.1.0
+date: 2004-11-19
+summary: Multi-language extension coding within ruby.
+require_paths: 
+  - "."
+author: Ryan Davis
+email: ryand-ruby@zenspider.com
+homepage: http://www.zenspider.com/ZSS/Products/RubyInline/
+rubyforge_project: rubyinline
+description: "Ruby Inline is my quick attempt to create an analog to Perl's Inline::C. It
+  allows you to embed C or C++ external module code in your ruby script directly.
+  The code is compiled and run on the fly when needed. The ruby version isn't near
+  as feature-full as the perl version, but it is neat!"
+autorequire: inline
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+files: 
+  - History.txt
+  - Makefile
+  - Manifest.txt
+  - README.txt
+  - example.rb
+  - example2.rb
+  - inline.gemspec
+  - inline.rb
+  - inline-compat.rb
+  - test_inline.rb
+  - tutorial/example1.rb
+  - tutorial/example2.rb
+test_files: 
+  - test_inline.rb
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: 
+  - A POSIX environment and a compiler for your language.
+dependencies: []