ruby embedded into c++

I said that I would provide you with a skeleton which you freely can built upon, no credit is necessary.

Here it is [rubyembed-0.2.tar.gz]. I admit it looks overwhelming, there is not much functionality and its spread out over many different files! Be sure to read the [combining everything] section of this tutorial.

There is also a simplified version where all code is in one-file (less than 500 lines of code). Certain vital things has been left out. [main.cpp, test.rb, Makefile]. You may have to adjust the Makefile to your own environment.

Don't Use Wizard Code You Don't Understand [wizards?]. There is a few gotcha's in this code, therefore I have some explaining to do!

Lets start out with a real-world example (a typical behavier in a texteditor). This sequence-diagram shows the two most vital embedding-operations.

The following c++code is for the lefthand side (USER). Observe that the View class is undeclared, this is covered in the next section.

class ViewQT : public View {
public:
    void repaint() {
        cout << "repaint!" << endl;
    }
};

int main() {
    ViewQT v;
    v.insert();
    return 0;
}

The following ruby-code is for the righthand side (RUBY). Observe that the Redirect class is undeclared, this is covered in the next section.

class RubyView < Redirect
    def insert
        repaint
    end
end

Executing the above c++ code should output “repaint!” to stdout.

Calling in both directions (c++ <-> ruby) is important. But in order to do this some glue-code is necessary.

Connecting those two different worlds is what this tutorial is all about! The following diagram illustrates the necessary classes (template method pattern). Do not get too scared :-)

ViewQT is a c++ class which has implemented the repaint function. Its responsible for rendering itself as an QT widget.

RubyView is a ruby class which has implemented the insert function. Its responsible for inserting text into the buffer. When the text has been inserted it invokes repaint.

View serves as a baseclass for all c++ frontends. self holds one instance of the RubyView class.

Redirect serves as a baseclass for the ruby backend. With help of this class we are able to call the overloaded virtual function repaint in ViewQT. This class is memory-managed by ruby. Here we have a SWIG candidate!

If trouble strikes you might try these options:

In order to use ruby; We must as our first thing do proper initialization, and when done we perhaps want ruby to cleanup itself.

The usual startup procedure:

Less importance: There exist a couple of extra initialization functions (ruby_options). Is there others?

Defining our own environment:

We are up running. Here is our typical activities:

Finaly teardown everything we build:

So how can we secure us against this?

An example of such encapsulation could be following:

VALUE require_wrap(VALUE arg) {
    return rb_require("test");
}

VALUE require_protect() {
    int error;
    VALUE result = rb_protect(
        require_wrap, 0, &error);
    if(error) 
        throw;
    return result;
}

This will protect you from bad things:

error tells us if it were succesfully. Next section I will discuss how to deal with failures.

The error value returned from rb_protect, is zero if everything is OK. Otherwise there is something wrong which needs to be dealed with!

The following code will translate ruby-exceptions into c++exceptions.

void ThrowOnError(int error) {
    if(error == 0)
        return;

    VALUE lasterr = rb_gv_get("$!");

    // class
    VALUE klass = rb_class_path(CLASS_OF(lasterr));
    clog << "class = " << RSTRING(klass)->ptr << endl; 

    // message
    VALUE message = rb_obj_as_string(lasterr);
    clog << "message = " << RSTRING(message)->ptr << endl;

    // backtrace
    if(!NIL_P(ruby_errinfo)) {
        std::ostringstream o;
        VALUE ary = rb_funcall(
            ruby_errinfo, rb_intern("backtrace"), 0);
        int c;
        for (c=0; c<RARRAY(ary)->len; c++) {
            o << "\tfrom " << 
                RSTRING(RARRAY(ary)->ptr[c])->ptr << 
                "\n";
        }
        clog << "backtrace = " << o.str() << endl;
    }
    throw runtime_error("ruby_error");
}

The other way around, translating c++exceptions into ruby-exceptions is also possible [discussion]. Do you want backtraces? [unix, windows].

#define RUBY_TRY \
    extern VALUE ruby_errinfo; \
    ruby_errinfo = Qnil; \
    try

#define RUBY_CATCH \
    catch(const std::exception &e) { \
        std::ostringstream o; \
        o << "c++error: " << e.what(); \
        ruby_errinfo = rb_exc_new2( \
            rb_eRuntimeError, o.str().c_str()); \
    } catch(...) { \
        ruby_errinfo = rb_exc_new2( \
            rb_eRuntimeError, "c++error: Unknown error"); \
    } \
    if(!NIL_P(ruby_errinfo)) { \
        rb_exc_raise(ruby_errinfo); \
    }

Many answers regarding memory management can be found here [GC + MM].

ruby uses a garbage collection technique called mark-and-sweep, see [RubyGarden, IBM, GC-FAQ].

If you are holding ruby instances within c++, you must tell rubys garbage collector, that you are busy using them. Otherwise GC will destroy them, because they seems to be unused!

There is 2 ways to tell GC that a variable is busy. You can either choose to export or not to export your variable.

class Objects {
private:
    VALUE objects;
public:
    Objects() {
        objects = rb_ary_new();
        rb_gc_register_address(&objects);
    }
    ~Objects() {
        // dispose array and flush all elements
        rb_gc_unregister_address(&objects);
        /*      
        mass destruction. GC can no longer
        mark the elements in the Array and 
        therefore they will all get swept.
        */
    }
    void Register(VALUE object) {
        rb_ary_push(objects, object);
    }
    void Unregister(VALUE object) {
        rb_ary_delete(objects, object);
    }
};

VALUE cats_alloc(VALUE klass) {
    return Data_Wrap_Struct(
        klass, 
        cats_mark, 
        cats_free, 
        new Cats()
    );
}

Threads in ruby can be used as usual.

Thread.new do
    loop do
        puts "."
        sleep 0.5
    end
end

The only thing you should care about is: In libc, the setitimer() function plus the SIGVTALRM signal is used by ruby to schedule threads. Messing around with these things, will get you in trouble.

ruby is not thread-safe. If you embed ruby into a multi-threaded application then you will need to semaphore protect all access to ruby. Warning: Insufficient semaphore protection can be hard debuggable.

Useful hints, what to do, and not to do.

Getting started in a rush? My best advice is to look at the ruby source itself, plus seek inspiration in projects which successfully has embedded ruby.

Projects which is less educational (secondary).

If you can recommend other resources about embedding I would be glad to add it.

I think usage of global variables is nasty, but thats just me. In order to create an instance of RubyView, we must use such dirty tricks.

Impl(View *parent) : parent(parent) {
    // create instance
    Redirect::SetView(parent);
    self = RUBY_CPP::New("RubyView");

    // tell GC
    objects->Register(self);
}

Creating an instance. How is this code working?

In an perfect world, we would have passed the parent variable to RubyView.new which then would pass it further to Redirect.ctor. But the world is unfortunatly not perfect and therefore its sometimes necessary to use global variables.

Why is it necessary to transfer arguments in such ackward way? todo:

Less importance but nice to know.

You might want to extend/adjust this code further for your own requirements. I will try to cover how to add new features.

Most people think that SWIG can be used ONLY for ruby extensions. But if you are clever you can actual use it for embedding.

I hope you have made it this far without too many bumps on the road. Now enjoy life :-)

Over and out - Simon Strandgaard.