Basic about Ruby C API

Creating a Gem using Ruby C API

Sometimes we want to use a lib built with C language without any Ruby version, to make this we'll find a gem that integrates the lib C with Ruby. But, how this Gem was built?

In this article I'll show how to make this, using as an example the project musicrb, this Gem uses the lib of C vlc to play music on Ruby.

How is possible to integrate Ruby and C?

It's simple: Ruby is built using C, so we'll build a shared lib to the interpreter of Ruby use.

But do not trust in me, see the repository of language!

Basic about Ruby C API

Before starting to code our lib, we'll see some features in Ruby C API that we will use (p.s.: this tutorial is very basic if you want deep in this theme, my recommendation is the book Ruby Under a Microscope).

VALUE

See VALUE as a pointer to a Ruby's Object, since the Ruby is dynamic this feature is required. Then String, Number, Class, Module ... are accessed and modified by VALUE through functions of Ruby C API.

This is an example using VALUE as a pointer to String:

VALUE x;
x = rb_str_new_cstr("Hello, world!");

VALUE str;
str = rb_sprintf("pi = %f. %"PRIsVALUE" inspected: %+"PRIsVALUE, M_PI, x, x);

/* pi = 3.141593. Hello, world! inspected: "Hello, world!" */

We can see that isn't required to pass the type of VALUE to methods like a programRuby!

DEFINE

The Gem musicrb has a class named Music, and has two static methods: play and stop.

Define this class and methods using Ruby is very simple:

class Music
  def play
    # Implementation ...
  end

  def stop
    # Implementation ...
  end
end

The code in C will be like this:

// Headers ...

// Global variables ...
VALUE rb_cMusic;

VALUE
rb_music_stop(VALUE msc)
{
  // Implementation ...
}

VALUE
rb_music_play(VALUE msc, VALUE rpath)
{
  // Implementation ...
}

void
Init_musicrb(void)
{
  rb_cMusic = rb_define_class("Music", rb_cObject);
  rb_define_singleton_method(rb_cMusic, "play", rb_music_play, 1);
  rb_define_singleton_method(rb_cMusic, "stop", rb_music_stop, 0);
}

rb_define_class: Define a class named "Music" that has a heritage with "Object".
rb_define_singleton_method: Define a singleton method to class "Music", in other words, a method of class. The last parameter of the function is the number of args.

Again, don't trust me!
See here the code.