Ruby Extensions

A few weeks ago I came across François Lamontagne's "Ruby and C : Part 1" post. He talks about the VALUE type in Ruby and how that's typedef'd to an unsigned long. You can see this in ruby.h; in ruby 1.8.6 p369 it's line 86:

typedef unsigned long VALUE;

One interesting thing that François' article notes is that VALUE can contain either a pointer to the data or the data itself. You can see this in Aman Gupta's latest post to Time to Bleed. In one example he creates an Array containing a few Fixnums and a String and then dumps the heap using memprof. This yields:

  {
    "type": "array",
    "length": 4,
    "data": [
      1,
      2,
      3,
      "0x12aa0c0"
    ]
  }

So the three Fixnums are stored as immediate values, and the last value is the pointer to the String.

What other Ruby types are stored as immediate values? From ruby.h around line 697 in the rb_type function:

    if (FIXNUM_P(obj)) return T_FIXNUM;
    if (obj == Qnil) return T_NIL;
    if (obj == Qfalse) return T_FALSE;
    if (obj == Qtrue) return T_TRUE;
    if (obj == Qundef) return T_UNDEF;
    if (SYMBOL_P(obj)) return T_SYMBOL;

Looks like Fixnums, Nil, False, True, and Symbols. Everything else gets identified using the BUILTIN_TYPE macro. The Ruby 1.9.1 code looks kind of similar, although it uses different macros (like RTEST) and does the comparisons in a different order.

In July of 2006 Peter Cooper (author of Beginning Ruby and many helpful web sites) published "How to create a Ruby extension in C in under 5 minutes". This is a nicely formatted little one page tutorial that walks you through creating an extconf.rb and a little test extension that defines a module and a method.

The extension uses rb_define_method to define the method, so it's an instance method on the module. That's why client code has to include the module. If the extension had used rb_define_module_function, it'd be a public class method instead. Then you could invoke it without the include, e.g., with just MyTest::test1 or MyTest.test1. In other words, rb_define_method defines an instance method, while rb_define_module_function define a public class function. It's the difference between:

module MyTest
  def test1
  end
end

and

module MyTest
  def self.test1
  end
end

You could use module_function as well to flip a method from being a private method to a public class method. There's a good section on module definition and visibility in David Flanagan's excellent book The Ruby Programming Language.

In the comment stream Ryan Davis suggests using ruby-inline to save a few more steps. I definitely plan on doing a post on ruby-inline for this blog at some point; neat stuff indeed.