DEV Community: Ulysse Buonomo

Calling Ruby Methods in C: Avoid Memory Leaks

Ulysse Buonomo — Wed, 01 Feb 2023 11:43:30 +0000

Memory leaks are a pain for gem users. They are hard to track and can lead to expensive infrastructure costs.

Memory leaks within a C extension are even worse. You'll see a lot of tools and articles about finding leaks in Ruby. However, you don't have the same access to internals in C.

A naive usage of rb_funcall can cause memory leaks: it's much better to use rb_protect instead. So, if you are a C extension writer, please read on for the sake of developers who will use your gem.

Let's get started!

The Issue with `rb_funcall` and C

rb_funcall can be a great tool when you need to interact between Ruby and the C parts of your library but only need to write a little C.

However, when you run rb_funcall, you are no longer in C where everything is straightforward. You can be left in muddy waters if the called function:

Completely changes its definition during runtime
Raises a call

Number 1 is the easiest one to catch. You'll likely end up with a segfault, and if your test suite is complete enough, you should catch that before publishing.

However, the latter can cause memory leaks and make your codebase way harder to read. Let's take a look at that now.

Raise in Ruby Causing C Memory Leaks

Ruby's raising mechanism jumps between parts of the code from one scope to the first parent that catches an error. This is implemented in the MRI using longjmp and setjmp.

If you are interested in how this is built, read the Evaluator chapter in the Ruby Hacking Guide. In a nutshell, when you use a begin..ensure block, you setjmp(), and when you raise within this block, you longjmp() to the saved position.

So if a function is raised with rb_funcall, the C code called after it never executes.

The example below illustrates a potential leak. If json_parse raises, it will leak.

VALUE rb_create_geometry_hash(VALUE self, VALUE wkt) {
    // Alloc
    GEOSWKTReader* reader = GEOSWKTReader_create();
    GEOSGeoJSONWriter* writer = GEOSGeoJSONWriter_create();

    // C processing
    GEOSGeometry* geom = GEOSWKTReader_read(reader, StringValuePtr(wkt));
    char* geojson = GEOSGeoJSONWriter_writeGeometry(writer, geom, -1);

    // Ruby processing
    VALUE rb_geojson = rb_str_new_cstr(geojson);
    VALUE result = rb_funcall(self, rb_intern("json_parse"), 1, rb_geojson);

    // Free
    GEOSWKTReader_destroy(reader);
    GEOSGeom_destroy(geom);
    GEOSGeoJSONWriter_destroy(writer);
    GEOSFree(geojson);

    return result;
}

Of course, the example above is a bit silly — you could invert the freeing and Ruby processing parts. However, this is not always possible, and longer function bodies can become more intertwined.

Using `begin..ensure` in Ruby

If you're using Ruby, you could instead write the above example using begin..ensure:

def create_geometry_hash(wkt)
    reader = GEOSWKTReader.new
    writer = GEOSGeoJSONWriter.new

    begin
        json_parse(writer.write(reader.read(wkt)))
    ensure
        reader.close
        writer.close
    end
end

This API is also available in C with rb_rescue and rb_ensure:

static VALUE try_ruby_processing(VALUE args) {
    char* geojson = (char*)args;
    // Ruby processing
    VALUE rb_geojson = rb_str_new_cstr(geojson);
    VALUE result = rb_funcall(self, rb_intern("json_parse"), 1, rb_geojson);
}

struct to_free {
    GEOSWKTReader* reader;
    GEOSGeoJSONWriter* writer;
    GEOSGeometry* geom;
    char* geojson;
};

static VALUE ensure_free(VALUE args) {
    struct to_free data = (struct to_free)args
    GEOSWKTReader_destroy(data.reader);
    GEOSGeom_destroy(data.geom);
    GEOSGeoJSONWriter_destroy(data.writer);
    GEOSFree(data.geojson);

}

VALUE rb_create_geometry_hash(VALUE self, VALUE wkt) {
    // Alloc
    GEOSWKTReader* reader = GEOSWKTReader_create();
    GEOSGeoJSONWriter* writer = GEOSGeoJSONWriter_create();

    // C processing
    GEOSGeometry* geom = GEOSWKTReader_read(reader, StringValuePtr(wkt));
    char* geojson = GEOSGeoJSONWriter_writeGeometry(writer, geom, -1);

    return rb_ensure(
        try_ruby_processing, (VALUE)geojson
        ensure_free, (struct to_free){ reader, writer, geom, geojson }
    );

    return result;
}

However, this is a bit cumbersome, and if you want to add a rescue block to the party, it gets way less readable. I suggest reading Peter Zhu's 'A Rubyist's Walk Along the C-side (Part 8): Exceptions & Error Handling' if you want to use the begin..rescue..ensure..end API in C.

