Programming Ruby: The Pragmatic Programmer's Guide

# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

# Extending Ruby

It is easy to extend Ruby with new features by writing code in Ruby. Once you start adding in low-level code written in C, however, the possibilities are endless.

Extending Ruby with C is pretty easy. For instance, suppose we are building a custom Internet-ready jukebox for the Sunset Diner and Grill. It will play MP3 audio files from a hard disk or audio CDs from a CD jukebox. We want to be able to control the jukebox hardware from a Ruby program. The hardware vendor gave us a C header file and a binary library to use; our job is to construct a Ruby object that makes the appropriate C function calls.

But before we can get Ruby and C to work together, we need to see what the Ruby world looks like from the C side.[Much of the information in this chapter is taken from the `README.EXT` file that is included in the distribution. If you are planning on writing a Ruby extension, you may want to refer to that file for more details as well as the latest changes.]

## Ruby Objects in C

The first thing we need to look at is how to represent and access Ruby datatypes from within C. Everything in Ruby is an object, and all variables are references to objects. In C, this means that the type of all Ruby variables is `VALUE`, which is either a pointer to a Ruby object or an immediate value (such as `Fixnum`).

This is how Ruby implements object-oriented code in C: a Ruby object is an allocated structure in memory that contains a table of instance variables and information about the class. The class itself is another object (an allocated structure in memory) that contains a table of the methods defined for that class. On this foundation hangs all of Ruby.

### VALUE as a Pointer

When `VALUE` is a pointer, it is a pointer to one of the defined Ruby object structures---you can't have a `VALUE` that points to an arbitrary structure. The structures for each built-in class are defined in ```ruby.h`'' and are named `R` Classname, as in `RString` and `RArray`.

You can check to see what type of structure is used for a particular `VALUE` in a number of ways. The macro `TYPE(` obj `)` will return a constant representing the C type of the given object: `T_OBJECT`, `T_STRING`, and so on. Constants for the built-in classes are defined in ```ruby.h`''. Note that the type we are referring to here is an implementation detail---it is not the same as the class of an object.

If you want to ensure that a value pointer points to a particular structure, you can use the macro `Check_Type`, which will raise a `TypeError` exception if value is not of the expected type (which is one of the constants `T_STRING`, `T_FLOAT`, and so on):

    Check_Type(VALUE value, int type)

If speed is an issue, there are faster macros that check specifically for the immediate values `Fixnum` and `nil`.

    FIXNUM_P(value) -> non-zero if value is a Fixnum
    NIL_P(value)    -> non-zero if value is nil
    RTEST(value)    -> non-zero if value is neither nil nor false

Again, note that we are talking about ``type'' as the C structure that represents a particular built-in type. The class of an object is a different beast entirely. The class objects for the built-in classes are stored in C global variables named `rb_c` Classname (for instance, `rb_cObject`); modules are named `rb_m` Modulename.

