Rice  1.5.2
 All Classes Files Functions Variables Typedefs Friends Pages
Rice - Ruby Interface for C++ Extensions

Introduction

Rice is a C++ interface to Ruby's C API. It provides a type-safe and exception-safe interface in order to make embedding Ruby and writing Ruby extensions with C++ easier. It is similar to Boost.Python in many ways, but also attempts to provide an object-oriented interface to all of the Ruby C API.

What Rice gives you:

Project Details

The source is hosted on github: http://github.com/jasonroelofs/rice

Bug tracking: http://github.com/jasonroelofs/rice/issues

Mailing List: rice@.nosp@m.libr.nosp@m.elist.nosp@m..com (your first email will be used as a subscription request and dropped)

Installation

gem install rice

Building it locally from a clone of the repository is as follows:

./bootstrap
ruby extconf.rb
make

Rice is known to work on *nix and OSX. Windows is not currently supported.

Rice does not work with any Ruby compiled with the Falcon performans patches as they make changes to some internals which Rice relies on.

Also Rice requires a Ruby built with –enable-shared and will not install properly against a Ruby with only static libraries.

Tutorial

Getting started

Writing an extension with Rice is very similar to writing an extension with the C API.

The first step is to create an extconf.rb file:

require 'mkmf-rice'
create_makefile('test')

Note that we use mkmf-rice instead of mkmf. This will ensure that the extension will be linked with standard C++ library along with the Rice library, and allow access to the Rice header files.

Next we create our extension and save it to test.cpp:

extern "C"
void Init_Test()
{
}

Note the extern "C" line above. This tells the compiler that the function Init_Test should have C linkage and calling convention. This turns off name mangling so that the Ruby interpreter will be able to find the function (remember that Ruby is written in C, not C++).

So far we haven't put anything into the extension, so it isn't particularly useful. The next step is to define a class so we can add methods to it.

Defining clases

Defining a class in Rice is easy:

#include "rice/Class.hpp"
using namespace Rice;
extern "C"
void Init_Test()
{
Class rb_cTest = define_class("Test");
}

This will create a class called Test that inherits from Object. If we wanted to inherit from a different class, we could easily do so:

#include "rice/Class.hpp"
using namespace Rice;
extern "C"
void Init_Test()
{
Class rb_cMySocket = define_class("MySocket", rb_cIO);
}

Note the prefix rb_c on the name of the class. This is a convention that the Ruby interpreter and many extensions tend to use. It signifies that this is a class and not some other type of object. Some other naming conventions that are commonly used:

Also note that we don't include "ruby.h" directly. Rice has a wrapper for ruby.h that handles some compatibility issues across platforms and Ruby versions. Always include Rice headers before including anything that might include "ruby.h".

Defining methods

Now let's add a method to our class:

#include "rice/Class.hpp"
#include "rice/String.hpp"
using namespace Rice;
Object test_hello(Object /* self */)
{
String str("hello, world");
return str;
}
extern "C"
void Init_Test()
{
Class rb_cTest =
define_class("Test")
.define_method("hello", &test_hello);
}

Here we add a method Test::hello that simply returns the string "Hello, World". The method takes self as an implicit parameter, but isn't used, so we comment it out to prevent a compiler warning.

We could also add an #initialize method to our class:

#include "rice/Class.hpp"
#include "rice/String.hpp"
using namespace Rice;
Object test_initialize(Object self)
{
self.iv_set("@foo", 42);
}
Object test_hello(Object /* self */)
{
String str("hello, world");
return str;
}
extern "C"
void Init_Test()
{
Class rb_cTest =
define_class("Test")
.define_method("initialize", &test_initialize);
.define_method("hello", &test_hello);
}

The initialize method sets an instance variable to the value 42. The number is automatically converted to a Fixnum before doing the assignment.

Note that we're chaining calls on the Class object. Most member functions in Module and Class return a reference to self, so we can chain as many calls as we want to define as many methods as we want.

Wrapping C++ Types

It's useful to be able to define Ruby classes in a C++ style rather than using the Ruby API directly, but the real power Rice is in wrapping already-defined C++ types.

Let's assume we have the following C++ class that we want to wrap:

class Test
{
public:
Test();
std::string hello();
};