Using `rb_protect` for C

There is another option. First, let's see how it could look in Ruby:

def create_geometry_hash(wkt)
    reader = GEOSWKTReader.new
    writer = GEOSGeoJSONWriter.new

    err = nil
    result = nil
    begin
        result = json_parse(writer.write(reader.read(wkt)))
    rescue => e
        err = e
    end

    reader.close
    writer.close

    raise err if err

    result
end

This looks strange in Ruby, but is a workflow very well suited to C. The MRI has an API for that, rb_protect, and the C function looks like this:

VALUE ruby_call(VALUE rb_geojson) {
    return rb_funcall(self, rb_intern("json_parse"), 1, rb_geojson);
}

VALUE rb_create_geometry_hash(VALUE self, VALUE wkt) {
    int state;

    // Alloc
    GEOSWKTReader* reader = GEOSWKTReader_create();
    GEOSGeoJSONWriter* writer = GEOSGeoJSONWriter_create();

    // C processing
    GEOSGeometry* geom = GEOSWKTReader_read(reader, StringValuePtr(wkt));
    char* geojson = GEOSGeoJSONWriter_writeGeometry(writer, geom, -1);

    // Ruby processing
    VALUE rb_geojson = rb_str_new_cstr(geojson);
    rb_protect(ruby_call, rb_geojson, &state);

    // Free
    GEOSWKTReader_destroy(reader);
    GEOSGeom_destroy(geom);
    GEOSGeoJSONWriter_destroy(writer);
    GEOSFree(geojson);

    if (state) rb_jump_tag(state);

    return result;
}

The above method will re-raise a Ruby error after having freed everything.

Note that we could also choose to ignore the error by using an empty rescue block in Ruby:

    ...

    if (state) rb_set_errinfo(Qnil);

    return result; // => nil
}

Warning: If you do not raise the error, the rb_set_errinfo(Qnil) step is important so you don't keep information available about an error that users should not know about.

Or, you can conditionally choose to raise an error, like rescue My::Error:

    ...

    if (state) {
        if (rb_obj_is_kind_of(rb_errinfo(), rb_define_class_under(rb_mMy, "Error", rb_eStandardError))) {
            rb_jump_tag(state);
        } else {
            rb_set_errinfo(Qnil);
        }
    }

    return result;
}

You can actually consider rb_errinfo() as the same as the $! global variable.

This is all great, but when it boils down to one rb_funcall only, we can simplify that API.

The overall idea behind using the rb_protect API when there is a function to raise is to enhance readability. You don't need to check if the function can raise or not, you assume it can, and use the state to work with that.

The `rb_protect_funcall` Proposal

Let's isolate rb_funcall, as it's the only dangerous method to use. Here's an API that will do that:

VALUE rb_protect_funcall(VALUE recv, ID mid, int* state, int n, ...);

This API is the same as rb_funcall, with a state from rb_protect. Hence the usage is pretty straightforward:

VALUE rb_create_geometry_hash(VALUE self, VALUE wkt) {
    int state;

    // Alloc
    GEOSWKTReader* reader = GEOSWKTReader_create();
    GEOSGeoJSONWriter* writer = GEOSGeoJSONWriter_create();

    // C processing
    GEOSGeometry* geom = GEOSWKTReader_read(reader, StringValuePtr(wkt));
    char* geojson = GEOSGeoJSONWriter_writeGeometry(writer, geom, -1);

    // Ruby processing
    VALUE rb_geojson = rb_str_new_cstr(geojson);
    rb_protect_funcall(self, rb_intern("json_parse"), &state, 1,  rb_geojson);

    // Free
    GEOSWKTReader_destroy(reader);
    GEOSGeom_destroy(geom);
    GEOSGeoJSONWriter_destroy(writer);
    GEOSFree(geojson);

    if (state) rb_jump_tag(state);

    return result;
}

This API is not yet available in Ruby, and may never be. You can take it from RGeo (MIT LICENSE).

A Real-World Example

If you want to see a real-world example, I encourage you to read the RGeo codebase as we recently switched to going full rb_protect. We even have some functions, such as rgeo_convert_to_geos_geometry, that propagate this state for simpler usage. This function is a good place to start digging around.

Feel free to open an issue on RGeo to discuss the choices we made further.

Wrapping Up

In this post, we warned against using rb_funcall with C as it can cause memory leaks. We explored using begin..ensure or rb_protect instead.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

How to Parse Arguments in Your Ruby C Extension

Ulysse Buonomo — Wed, 25 Jan 2023 16:07:05 +0000