It wouldn't be advisable to mess with the data in these structures directly, however---you may look, but don't touch unless you are fond of debuggers. You should normally use only the supplied C functions to manipulate Ruby data (we'll talk more about this in just a moment).

However, in the interests of efficiency you may need to dig into these structures to obtain data. In order to dereference members of these C structures, you have to cast the generic `VALUE` to the proper structure type. `ruby.h` contains a number of macros that perform the proper casting for you, allowing you to dereference structure members easily. These macros are named `RCLASSNAME` , as in `RSTRING` or `RARRAY`. For example:

    VALUE str, arr;
    RSTRING(str)->len -> length of the Ruby string
    RSTRING(str)->ptr -> pointer to string storage
    RARRAY(arr)->len  -> length of the Ruby array
    RARRAY(arr)->capa -> capacity of the Ruby array
    RARRAY(arr)->ptr  -> pointer to array storage

### VALUE as an Immediate Object

As we said above, immediate values are not pointers: `Fixnum`, `Symbol`, `true`, `false`, and `nil` are stored directly in `VALUE`.

`Fixnum` values are stored as 31-bit numbers[Or 63-bit on wider CPU architectures.] that are formed by shifting the original number left 1 bit and then setting the least significant bit (bit 0) to ``1.'' When `VALUE` is used as a pointer to a specific Ruby structure, it is guaranteed always to have an LSB of zero; the other immediate values also have LSBs of zero. Thus, a simple bit test can tell you whether or not you have a `Fixnum`.

There are several useful conversion macros for numbers as well as other standard datatypes shown in Table 17.1 on page 174.

The other immediate values (`true`, `false`, and `nil`) are represented in C as the constants `Qtrue`, `Qfalse`, and `Qnil`, respectively. You can test `VALUE` variables against these constants directly, or use the conversion macros (which perform the proper casting).

## Writing Ruby in C

One of the joys of Ruby is that you can write Ruby programs almost directly in C. That is, you can use the same methods and the same logic, but with slightly different syntax to accommodate C. For instance, here is a small, fairly boring test class written in Ruby.

    class Test
      def initialize
        @arr = Array.new
      end
      def add(anObject)
        @arr.push(anObject)
      end
    end

The equivalent code in C should look somewhat familiar.

    #include "ruby.h"

    static VALUE t_init(VALUE self)
    {
      VALUE arr;

      arr = rb_ary_new();
      rb_iv_set(self, "@arr", arr);
      return self;
    }

    static VALUE t_add(VALUE self, VALUE anObject)
    {
      VALUE arr;

      arr = rb_iv_get(self, "@arr");
      rb_ary_push(arr, anObject);
      return arr;
    }

    VALUE cTest;

    void Init_Test() {
      cTest = rb_define_class("Test", rb_cObject);
      rb_define_method(cTest, "initialize", t_init, 0);
      rb_define_method(cTest, "add", t_add, 1);
    }

Let's go through this example in detail, as it illustrates many of the important concepts in this chapter. First off, we need to include the header file ```ruby.h`'' to obtain the necessary definitions.

Now look at the last function, `Init_Test`. Every class or module defines a C global function named `Init_` Name. This function will be called when the interpreter first loads the extension Name (or on startup for statically linked extensions). It is used to initialize the extension and to insinuate it into the Ruby environment. In this case, we define a new class named `Test`, which is a subclass of `Object` (represented by the external symbol `rb_cObject`; see ```ruby.h`'' for others).

Next we set up `add` and `initialize` as two instance methods for class `Test`. The calls to `rb_define_method` establish a binding between the Ruby method name and the C function that will implement it, so a call to the `add` method in Ruby will call the C function `t_add` with one argument.

Similarly, when `new` is called for this class, Ruby will construct a basic object and then call `initialize`, which we have defined here to call the C function `t_init` with no (Ruby) arguments.

Now go back and look at the definition of `initialize`. Even though we said it took no arguments, there's a parameter here! In addition to any Ruby arguments, every method is passed an initial `VALUE` argument that contains the receiver for this method (the equivalent of `self` in Ruby code).

The first thing we'll do in `initialize` is create a Ruby array and set the instance variable `@arr` to point to it. Just as you would expect if you were writing Ruby source, referencing an instance variable that doesn't exist creates it.

Finally, the function `t_add` gets the instance variable `@arr` from the current object and calls `Array#push` to push the passed value onto that array. When accessing instance variables in this way, the `@`-prefix is mandatory---otherwise the variable is created, but cannot be referenced from Ruby.

Despite the extra, clunky syntax that C imposes, you're still writing in Ruby---you can manipulate objects using all of the method calls you've come to know and love, with the added advantage of being able to craft tight, fast code when needed.

WARNING: Every C function that is callable from Ruby must return a `VALUE`, even if it's just `Qnil`. Otherwise, a core dump (or GPF) will be the likely result.

We can use the C version of the code in Ruby simply by `require`-ing it dynamically at runtime (on most platforms).

    require "code/ext/Test"
    t = Test.new
    t.add("Bill Chase")

C/Ruby datatype conversion functions and macros
C Datatypes to Ruby Objects:
| INT2NUM(int) | -> Fixnum or Bignum
| INT2FIX(int) | -> Fixnum (faster)
| INT2NUM(long or int) | -> Fixnum or Bignum
| INT2FIX(long or int) | -> Fixnum (faster)
| CHR2FIX(char) | -> Fixnum
| rb_str_new2(char *) | -> String
| rb_float_new(double) | -> Float
Ruby Objects to C Datatypes:
int | NUM2INT(Numeric) | (Includes type check)
int | FIX2INT(Fixnum) | (Faster)
unsigned int | NUM2UINT(Numeric) | (Includes type check)
unsigned int | FIX2UINT(Fixnum) | (Includes type check)
long | NUM2LONG(Numeric) | (Includes type check)
long | FIX2LONG(Fixnum) | (Faster)
unsigned long | NUM2ULONG(Numeric) | (Includes type check)
char | NUM2CHR(Numeric or String) | (Includes type check)
char * | STR2CSTR(String) |
char * | rb_str2cstr(String, int *length) | Returns length as well
double | NUM2DBL(Numeric) |

### Evaluating Ruby Expressions in C

If you are in the middle of some C code and you want to run an arbitrary Ruby expression without writing a bunch of C, you can always use the C version of `eval`. Suppose you have a collection of objects that need to have a flag cleared.

    rb_eval_string("anObject.each{|x| x.clearFlag }");

If you just want to call a particular method (which is cheaper than `eval`-ing an entire string) you can use

    rb_funcall(receiver, method_id, argc, ...)

Full descriptions of these and other commonly used C functions begin on page 186.

## Sharing Data Between Ruby and C

We've covered enough of the basics now to return to our jukebox example---interfacing C code with Ruby and sharing data and behavior between the two worlds.

### Directly Sharing Variables

Although you could maintain a C version of some variable along with a separate Ruby version of that variable, and struggle to keep the two in sync,[A clear violation of the DRY--Don't Repeat Yourself---principle described in our book The Pragmatic Programmer .] it would be much better to share a variable directly between Ruby and C. You can share global variables by creating a Ruby object on the C side and then binding its address to a Ruby global variable. In this case, the $ prefix is optional, but it helps clarify that this is a global variable.

    VALUE hardware_list;
    hardware_list = rb_ary_new();
    rb_define_variable("$hardware", &hardware_list);
    ...
    rb_ary_push(hardware_list, rb_str_new2("DVD"));
    rb_ary_push(hardware_list, rb_str_new2("CDPlayer1"));
    rb_ary_push(hardware_list, rb_str_new2("CDPlayer2"));

The Ruby side can then access the C variable `hardware_list` as `$hardware`:

`$hardware` | » | `["DVD", "CDPlayer1", "CDPlayer2"]`

You can also create hooked variables that will call a specified function when the variable is accessed, and virtual variables that only call the hooks---no actual variable is involved. See the API section that begins on page 189 for details.

If you create a Ruby object from C and store it in a C global variable without exporting it to Ruby, you must at least tell the garbage collector about it, lest ye be reaped inadvertently:

    VALUE obj;
    obj = rb_ary_new();
    rb_global_variable(obj);

### Wrapping C Structures

Now on to the really fun stuff. We've got the vendor's library that controls the audio CD jukebox units, and we're ready to wire it into Ruby. The vendor's header file looks like this:

    typedef struct _cdjb {
      int statusf;
      int request;
      void *data;
      char pending;
      int unit_id;
      void *stats;
    } CDJukebox;

    // Allocate a new CDPlayer structure and bring it online
    CDJukebox *CDPlayerNew(int unit_id);

    // Deallocate when done (and take offline)
    void CDPlayerDispose(CDJukebox *rec);

    // Seek to a disc, track and notify progress
    void CDPlayerSeek(CDJukebox *rec,
                      int disc,
                      int track,
                      void (*done)(CDJukebox *rec, int percent));
    // ... others...
    // Report a statistic
    double CDPlayerAvgSeekTime(CDJukebox *rec);

This vendor has its act together; while the vendor might not admit it, the code is written with an object-oriented flavor. We don't know what all those fields mean within the `CDJukeBox` structure, but that's okay---we can treat it as an opaque pile of bits. The vendor's code knows what to do with it, we just have to carry it around.

Anytime you have a C-only structure that you would like to handle as a Ruby object, you should wrap it in a special, internal Ruby class called `DATA` (type `T_DATA`). There are two macros to do this wrapping, and one to retrieve your structure back out again.

C Datatype Wrapping
`VALUE` | `Data_Wrap_Struct(VALUE class, void (*mark)(), void (*free)(), void *ptr")`
| Wraps the given C datatype ptr, registers the two garbage collection routines (see below), and returns a VALUE pointer to a genuine Ruby object. The C type of the resulting object is `T_DATA` and its Ruby class is class.
`VALUE` | `Data_Make_Struct(VALUE class, c-type, void (*mark)(), void (*free)(), c-type *")`
| Allocates a structure of the indicated type first, then proceeds as `Data_Wrap_Struct`. c-type is the name of the C datatype that you're wrapping, not a variable of that type.
`` | `Data_Get_Struct(VALUE obj,c-type,c-type *")`
| Returns the original pointer. This macro is a type-safe wrapper around the macro `DATA_PTR(obj)`, which evaluates the pointer.

The object created by `Data_Wrap_Struct` is a normal Ruby object, except that it has an additional C datatype that can't be accessed from Ruby. As you can see in Figure 17.1 on page 177, this C datatype is separate from any instance variables that the object contains. But since it's a separate thing, how do you get rid of it when the garbage collector claims this object? What if you have to release some resource (close some file, clean up some lock or IPC mechanism, and so on)?

Figure not available...

In order to participate in Ruby's mark-and-sweep garbage collection process, you need to define a routine to free your structure, and possibly a routine to mark any references from your structure to other structures. Both routines take a `void` pointer, a reference to your structure. The mark routine will be called by the garbage collector during its ``mark'' phase. If your structure references other Ruby objects, then your mark function needs to identify these objects using `rb_gc_mark(value)`. If the structure doesn't reference other Ruby objects, you can simply pass `0` as a function pointer.

When the object needs to be disposed of, the garbage collector will call the free routine to free it. If you have allocated any memory yourself (for instance, by using `Data_Make_Struct`), you'll need to pass a free function---even if it's just the standard C library's `free` routine. For complex structures that you have allocated, your free function may need to traverse the structure to free all the allocated memory.

First a simple example, without any special handling. Given the structure definition

    typedef struct mp3info {
      char *title;
      char *artist;
      int  genre;
    } MP3Info;

we can create a structure, populate it, and wrap it as an object.[We cheat a bit in this example. Our `MP3Info` structure has a couple of `char` pointers in it. In our code we initialize them from two static strings. This means that we don't have to free these strings when the `MP3Info` structure is freed. If we'd allocated these strings dynamically, we'd have to write a free method to dispose of them.]

    MP3Info *p;
    VALUE info;

    p = ALLOC(MP3Info);
    p->artist = "Maynard Ferguson";
    p->title = "Chameleon";
    ...
    info = Data_Wrap_Struct(cTest, 0, free, p);

`info` is a `VALUE` type, a genuine Ruby object of class `Test` (represented in C by the built-in type `T_DATA`). You can push it onto an array, hold a reference to it in an object, and so on. At some later point in the code, we may want to access this structure again, given the `VALUE`:

    VALUE doit(VALUE info) {
      MP3Info *p;
      Data_Get_Struct(info, MP3Info, p);
      ...
      p->artist    -> "Maynard Ferguson"
      p->title     -> "Chameleon"
      ...
    }

In order to follow convention, however, you may need a few more things: support for an `initialize` method, and a ``C-constructor.'' If you were writing Ruby source, you'd allocate and initialize an object by calling `new`. In C extensions, the corresponding call is `Data_Make_Struct`. However, although this allocates memory for the object, it does not automatically call an `initialize` method; you need to do that yourself:

    info = Data_Make_Struct(cTest, MP3Info, 0, free, one);
    rb_obj_call_init(info, argc, argv);

This has the benefit of allowing subclasses in Ruby to override or augment the basic `initialize` in your class. Within `initialize`, it is allowable (but not necessarily advisable) to alter the existing data pointer, which may be accessed directly with `DATA_PTR(obj)`.

And finally, you may want to define a ``C-constructor''---that is, a globally available C function that will create the object in one convenient call. You can use this function within your own code or allow other extension libraries to use it. All of the built-in classes support this idea with functions such as `rb_str_new`, `rb_ary_new`, and so on. We can make our own:

    VALUE mp3_info_new() {
      VALUE info;
      MP3Info *one;
      info = Data_Make_Struct(cTest, MP3Info, 0, free, one);
      ...
      rb_obj_call_init(info, 0, 0);
      return info;
    }

### An Example

Okay, now we're ready for a full-size example. Given our vendor's header file above, we write the following code.

    #include "ruby.h"
    #include "cdjukebox.h"

    VALUE cCDPlayer;

    static void cd_free(void *p) {
      CDPlayerDispose(p);
    }

    static void progress(CDJukebox *rec, int percent)
    {
      if (rb_block_given_p()) {
        if (percent > 100) percent = 100;
        if (percent < 0) percent = 0;
        rb_yield(INT2FIX(percent));
      }
    }

    static VALUE
    cd_seek(VALUE self, VALUE disc, VALUE track)
    {
      CDJukebox *ptr;
      Data_Get_Struct(self, CDJukebox, ptr);

      CDPlayerSeek(ptr,
                   NUM2INT(disc),
                   NUM2INT(track),
                   progress);
      return Qnil;
    }

    static VALUE
    cd_seekTime(VALUE self)
    {
      double tm;
      CDJukebox *ptr;
      Data_Get_Struct(self, CDJukebox, ptr);
      tm = CDPlayerAvgSeekTime(ptr);
      return rb_float_new(tm);
    }

    static VALUE
    cd_unit(VALUE self)
    {
      return rb_iv_get(self, "@unit");
    }

    static VALUE
    cd_init(VALUE self, VALUE unit)
    {
      rb_iv_set(self, "@unit", unit);
      return self;
    }

    VALUE cd_new(VALUE class, VALUE unit)
    {
      VALUE argv[1];
      CDJukebox *ptr = CDPlayerNew(NUM2INT(unit));
      VALUE tdata = Data_Wrap_Struct(class, 0, cd_free, ptr);
      argv[0] = unit;
      rb_obj_call_init(tdata, 1, argv);
      return tdata;
    }

    void Init_CDJukebox() {
      cCDPlayer = rb_define_class("CDPlayer", rb_cObject);
      rb_define_singleton_method(cCDPlayer, "new", cd_new, 1);
      rb_define_method(cCDPlayer, "initialize", cd_init, 1);
      rb_define_method(cCDPlayer, "seek", cd_seek, 2);
      rb_define_method(cCDPlayer, "seekTime", cd_seekTime, 0);
      rb_define_method(cCDPlayer, "unit", cd_unit, 0);
    }

Now we have the ability to control our jukebox from Ruby in a nice, object-oriented manner:

    require "code/ext/CDJukebox"
    p = CDPlayer.new(1)
    puts "Unit is #{p.unit}"
    p.seek(3, 16) {|x| puts "#{x}% done" }
    puts "Avg. time was #{p.seekTime} seconds"

produces:

    Unit is 1
    26% done
    79% done
    100% done
    Avg. time was 1.2 seconds

This example demonstrates most of what we've talked about so far, with one additional neat feature. The vendor's library provided a callback routine---a function pointer that is called every so often while the hardware is grinding its way to the next disc. We've set that up here to run a code block passed as an argument to `seek`. In the `progress` function, we check to see if there is an iterator in the current context and, if there is, run it with the current percent done as an argument.

## Memory Allocation

You may sometimes need to allocate memory in an extension that won't be used for object storage---perhaps you've got a giant bitmap for a Bloom filter, or an image, or a whole bunch of little structures that Ruby doesn't use directly.

In order to work correctly with the garbage collector, you should use the following memory allocation routines. These routines do a little bit more work than the standard `malloc`. For instance, if `ALLOC_N` determines that it cannot allocate the desired amount of memory, it will invoke the garbage collector to try to reclaim some space. It will raise a `NoMemError` if it can't or if the requested amount of memory is invalid.

Memory Allocation
`type *` | `ALLOC_N(c-type, n")`
| Allocates n c-type objects, where c-type is the literal name of the C type, not a variable of that type.
`type *` | `ALLOC(c-type")`
| Allocates a c-type and casts the result to a pointer of that type.
`` | `REALLOC_N(var, c-type, n")`
| Reallocates n c-types and assigns the result to var, a pointer to a c-type.
`type *` | `ALLOCA_N(c-type, n")`
| Allocates memory for n objects of c-type on the stack---this memory will be automatically freed when the function that invokes `ALLOCA_N` returns.

## Creating an Extension

Having written the source code for an extension, we now need to compile it so Ruby can use it. We can either do this as a shared object, which is dynamically loaded at runtime, or statically link the extension into the main Ruby interpreter itself. The basic procedure is the same:

- Create the C source code file(s) in a given directory.
- Create `extconf.rb`.
- Run `extconf.rb` to create a `Makefile` for the C files in this directory.
- Run `make`.
- Run `make install`.

Figure not available...

### Creating a Makefile with extconf.rb

Figure 17.2 on page 182 shows the overall workflow when building an extension. The key to the whole process is the `extconf.rb` program which you, as a developer, create. In `extconf.rb`, you write a simple program that determines what features are available on the user's system and where those features may be located. Executing `extconf.rb` builds a customized `Makefile`, tailored for both your application and the system on which it's being compiled. When you run the `make` command against this `Makefile`, your extension is built and (optionally) installed.

The simplest `extconf.rb` may be just two lines long, and for many extensions this is sufficient.

    require 'mkmf'
    create_makefile("Test")

The first line brings in the `mkmf` library module (documented beginning on page 451). This contains all the commands we'll be using. The second line creates a `Makefile` for an extension called ``Test.'' (Note that ``Test'' is the name of the extension; the makefile will always be called ``Makefile.'') `Test` will be built from all the C source files in the current directory.

Let's say that we run this `extconf.rb` program in a directory containing a single source file, `main.c`. The result is a `Makefile` that will build our extension. On our system, this contains the following commands.

    gcc -fPIC -I/usr/local/lib/ruby/1.6/i686-linux -g -O2  \
      -c main.c -o main.o
    gcc -shared -o Test.so main.o -lc

The result of this compilation is `Test.so`, which may be dynamically linked into Ruby at runtime with ```require`''. See how the `mkmf` commands have located platform-specific libraries and used compiler-specific options automatically. Pretty neat, eh?

Although this basic program works for many simple extensions, you may have to do some more work if your extension needs header files or libraries that aren't included in the default compilation environment, or if you conditionally compile code based on the presence of libraries or functions.

A common requirement is to specify nonstandard directories where include files and libraries may be found. This is a two-step process. First, your `extconf.rb` should contain one or more `dir_config` commands. This specifies a tag for a set of directories. Then, when you run the `extconf.rb` program, you tell `mkmf` where the corresponding physical directories are on the current system.

If `extconf.rb` contains the line `dir_config(` name `)`, then you give the location of the corresponding directories with the command-line options:

`--with-name-include=directory`
  * Add directory/`include` to the compile command.
`--with-name-lib=directory`
  * Add directory/`lib` to the link command.

If (as is common) your include and library directories are both subdirectories of some other directory, and (as is also common) they're called `include` and `lib`, you can take a shortcut:

`--with-name-dir=directory`
  * Add directory/`lib` and directory/`include` to the link command and compile command, respectively.

There's a twist here. As well as specifying all these `--with` options when you run `extconf.rb`, you can also use the `--with` options that were specified when Ruby was built for your machine. This means you can find out the locations of libraries that are used by Ruby itself.

To make all this concrete, lets say you need to use libraries and include files for the CD jukebox we're developing. Your `extconf.rb` program might contain

    require 'mkmf'
    dir_config('cdjukebox')
    # .. more stuff
    create_makefile("CDJukeBox")

You'd then run `extconf.rb` with something like:

    % ruby extconf.rb --with-cdjukebox-dir=/usr/local/cdjb

The generated `Makefile` would assume that the libraries were in `/usr/local/cdjb/lib` and the include files were in `/usr/local/cdjb/include`.

The `dir_config` command adds to the list of places to search for libraries and include files. It does not, however, link the libraries into your application. To do that, you'll need to use one or more `have_library` or `find_library` commands.

`have_library` looks for a given entry point in a named library. If it finds the entry point, it adds the library to the list of libraries to be used when linking your extension. `find_library` is similar, but allows you to specify a list of directories to search for the library.

    require 'mkmf'
    dir_config('cdjukebox')
    have_library('cdjb', 'CDPlayerNew')
    create_makefile("CDJukeBox")

On some platforms, a popular library may be in one of several places. The X Window system, for example, is notorious for living in different directories on different systems. The `find_library` command will search a list of supplied directories to find the right one (this is different from `have_library`, which uses only configuration information for the search). For example, to create a `Makefile` that uses X Windows and a jpeg library, `extconf.rb` might contain

    require 'mkmf'

    if have_library("jpeg","jpeg_mem_init") and
       find_library("X11", "XOpenDisplay", "/usr/X11/lib",
                    "/usr/X11R6/lib", "/usr/openwin/lib")
    then
        create_makefile("XThing")
    else
        puts "No X/JPEG support available"
    end

We've added some additional functionality to this program. All of the `mkmf` commands return `false` if they fail. This means that we can write an `extconf.rb` that generates a `Makefile` only if everything it needs is present. The Ruby distribution does this so that it will try to compile only those extensions that are supported on your system.

You also may want your extension code to be able to configure the features it uses depending on the target environment. For example, our CD jukebox may be able to use a high-performance MP3 decoder if the end user has one installed. We can check by looking for its header file.

    require 'mkmf'
    dir_config('cdjukebox')
    have_library('cdjb', 'CDPlayerNew')
    have_header('hp_mp3.h')
    create_makefile("CDJukeBox")

We can also check to see if the target environment has a particular function in any of the libraries we'll be using. For example, the `setpriority` call would be useful but isn't always available. We can check for it with:

    require 'mkmf'
    dir_config('cdjukebox')
    have_func('setpriority')
    create_makefile("CDJukeBox")

Both `have_header` and `have_func` define preprocessor constants if they find their targets. The names are formed by converting the target name to uppercase and prepending ``HAVE_''. Your C code can take advantage of this using constructs such as:

    #if defined(HAVE_HP_MP3_H)
    #  include <hp_mp3.h>
    #endif

    #if defined(HAVE_SETPRIORITY)
      err = setpriority(PRIOR_PROCESS, 0, -10)
    #endif

If you have special requirements that can't be met with all these `mkmf` commands, your program can directly add to the global variables `$CFLAGS` and `$LFLAGS`, which are passed to the compiler and linker, respectively.

### Static Linking

Finally, if your system doesn't support dynamic linking, or if you have an extension module that you want to have statically linked into Ruby itself, edit the file `ext/Setup` in the distribution and add your directory to the list of extensions in the file, then rebuild Ruby. The extensions listed in `Setup` will be statically linked into the Ruby executable. If you want to disable any dynamic linking, and link all extensions statically, edit `ext/Setup` to contain the following option.

    option nodynamic

## Embedding a Ruby Interpreter

In addition to extending Ruby by adding C code, you can also turn the problem around and embed Ruby itself within your application. Here's an example.

    #include "ruby.h"

    main() {
      /* ... our own application stuff ... */
      ruby_init();
      ruby_script("embedded");
      rb_load_file("start.rb");
      while (1) {
        if (need_to_do_ruby) {
          ruby_run();
        }
        /* ... run our app stuff */
      }
    }

To initialize the Ruby interpreter, you need to call `ruby_init()`. But on some platforms, you may need to take special steps before that:

    #if defined(NT)
      NtInitialize(&argc, &argv);
    #endif
    #if defined(__MACOS__) && defined(__MWERKS__)
      argc = ccommand(&argv);
    #endif

See `main.c` in the Ruby distribution for any other special defines or setup needed for your platform.

Embedded Ruby API
`void` | `ruby_init(")`
| Sets up and initializes the interpreter. This function should be called before any other Ruby-related functions.
`void` | `ruby_options(int argc, char **argv")`
| Gives the Ruby interpreter the command-line options.
`void` | `ruby_script(char *name")`
| Sets the name of the Ruby script (and `$0`) to name.
`void` | `rb_load_file(char *file")`
| Loads the given file into the interpreter.
`void` | `ruby_run(")`
| Runs the interpreter.

You need to take some special care with exception handling; any Ruby calls you make at this top level should be protected to catch exceptions and handle them cleanly. `rb_protect`, `rb_rescue`, and related functions are documented on page 192.

For an example of embedding a Ruby interpreter within another program, see also `eruby`, which is described beginning on page 147.

## Bridging Ruby to Other Languages

So far, we've discussed extending Ruby by adding routines written in C. However, you can write extensions in just about any language, as long as you can bridge the two languages with C. Almost anything is possible, including awkward marriages of Ruby and C++, Ruby and Java, and so on.

But you may be able to accomplish the same thing without resorting to C code. For example, you could bridge to other languages using middleware such as CORBA or COM. See the section on Windows automation beginning on page 164 for more details.

## Ruby C Language API

Last, but by no means least, here are several C-level functions that you may find useful when writing an extension.

Some functions require an `ID`: you can obtain an `ID` for a string by using `rb_intern` and reconstruct the name from an `ID` by using `rb_id2name`.

As most of these C functions have Ruby equivalents that are already described in detail elsewhere in this book, the descriptions here will be brief.

Also note that the following listing is not complete. There are many more functions available---too many to document them all, as it turns out. If you need a method that you can't find here, check ```ruby.h`'' or ```intern.h`'' for likely candidates. Also, at or near the bottom of each source file is a set of method definitions that describe the binding from Ruby methods to C functions. You may be able to call the C function directly, or search for a wrapper function that calls the function you are looking for. The following list, based on the list in `README.EXT`, shows the main source files in the interpreter.

Ruby Language Core
  class.c error.c eval.c gc.c object.c parse.y variable.c
Utility Functions
  dln.c regex.c st.c util.c
Ruby Interpreter
  dmyext.c inits.c keywords main.c ruby.c version.c
Base Library
  array.c bignum.c compar.c dir.c enum.c file.c hash.c io.c marshal.c math.c numeric.c pack.c prec.c process.c random.c range.c re.c signal.c sprintf.c string.c struct.c time.c

Defining Objects
`VALUE` | `rb_define_class(char *name, VALUE superclass")`
| Defines a new class at the top level with the given name and superclass (for class `Object`, use `rb_cObject`).
`VALUE` | `rb_define_module(char *name")`
| Defines a new module at the top level with the given name.
`VALUE` | `rb_define_class_under(VALUE under, char *name, VALUE superclass")`
| Defines a nested class under the class or module under.
`VALUE` | `rb_define_module_under(VALUE under, char *name")`
| Defines a nested module under the class or module under.
`void` | `rb_include_module(VALUE parent, VALUE module")`
| Includes the given module into the class or module parent.
`void` | `rb_extend_object(VALUE obj, VALUE module")`
| Extends obj with module.
`VALUE` | `rb_require(const char *name")`
| Equivalent to ```require` name.'' Returns `Qtrue` or `Qfalse`.

In some of the function definitions that follow, the parameter argc specifies how many arguments a Ruby method takes. It may have the following values.

argc | Function prototype
0..17 | `VALUE func(VALUE self, VALUE arg...)`
| The C function will be called with this many actual arguments.
-1 | `VALUE func(int argc, VALUE *argv, VALUE self)`
| The C function will be given a variable number of arguments passed as a C array.
-2 | `VALUE func(VALUE self, VALUE args)`
| The C function will be given a variable number of arguments passed as a Ruby array.

In a function that has been given a variable number of arguments, you can use the C function `rb_scan_args` to sort things out (see below).

Defining Methods
`void` | `rb_define_method(VALUE classmod, char *name, VALUE(*func)(), int argc")`
| Defines an instance method in the class or module classmod with the given name, implemented by the C function func and taking argc arguments.
`void` | `rb_define_module_function(VALUE classmod, char *name, VALUE(*func)(), int argc)")`
| Defines a method in class classmod with the given name, implemented by the C function func and taking argc arguments.
`void` | `rb_define_global_function(char *name, VALUE(*func)(), int argc")`
| Defines a global function (a private method of `Kernel`) with the given name, implemented by the C function func and taking argc arguments.
`void` | `rb_define_singleton_method(VALUE classmod, char *name, VALUE(*func)(), int argc")`
| Defines a singleton method in class classmod with the given name, implemented by the C function func and taking argc arguments.
`int` | `rb_scan_args(int argcount, VALUE *argv, char *fmt, ...")`
| Scans the argument list and assigns to variables similar to `scanf`: fmt is a string containing zero, one, or two digits followed by some flag characters. The first digit indicates the count of mandatory arguments; the second is the count of optional arguments. A ``*'' means to pack the rest of the arguments into a Ruby array. A ``&'' means that an attached code block will be taken and assigned to the given variable (if no code block was given, `Qnil` will be assigned). After the fmt string, pointers to `VALUE` are given (as with `scanf`) to which the arguments are assigned.
    VALUE name, one, two, rest;
    rb_scan_args(argc, argv, "12", &name, &one, &two);
    rb_scan_args(argc, argv, "1*", &name, &rest);

`void` | `rb_undef_method(VALUE classmod, const char *name")`
| Undefines the given method name in the given classmod class or module.
`void` | `rb_define_alias(VALUE classmod, const char *newname, const char *oldname")`
| Defines an alias for oldname in class or module classmod.

Defining Variables and Constants
`void` | `rb_define_const(VALUE classmod, char *name, VALUE value")`
| Defines a constant in the class or module classmod, with the given name and value.
`void` | `rb_define_global_const(char *name, VALUE value")`
| Defines a global constant with the given name and value.

`void` | `rb_define_variable(const char *name, VALUE *object")`
| Exports the address of the given object that was created in C to the Ruby namespace as name. From Ruby, this will be a global variable, so name should start with a leading dollar sign. Be sure to honor Ruby's rules for allowed variable names; illegally named variables will not be accessible from Ruby.

`void` | `rb_define_class_variable(VALUE class, const char *name, VALUE val")`
| Defines a class variable name (which must be specified with a ```@@`'' prefix) in the given class, initialized to value.

`void` | `rb_define_virtual_variable(const char *name, VALUE(*getter)(), void(*setter)()")`
| Exports a virtual variable to Ruby namespace as the global $name. No actual storage exists for the variable; attempts to get and set the value will call the given functions with the prototypes:
    VALUE getter(ID id, VALUE *data,
                 struct global_entry *entry);
    void setter(VALUE value, ID id, VALUE *data,
                struct global_entry *entry);
You will likely not need to use the entry parameter and can safely omit it from your function declarations.

`void` | `rb_define_hooked_variable(const char *name, VALUE *variable, VALUE(*getter)(), void(*setter)()")`
| Defines functions to be called when reading or writing to variable. See also `rb_define_virtual_variable`.
`void` | `rb_define_readonly_variable(const char *name, VALUE *value")`
| Same as `rb_define_variable`, but read-only from Ruby.
`void` | `rb_define_attr(VALUE variable, const char *name, int read, int write")`
| Creates accessor methods for the given variable, with the given name. If read is nonzero, create a read method; if write is nonzero, create a write method.
`void` | `rb_global_variable(VALUE *obj")`
| Registers the given address with the garbage collector.

Calling Methods
`VALUE` | `rb_funcall(VALUE recv, ID id, int argc, ...")`
| Invokes the method given by id in the object recv with the given number of arguments argc and the arguments themselves (possibly none).
`VALUE` | `rb_funcall2(VALUE recv, ID id, int argc, VALUE *args")`
| Invokes the method given by id in the object recv with the given number of arguments argc and the arguments themselves given in the C array args.
`VALUE` | `rb_funcall3(VALUE recv, ID id, int argc, VALUE *args")`
| Same as `rb_funcall2`, but will not call private methods.

`VALUE` | `rb_apply(VALUE recv, ID name, int argc, VALUE args")`
| Invokes the method given by id in the object recv with the given number of arguments argc and the arguments themselves given in the Ruby `Array` args.
`ID` | `rb_intern(char *name")`
| Returns an `ID` for a given name. If the name does not exist, a symbol table entry will be created for it.
`char *` | `rb_id2name(ID id")`
| Returns a name for the given id.
`VALUE` | `rb_call_super(int argc, VALUE *args")`
| Calls the current method in the superclass of the current object.

Exceptions
`void` | `rb_raise(VALUE exception, const char *fmt, ...")`
| Raises an exception. The given string fmt and remaining arguments are interpreted as with `printf`.
`void` | `rb_fatal(const char *fmt, ...")`
| Raises a `Fatal` exception, terminating the process. No rescue blocks are called, but ensure blocks will be called. The given string fmt and remaining arguments are interpreted as with `printf`.
`void` | `rb_bug(const char *fmt, ...")`
| Terminates the process immediately---no handlers of any sort will be called. The given string fmt and remaining arguments are interpreted as with `printf`. You should call this function only if a fatal bug has been exposed. You don't write fatal bugs, do you?
`void` | `rb_sys_fail(const char *msg")`
| Raises a platform-specific exception corresponding to the last known system error, with the given msg.
`VALUE` | `rb_rescue(VALUE (*body)(), VALUE args, VALUE(*rescue)(), VALUE rargs")`
| Executes body with the given args. If a `StandardError` exception is raised, then execute rescue with the given rargs.
`VALUE` | `rb_ensure(VALUE(*body)(), VALUE args, VALUE(*ensure)(), VALUE eargs")`
| Executes body with the given args. Whether or not an exception is raised, execute ensure with the given rargs after body has completed.
`VALUE` | `rb_protect(VALUE (*body)(), VALUE args, int *result")`
| Executes body with the given args and returns nonzero in result if any exception was raised.
`void` | `rb_notimplement(")`
| Raises a `NotImpError` exception to indicate that the enclosed function is not implemented yet, or not available on this platform.
`void` | `rb_exit(int status")`
| Exits Ruby with the given status. Raises a `SystemExit` exception and calls registered exit functions and finalizers.
`void` | `rb_warn(const char *fmt, ...")`
| Unconditionally issues a warning message to standard error. The given string fmt and remaining arguments are interpreted as with `printf`.
`void` | `rb_warning(const char *fmt, ...")`
| Conditionally issues a warning message to standard error if Ruby was invoked with the `-w` flag. The given string fmt and remaining arguments are interpreted as with `printf`.

Iterators
`void` | `rb_iter_break(")`
| Breaks out of the enclosing iterator block.
`VALUE` | `rb_each(VALUE obj")`
| Invokes the `each` method of the given obj.
`VALUE` | `rb_yield(VALUE arg")`
| Transfers execution to the iterator block in the current context, passing arg as an argument. Multiple values may be passed in an array.
`int` | `rb_block_given_p(")`
| Returns true if `yield` would execute a block in the current context---that is, if a code block was passed to the current method and is available to be called.
`VALUE` | `rb_iterate(VALUE (*method)(), VALUE args, VALUE (*block)(), VALUE arg2")`
| Invokes method with argument args and block block. A `yield` from that method will invoke block with the argument given to `yield`, and a second argument arg2.
`VALUE` | `rb_catch(const char *tag, VALUE (*proc)(), VALUE value")`
| Equivalent to Ruby `catch`.
`void` | `rb_throw(const char *tag , VALUE value")`
| Equivalent to Ruby `throw`.

Accessing Variables
`VALUE` | `rb_iv_get(VALUE obj, char *name")`
| Returns the instance variable name (which must be specified with a ```@`'' prefix) from the given obj.
`VALUE` | `rb_ivar_get(VALUE obj, ID name")`
| Returns the instance variable name from the given obj.
`VALUE` | `rb_iv_set(VALUE obj, char *name, VALUE value")`
| Sets the value of the instance variable name (which must be specified with a ```@`'' prefix) in the given obj to value. Returns value.
`VALUE` | `rb_ivar_set(VALUE obj, ID name, VALUE value")`
| Sets the value of the instance variable name in the given obj to value. Returns value.
`VALUE` | `rb_gv_set(const char *name, VALUE value")`
| Sets the global variable name (the ```$`'' prefix is optional) to value. Returns value.
`VALUE` | `rb_gv_get(const char *name")`
| Returns the global variable name (the ```$`'' prefix is optional).
`void` | `rb_cvar_set(VALUE class, ID name, VALUE val")`
| Sets the class variable name in the given class to value.

`VALUE` | `rb_cvar_get(VALUE class, ID name")`
| Returns the class variable name from the given class.

`int` | `rb_cvar_defined(VALUE class, ID name")`
| Returns `Qtrue` if the given class variable name has been defined for class; otherwise, returns `Qfalse`.

`void` | `rb_cv_set(VALUE class, const char *name, VALUE val")`
| Sets the class variable name (which must be specified with a ```@@`'' prefix) in the given class to value.

`VALUE` | `rb_cv_get(VALUE class, const char *name")`
| Returns the class variable name (which must be specified with a ```@@`'' prefix) from the given class.

Object Status
`` | `OBJ_TAINT(VALUE obj")`
| Marks the given obj as tainted.
`int` | `OBJ_TAINTED(VALUE obj")`
| Returns nonzero if the given obj is tainted.
`` | `OBJ_FREEZE(VALUE obj")`
| Marks the given obj as frozen.
`int` | `OBJ_FROZEN(VALUE obj")`
| Returns nonzero if the given obj is frozen.
`` | `Check_SafeStr(VALUE str")`
| Raises `SecurityError` if current safe level > 0 and str is tainted, or a `TypeError` if str is not a `T_STRING`.
`int` | `rb_safe_level(")`
| Returns the current safe level.
`void` | `rb_secure(int level")`
| Raises `SecurityError` if level <= current safe level.
`void` | `rb_set_safe_level(int newlevel")`
| Sets the current safe level to newlevel.

Commonly Used Methods
`VALUE` | `rb_ary_new(")`
| Returns a new `Array` with default size.
`VALUE` | `rb_ary_new2(long length")`
| Returns a new `Array` of the given length.
`VALUE` | `rb_ary_new3(long length, ...")`
| Returns a new `Array` of the given length and populated with the remaining arguments.
`VALUE` | `rb_ary_new4(long length, VALUE *values")`
| Returns a new `Array` of the given length and populated with the C array values.
`void` | `rb_ary_store(VALUE self, long index, VALUE value")`
| Stores value at index in array self.
`VALUE` | `rb_ary_push(VALUE self, VALUE value")`
| Pushes value onto the end of array self. Returns value.
`VALUE` | `rb_ary_pop(VALUE self")`
| Removes and returns the last element from the array self.
`VALUE` | `rb_ary_shift(VALUE self")`
| Removes and returns the first element from the array self.
`VALUE` | `rb_ary_unshift(VALUE self, VALUE value")`
| Pushes value onto the front of array self. Returns value.
`VALUE` | `rb_ary_entry(VALUE self, long index")`
| Returns array self's element at index.
`int` | `rb_respond_to(VALUE self, ID method")`
| Returns nonzero if self responds to method.
`VALUE` | `rb_thread_create(VALUE (*func)(), void *data")`
| Runs func in a new thread, passing data as an argument.
`VALUE` | `rb_hash_new(")`
| Returns a new, empty `Hash`.
`VALUE` | `rb_hash_aref(VALUE self, VALUE key")`
| Returns the element corresponding to key in self.
`VALUE` | `rb_hash_aset(VALUE self, VALUE key, VALUE value")`
| Sets the value for key to value in self. Returns value.
`VALUE` | `rb_obj_is_instance_of(VALUE obj, VALUE klass")`
| Returns `Qtrue` if obj is an instance of klass.
`VALUE` | `rb_obj_is_kind_of(VALUE obj, VALUE klass")`
| Returns `Qtrue` if klass is the class of obj or class is one of the superclasses of the class of obj.
`VALUE` | `rb_str_new(const char *src, long length")`
| Returns a new `String` initialized with length characters from src.
`VALUE` | `rb_str_new2(const char *src")`
| Returns a new `String` initialized with the null-terminated C string src.
`VALUE` | `rb_str_dup(VALUE str")`
| Returns a new `String` object duplicated from str.
`VALUE` | `rb_str_cat(VALUE self, const char *src, long length")`
| Concatenates length characters from src onto the `String` self. Returns self.
`VALUE` | `rb_str_concat(VALUE self, VALUE other")`
| Concatenates other onto the `String` self. Returns self.
`VALUE` | `rb_str_split(VALUE self, const char *delim")`
| Returns an array of `String` objects created by splitting self on delim.

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.