This is a C++ version of the Ruby class we just created in the previous section. To wrap it:

#include "rice/Data_Type.hpp"
#include "rice/Constructor.hpp"
using namespace Rice;
extern "C"
void Init_Test()
{
Data_Type<Test> rb_cTest =
define_class<Test>("Test")
.define_constructor(Constructor<Test>())
.define_method("hello", &Test::hello);
}

This example is similar to the one before, but we use Data_Type<> instead of Class and the template version of define_class() instead of the non-template version. This creates a binding in the Rice library between the Ruby class Test and the C++ class Test, so that we pass member function pointers to define_method() and have conversions be done automatically.

It's possible to write the conversion functions ourself (as we'll see below), but Rice does all the dirty work for us.

Type conversions

Let's look again at our example class:

class Test
{
public:
Test();
std::string hello();
};

When we wrote our class, we never wrote a single line of code to convert the std::string returned by hello() into a Ruby type. Neverthless, the conversion works, and when we write:

test = Test.new
puts test.hello

We get the expected result.

Rice has two template conversion functions to convert between C++ and Ruby types:

template<typename T>
T from_ruby(Object x);
template<typename T>
Object to_ruby(T const & x);

Rice has included by default specializations for many of the builtin types. To define your own conversion, you can write a specialization:

template<>
Foo from_ruby<Foo>(Object x)
{
// ...
}
template<>
Object to_ruby<Foo>(Foo const & x)
{
// ...
}

The implementation of these functions would, of course, depend on the implementation of Foo.

Conversions for wrapped C++ types

Take another look at the wrapper we wrote for the Test class:

extern "C"
void Init_Test()
{
Data_Type<Test> rb_cTest =
define_class<Test>("Test")
.define_constructor(Constructor<Test>())
.define_method("hello", &Test::hello);
}

When we called define_class<Test>, it created a Class for us and automatically registered the new Class with the type system, so that the calls:

Data_Object<Foo> obj(new Foo);
Foo * f = from_ruby<Foo *>(obj);
Foo const * f = from_ruby<Foo const *>(obj);

work as expected.

The Data_Object class is a wrapper for the Data_Wrap_Struct and the Data_Get_Struct macros in C extensions. It can be used to wrap or unwrap any class that has been assigned to a Data_Type. It inherits from Object, so any member functions we can call on an Object we can also call on a Data_Object:

Object object_id = obj.call("object_id");
std::cout << object_id << std::endl;

The Data_Object class can be used to wrap a newly-created object:

Data_Object<Foo> foo(new Foo);

or to unwrap an already-created object:

VALUE obj = ...;
Data_Object<Foo> foo(obj);

A Data_Object functions like a smart pointer:

Data_Object<Foo> foo(obj);
foo->foo();
std::cout << *foo << std::endl;

Like a VALUE or an Object, data stored in a Data_Object will be marked by the garbage collector as long as the Data_Object is on the stack.

Exceptions

Suppose we added a member function to our example class that throws an exception:

class MyException
: public std::exception
{
};
class Test
{
public:
Test();
std::string hello();
void error();
};

If we were to wrap this function:

extern "C"
void Init_Test()
{
Data_Type<Test> rb_cTest =
define_class<Test>("Test")
.define_constructor(Constructor<Test>())
.define_method("hello", &Test::hello)
.define_method("error", &Test::error);
}

and call it from inside Ruby:

test = Test.new
test.error()

we would get an exception. Rice will automatically convert any C++ exception it catches into a Ruby exception. But what if we wanted to use a custom eror message when we convert the exception, or what if we wanted to convert to a different type of exception? We can write this:

extern "C"
void Init_Test()
{
Data_Type<Test> rb_cTest =
define_class<Test>("Test")
.add_handler<MyException>(handle_my_exception)
.define_constructor(Constructor<Test>())
.define_method("hello", &Test::hello)
.define_method("error", &Test::error);
}

The handle_my_exception function need only rethrow the exception as a Rice::Exception:

void handle_my_exception(MyException const & ex)
{
throw Exception(rb_eRuntimeError, "Goodnight, moon");
}

And what if we want to call Ruby code from C++? These exceptions are also converted:

Object o;
o.call("some_function_that_raises", 42);
protect(rb_raise, rb_eRuntimeError, "some exception msg");

Internally whenever Rice catches a C++ or a Ruby exception, it converts it to an Exception object. This object will later be re-raised as a Ruby exception when control is returned to the Ruby VM.

Rice uses a similar class called Jump_Tag to handle symbols thrown by Ruby's throw/catch or other non-local jumps from inside the Ruby VM.

Builtin types

You've seen this example:

Object object_id = obj.call("object_id");
std::cout << object_id << std::endl;

Rice mimics the Ruby class hierarchy as closely as it can given that C++ is statically typed. In fact, the above code also works for Classes:

Class rb_cTest = define_class<Test>("Test");
Object object_id = rb_cTest.call("object_id");
std::cout << object_id << std::endl;

Rice provides builtin wrappers for many builtin Ruby types, including:

The Array and Hash types can even be iterated over the same way one would iterate over an STL container:

Array a;
a.push(to_ruby(42));
a.push(to_ruby(43));
a.push(to_ruby(44));
Array::iterator it = a.begin();
Array::iterator end = a.end();
for(; it != end; ++it)
{
std::cout << *it << std::endl;
}

STL algorithms should also work as expected on Array and Hash containers.

Inheritance

Inheritance is a tricky problem to solve in extensions. This is because wrapper functions for base classes typically don't know how to accept pointers to derived classes. It is possible to write this logic, but the code is nontrivial.

Forunately Rice handles this gracefully:

class Base
{
public:
virtual void foo();
};
class Derived
: public Base
{
};
extern "C"
void Init_Test()
{
Data_Type<Base> rb_cBase =
define_class<Base>("Base")
.define_method("foo", &Base::foo);
Data_Type<Derived> rb_cDerived =
define_class<Derived, Base>("Derived");
}

The second template parameter to define_class indicates that Derived inherits from Base.

Rice does not yet support multiple inheritance, but it is believed that this is possible through the use of mixins.

Overloaded functions

If you try to create a member function pointer to an overloaded function, you will get an error. So how do we wrap classes that have overloaded functions?

Consider a class that uses this idiom for accessors:

class Container
{
size_t capacity(); // Get the capacity
void capacity(size_t cap); // Set the capacity
};

We can wrap this class by using typedefs:

extern "C"
void Init_Container()
{
typedef size_t (Container::*get_capacity)();
typedef void (Container::*set_capacity)(size_t);
Data_Type<Container> rb_cContainer =
define_class<Container>("Container")
.define_method("capacity", get_capacity(&Container::capacity))
.define_method("capacity=", set_capacity(&Container::capacity))
}

A future version of Rice may provide a simplified interface for this.

User-defined type conversions

Rice provides default conversions for many built-in types. Sometimes, however, the default conversion is not their right conversion. For example, consider a function:

void foo(char * x);

Is x a pointer to a single character or a pointer to the first character of a null-terminated string or a pointer to the first character of an array of char?

Because the second case is the most common use case (a pointer to the first character of a C string), Rice provides a default conversion that treats a char * as a C string. But suppose the above function takes a pointer to a char instead?

If we write this:

extern "C"
void Init_Test()
{
define_global_function("foo", &foo);
}

It will likely have the wrong behavior.

To avoid this problem, it is necessary to write a wrapper function:

Object wrap_foo(Object o)
{
char c = from_ruby<char>(o);
foo(&c);
return to_ruby(c);
}
extern "C"
void Init_Test()
{
define_global_function("foo", &wrap_foo);
}

Note that the out parameter is returned from wrap_foo, as Ruby does not have pass-by-variable-reference (it uses pass-by-object-reference).

Future versions of Rice will have a cleaner way of dealing with this.

Default Arguments

Going back to our initial C++ class example, lets say that hello() now take a few arguments for what to return, one which has a default value:

class Test
{
public:
Test();
std::string hello(std::string first, std::string second = "world");
};

As default parameter information is not available through templates, it's necessary to define this in Rice explicitly using Rice::Arg:

#include "rice/Data_Type.hpp"
#include "rice/Constructor.hpp"
using namespace Rice;
extern "C"
void Init_Test()
{
Data_Type<Test> rb_cTest =
define_class<Test>("Test")
.define_constructor(Constructor<Test>())
.define_method("hello",
&Test::hello,
(Arg("hello"), Arg("second") = "world")
);
}