Ruby is a wonderful language, made for humans first and machines second. It is easy to read and write. There are plenty of ways to write anything, and you can often guess its standard library by typing the name of the method you would have chosen yourself.

Because of this, Ruby's arguments are very flexible, which lets us express our APIs very clearly. But this comes with a drawback: Ruby is quite hard to parse for C extension developers!

In this article, we'll go through two ways to set up a complex Ruby API that is written in C:

with rb_define_method and parsing it with rb_scan_args
using a Ruby interface

Let's get started!

C and Ruby: An Introduction

As mentioned, Ruby is hard to parse for C extension developers.

For example:

def this(is, a = "quite", *convoluted, yet: 1, possible:, &example)
  # And we could have omitted the block, yet still passed it as an argument!
end

The beauty of C, the language Ruby is written in, stems from its simplicity, including in its function parameters:

<data-type> <variable-identifier>
... for variadic arguments.

These will help you maintain a codebase that is not too hard to understand.

Here's the most complex way to define a C function:

int printf(const char*, ...);

When you code a C extension for your Ruby codebase, you'll start to understand where the complexity begins. But don't worry — Ruby MRI developers have us covered.

Simple Method Definition in a Ruby C Extension

We'll start with a method you'll have to use at some point, rb_define_method.

You can also follow along with the code examples in this repo.

Here is rb_define_method's signature:

void rb_define_method(VALUE klass, const char *name,
                      VALUE (*func)(ANYARGS), int argc);

And according to Ruby's extension.rdoc:

argc is the number of arguments. if argc is -1, the function will receive 3 arguments: argc, argv, and self. if argc is -2, the function will receive 2 arguments, self and args, where args is a Ruby array of the method arguments.

In a nutshell:

// argc is -1.
VALUE func(int argc, VALUE* argv, VALUE self);
// argc is -2.
VALUE func(VALUE self, VALUE args);
// argc is N (here N=2).
VALUE func(VALUE self, VALUE arg1, VALUE arg2);

So if your API only consists of methods with fixed parameter lengths, or only one variadic parameter (def foo(*bar)), read no further — you are done! If you want a richer way to call your API, please, be my guest.

By the way, if you want more involved examples on rb_define_method, I suggest you read Peter Zhu's article on Defining Methods.

Using Ruby C API Internals

So, let's go back to our use case: parsing complex arguments. Fortunately, some tools can help us.

But first, let's see the limitations of solely using rb_define_method.

Drawbacks of `rb_define_method`

No Mention of Block Arguments

One limitation is that rb_define_method never mentions block arguments. Those are not considered, as it doesn't really matter to Ruby anyway if you pass a block. You can still ensure that a block is passed by using rb_block_given_p or rb_need_block. There's more on that topic in Peter Zhu's article.

Args Can Vary

Another important limitation is that args can vary, but the method call itself is not so constrained. Therefore, if you want your API to be like def foo(bar, *baz), you'll have to parse your arguments. There are a few methods to help you down that path. rb_check_arity is one you can use, along with the -1 version of rb_define_method.

Here's the function signature:

rb_check_arity(int argc, int min, int max)

Keyword Arguments

One last limitation we'll go through is the use of keyword arguments. And I kept the best for last, as that will be the core of this article.

We have to retrieve keyword arguments before we can parse them correctly. Fortunately, the Ruby C API comes with a method for this, rb_scan_args.

Here's the rb_scan_args signature:

rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)

You pass rb_scan_args the argc and argv given by rb_define_method — a string that says how the arguments should be parsed (fmt) and the receiver for those arguments. There you go, all of Ruby's args complexity parsed in one line! Well, almost.

You can refer to extension.rdoc for a formal representation of how fmt should be written, although we'll partially cover it in the examples below.

Write and Parse a Function: An Example

For the rest of this article, let's consider that we want to write this function:

def voronoi_diagram(envelope, *polygons, tolerance:, only_edges: false)
end

Parsing this using rb_scan_args will look like this:

VALUE voronoi_diagram(int argc, VALUE *argv, VALUE self) {
  VALUE envelope;
  VALUE polygons;
  VALUE kwargs;
  rb_scan_args(argc, argv, "1*:", &envelope, &polygons, &kwargs);

  // Actual method
}

The "1*:" gibberish means:

1: one required positional argument
*: any amount of positional arguments not required
:: keyword arguments at the end

Parse Keyword Arguments

Now we've constrained the method, unfortunately, we are not done yet. Our current API is def voronoi_diagram(envelope, *polygons, **kwargs).

Finally, we
need to parse those keyword arguments using rb_get_kwargs.

int rb_get_kwargs(VALUE keyword_hash, const ID *table,
                  int required, int optional, VALUE *values);

You have to choose some required and optional arguments. Once that's done, you use table to tell Ruby the name of those arguments, and you store the result in an array (values).

VALUE voronoi_diagram(int argc, VALUE *argv, VALUE self) {
  VALUE envelope;
  VALUE polygons;
  VALUE tolerance;
  VALUE only_edges;

  VALUE kwargs;
  rb_scan_args(argc, argv, "1*:", &envelope, &polygons, &kwargs);

  ID table[2];
    table[0] = rb_intern("tolerance");
    table[1] = rb_intern("only_edges");
  VALUE *values;
  rb_get_kwargs(kwargs, table, 1, 1, values);

  tolerance = values[0];
  only_edges = values[1] == Qundef ? Qfalse : values[1];

  // Actual method
}

There you have it! A complex Ruby method, parsed using only C. However, if this is too convoluted for you, there is another option.

Using a Ruby Interface

Another way to handle the problem is actually to use Ruby's syntax directly and do the parsing at the Ruby stage.

def voronoi_diagram(envelope, *polygons, tolerance:, only_edges: false)
  c_voronoi_diagram(envelope, polygons, tolerance, only_edges)
end

With this, you can directly use the third form of rb_define_method, for a C method that looks like this:

VALUE c_voronoi_diagram(VALUE self, VALUE envelope,
                        VALUE polygons, VALUE tolerance,
                        VALUE only_edges) {
  // Actual method
}

And there you go — you completely avoid the problem with an elegant solution that is actually used for some methods in a Ruby implementation (with the Primitive class).

Although the class used by the MRI is quite complex and generates C itself, we can get inspired by it.

Let's create an object and plug our methods to avoid having a visible c_voronoi_diagram for users of our API:

void Init_ext() {
  VALUE primary_mod = rb_define_module("Hidden")
  rb_define_method(primary_mod, "voronoi_diagram", func, 4)
}

def voronoi_diagram(envelope, *polygons, tolerance:, only_edges: false)
  Hidden.voronoi_diagram(envelope, polygons, tolerance, only_edges)
end

Check out a real use case of this class in RGeo's codebase.

Parsing Arguments: Which Method Should I Use?

This repo showcases the two ways to set up a complex Ruby API that is written in C — to recap:

with rb_define_method and parsing it with rb_scan_args
using a Ruby interface

When we compare both solutions in terms of performance, they are roughly equal (Ruby parsing is 1.02 times faster on average on my M1). That doesn't make much of a difference.

In the RGeo lib, our first design choice was to have an API that only uses variadic length arguments. No keywords, no blocks. This can be very limiting, and we are now using the Primitive way to allow more convoluted arguments.

Benefits of Using a Ruby Interface

My advice is to use a Ruby interface for multiple reasons, including that:

the code size is smaller
changes are easier to make

Overall, this makes the experience of reading your codebase simpler.

Engaging Ruby users in reading the source code of the gems they use is important to me. As Ruby is easy to read, gems should be as well.

Benefits of Using `rb_define_method`

The C version, however, gives us a taste of some very useful internal methods. For instance, rb_check_arity is still really useful. Methods for handling blocks are great as well, and you might not need to use the Ruby facade for blocks.

It's all about finding the best choice for your use case.

Wrapping Up

In this post, we explored two methods to parse arguments in your Ruby C extension — using rb_define_method (also looking briefly at its limitations) and parsing it with rb_scan_args and using a Ruby interface.

If you want to read more about C extensions, I recommend:

And my final word of advice for you: check out RGeo. It is a widely used C extension codebase in active development. Most of my examples come from here.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

DEV Community: Ulysse Buonomo

Calling Ruby Methods in C: Avoid Memory Leaks

The Issue with rb_funcall and C

Raise in Ruby Causing C Memory Leaks

Using begin..ensure in Ruby

Using rb_protect for C

The rb_protect_funcall Proposal

A Real-World Example

Wrapping Up

How to Parse Arguments in Your Ruby C Extension

C and Ruby: An Introduction

Simple Method Definition in a Ruby C Extension

Using Ruby C API Internals

Drawbacks of rb_define_method

No Mention of Block Arguments

Args Can Vary

Keyword Arguments

Write and Parse a Function: An Example

Parse Keyword Arguments

Using a Ruby Interface

Parsing Arguments: Which Method Should I Use?

Benefits of Using a Ruby Interface

Benefits of Using rb_define_method

Wrapping Up

The Issue with `rb_funcall` and C

Using `begin..ensure` in Ruby

Using `rb_protect` for C

The `rb_protect_funcall` Proposal

Drawbacks of `rb_define_method`

Benefits of Using `rb_define_method`