The syntax here is simply Arg(nameOfParameter)[ = defaultValue]. The name of the parameter is not important (more for readability, and the future for when/if Ruby gets named parameters), but the value set via operator= must match the type of the given parameter.

These Rice::Arg objects must be in the correct order, and if there are more than one of them they must be surrounded in parentheses, as above, or the compilation will fail.

It may be required to explicitly cast the default argument values to their appropriate types:

.define_method("hello",
&Test::hello,
(Arg("hello"), Arg("second") = (std::string)"world")
);

With this, Ruby will now know about the default arguments, and this wrapper can be used as expected:

t = Test.new
t.hello("hello")
t.hello("goodnight", "moon")

This will also work with Constructors:

.define_constructor(Constructor<SomeClass, int, int>(),
( Arg("arg1") = 1, Arg("otherArg") = 12 );

Director

As polymorphism is the most important tennant of Object Oriented Programming, it's important that Rice supports polymorphic calls travelling between C++ and Ruby seemlessly. Super calls from Ruby subclasses back into C++ already work, but enabling the other direction requires some extra work. While this isn't something Rice can do on it's own, the Rice::Director class, coupled with Rice::Data_Type::define_director exposes this functionality cleanly.

Like SWIG_Director, Rice::Director is a class that is used to build a proxy class to properly send execution up or down the object heiarchy for that class. Take the following class:

class VirtualBase {
public:
VirtualBase();
virtual int doWork();
virtual int processWorker() = 0;
};

Due to the abstract nature of this class, it will not work at all with Rice in it's current form. Any attempt to do so will cause a compilation error due to this class not being constructable. Even without the pure virtual function, any call to VirtualBase::doWork will stop at the C++ level and will not pass down into any Ruby subclasses.

To properly wrap both of these methods, you'll need to build a proxy class that subclasses Rice::Director along with a few methods:

#include "rice/Director.hpp"
class VirtualBaseProxy : public VirtualBase, public Rice::Director {
public:
VirtualBaseProxy(Object self) : Rice::Director(self) { }
virtual int doWork() {
return from_ruby<int>( getSelf().call("do_work") );
}
int default_doWork() {
return VirtualBase::doWork();
}
virtual int processWorker() {
return from_ruby<int>( getSelf().call("process_worker") );
}
int default_processWorker() {
}
};

There is a lot going on here, so we'll go through each part.

class VirtualBaseProxy : public Virtualbase, public Rice::Director {

First, the class needs to subclass both the virtual class and Rice::Director class.

public:
VirtualBaseProxy(Object self) : Rice::Director(self) { }

For Rice::Director to work its magic, every instance of this class needs to have a handle to the Ruby instance of this class as well. The constructor must take a Rice::Object as the first argument, then any other arguments follow and should be passed back to the superclass as needed. The code here is the minimum required for a Rice::Director proxy.

virtual int doWork() {
return from_ruby<int>( getSelf().call("do_work") );
}
int default_doWork() {
return VirtualBase::doWork();
}

The two methods seen here directly correspond to the two code directions this class opens up. The virtual method is this class's hook into C++'s polymorphism. Any calls that need to be forwarded into Ruby are done as specified here: get the Ruby object for the instance of this class, call Rice::Object::call, and if necessary convert the return value from Ruby back into C++ types.

The default_doWork method will be used as Rice's hookup of calling back up the heirarchy (wrapping is below). This method needs to do one of two things: call up the class heirarchy, as seen here, or call raisePureVirtual() as seen in the processWorker example:

int default_processWorker() {
raisePureVirtual();
}

The method raisePureVirtual() exists to allow wrapping a pure virtual method into Ruby but making sure any users of this extension are informed quickly that there's nothing in the C++ to call for the given method.

Once the proxy class is built, it's time to wrap it into Ruby:

extern "C"
void Init_virtual() {
define_class<VirtualBase>("VirtualBase")
.define_director<VirtualBaseProxy>()
.define_constructor(Constructor<VirtualBaseProxy, Rice::Object>())
.define_method("do_work", &VirtualBaseProxy::default_doWork)
.define_method("process_worker", &VirtualBaseProxy::default_processWorker);
}

The wrapping is the same as is described earlier in this document. Expose the class VirtualBase, and register VirtualBaseProxy as a director proxy of VirtualBase with Rice::Data_Type::define_director, then define methods pointing to the proxy object as necessary.

You must use the Rice::Director proxy class in the Constructor line, this allows proper object construction / destruction of the types in question.

Implicit Casting

There are times when a library exposes classes that while unrelated are built to be interchangeable across the library. One example of this, taken from the Open Source 3d rendering engine OGRE, are the Degree and Radian classes. When a given method takes a Radian, you're free to pass in a Degree, and vice versa.

Rice cannot automatically figure out if this kind of functionality is possible in a given library but it does have a simple API for defining these relationships: Rice::define_implicit_cast<From, To>().

class Degree { ... };
class Radian { ... };
extern "C"
void Init_implicit() {
define_class<Degree>()
...;
define_class<Radian>()
...;
define_implicit_cast<Degree, Radian>();
define_implicit_cast<Radian, Degree>();
}

This support is still being fleshed out and has a few requirements for proper use:

To see a full example of this feature, please check out test/test_Data_Type.cpp.

Motivation

There are a number of common problems when writing C or C++ extensions for Ruby:

Rice addresses these issues in many ways:

What Rice is Not

There are a number projects which server similar functions to Rice. Two such popular projects are SWIG and Boost.Python. Rice has some distinct features which set it apart from both of these projects.

Rice is not trying to replace SWIG. Rice is not a generic wrapper interface generator. Rice is a C++ library for interfacing with the Ruby C API. This provides a very natural way for C++ programmers to wrap their C++ code, without having to learn a new domain-specific language. However, there is no reason why SWIG and Rice could not work together; a SWIG module could be written to generate Rice code. Such a module would combine the portability of SWIG with the maintainability of Rice (I have written extensions using both, and I have found Rice extensions to be more maintainable when the interface is constantly changing. Your mileage may vary).

Rice is also not trying to simply be a Ruby version of Boost.Python. Rice does use some of the same template tricks that Boost.Python uses, however there are some important distinctions. First of all, Boost.Python attempts to create a declarative DSL in C++ using templates. Rice is a wrapper around the Ruby C API and attempts to make its interface look like an OO version of the API; this means that class declarations look procedural rather than declarative. Secondly, the Ruby object model is different from the python object model. This is reflected in the interface to Rice; it mimics the Ruby object model at the C++ level. Thirdly, Rice uses Ruby as a code generator; I find this to be much more readable than using the Boost preprocessor library.

History

Rice originated as a project to interface with C++-based trading software at Automated Trading Desk in Mount Pleasant, South Carolina. The Ruby bindings for Swig were at the time less mature than they are today, and did not suit the needs of the project.

Excruby was written not as a wrapper for the Ruby API, but rather as a set of helper functions and classes for interfacing with the Ruby interpreter in an exception-safe manner. Over the course of five years, the project grew into wrappers for pieces of the API, but the original helper functions remained as part of the public interface.

This created confusion for the users of the library, because there were multiple ways of accomplishing most tasks – directly through the C API, through a low-level wrapper around the C API, and through a high-level abstraction of the lower-level interfaces.

Rice was then born in an attempt to clean up the interface. Rice keeps the lower-level wrappers, but as an implementation detail; the public interface is truly a high-level abstraction around the Ruby C API.

The GC

Embedding

You can embed the Ruby interpter in your application by using the VM class:

int main(int argc, char * argv[])
{
Rice::VM vm(argc, argv);
vm.run()
}

If the VM is not initialized from main() – from a callback, for example – then you may need to initialize the stack whenever you use Rice or the Ruby API:

std::auto_ptr<Rice::VM> vm;
void some_application_extension_init()
{
vm.reset(new Rice::VM("some_application"));
}
void some_application_extension_callback()
{
// Need to initialize the stack here, because we don't know if
// we are at the same stack depth as when the VM was initialized
vm->init_stack();
// Now do some work...
obj->call("some_callback_function")
}

Be aware that initializing the Ruby VM can cause a call to exit() if certain command-line options are specified. This has two implications: