Building C Extensions in Ruby

A starting guide to your first C extension.

Transcript

1. Building C Extensions in Ruby André Medeiros @superdealloc
2. Why?
3. Ruby is not slow (don’t believe the haters)
4. Not great for heavy processing.
5. It’s not hard.
6. Ruby’s C API feels a lot like Ruby
7. Don’t know C?
 Learn it The Hard Way http://c.learncodethehardway.org/
8. How to approach the problem.
9. C types as first class citizens Great for gems that involve back-and-forth communication (RMagick, Nokogiri)
10. Ruby first Better for when it’s one-sided communication (MySQL2, statistics, log parsing)
11. Getting started
12. Create your gem skeleton $ bundle gem speedy_gem!
13. Add the Rake compile task # speedy_gem.gemspec! spec.add_development_dependency "rake-compiler"! ! # Rakefile! require "rake/extensiontask"! ! Rake::ExtensionTask.new("speedy_gem") do |ext|! extension.lib_dir = "lib/speedy_gem"! end!
14. Create THE EXT FOLDER $ mkdir -p ext/speedy_gem!
15. … and your extension configuration file # ext/speedy_gem/extconf.rb! require 'mkmf'! ! create_makefile('speedy_gem')!
16. Boilerplate
17. initializing your extension // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! // Initialization code goes here! }!
18. Defining your first class // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! }!
19. Memory management // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! rb_define_alloc_func(SpeedyGemClass, rb_alloc);! }! ! VALUE rb_alloc(VALUE self) {! char *string = calloc(1024, sizeof(char));! return Data_Wrap_Struct(SpeedyGemClass, NULL, rb_free, string);! }! ! void rb_free(char *string) {! free(string);! }!
20. Getting the C struct // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! rb_define_method(SpeedyGemClass, "string", rb_get_string, 0);! }! ! VALUE rb_get_string(VALUE self) {! char *string;! Data_Get_Struct(self, char, string);! return rb_str_new2(string);! }!
21. your first method // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! rb_define_method(SpeedyGemClass, "say_hi", rb_say_hi, 1);! }! ! VALUE rb_say_hi(VALUE self, VALUE name) {! VALUE phrase = rb_str_new2("Hello, ");! rb_str_append(phrase, name);! return phrase;! } !
22. Checking types
23. built-in types // Checks if radius is a Float! Check_Type(radius, T_FLOAT);! ! // Checks if age is a Fixnum! Check_Type(age, T_FIXNUM);! ! // Checks if name is a String! Check_Type(name, T_STRING);! ! // Checks if options is a Hash! Check_Type(options, T_HASH); !
24. Others if (CLASS_OF(klass) != SpeedyGemClass) {! rb_raise(rb_eTypeError, "wrong argument type %s (expected SpeedyGem)",! rb_obj_classname(klass));! }!
25. Method Parameters
26. Fixed number // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! rb_define_method(SpeedyGemClass, "say_hi", rb_say_hi, 1);! }! ! VALUE rb_say_hi(VALUE self, VALUE name) {! VALUE phrase = rb_str_new2("Hello, ");! rb_str_append(phrase, name);! return phrase;! } !
27. optional // ext/speedy_gem/speedy_gem.c! ! #include "ruby.h"! ! VALUE SpeedyGemClass = Qnil;! ! void Init_rubyconf() {! SpeedyGemClass = rb_define_class("SpeedyGem", rb_cObject);! rb_define_method(SpeedyGemClass, "say_hi", rb_say_hi, -1);! }! ! VALUE rb_say_hi(int argc, VALUE *argv, VALUE self) {! VALUE phrase = rb_str_new2("Hello, ");! VALUE name;! rb_scan_args(argc, argv, "01", &name);! ! if(!RTEST(name))! name = rb_str_new2("World");! ! rb_str_append(phrase, name);! return phrase;! } !
28. Honing Ruby functionality
29. Strings // Create a Ruby string from char *! VALUE phrase = rb_str_new2("Hello, ");! ! // Append two Ruby strings together! rb_str_append(phrase, subject);! ! // Append a char * to a Ruby string! rb_str_cat2(phrase, "Something");! ! // Duplicate a Ruby string! VALUE copy = rb_str_dup(phrase);! ! // Get a substring from a Ruby string! VALUE without_hello = rb_str_substr(phrase, 7, 100);!
30. Arrays // Create a Ruby array! VALUE array = rb_ary_new();! ! // Push values to a Ruby array! rb_ary_push(array, rb_str_new2("One thing"));! rb_ary_push(array, rb_str_new2("Another thing"));! ! // Add a value to a specific position in a Ruby array! rb_ary_store(array, 2, rb_str_new2("A third thing"));! ! // Reverse a Ruby array! VALUE reversed = rb_ary_reverse(array);! ! // Create a Ruby string out of a Ruby array! VALUE string = rb_ary_join(array, rb_str_new2(", "));!
31. Hashes // Creating a Ruby hash! VALUE hash = rb_hash_new();! ! // Adding values! rb_hash_aset(! hash, // The Ruby hash! ID2SYM(rb_intern("universal_answer")), // Key! INT2NUM(42) // Value! );! ! // Getting a value from a Ruby hash! VALUE answer = rb_hash_aref(hash, ID2SYM(rb_intern("universal_answer")));!
32. Blocks // Check if a block was given and yield a value if so.! if(rb_block_given_p()) rb_yield(value)! ! // Same as above, but multiple values! if(rb_block_given_p()) rb_yield_values(value1, value2)! ! // Store a block into a variable and call it later.! VALUE block = rb_block_proc();! rb_funcall(block, rb_intern("call"), 2, value1, value2);!
33. SYMBOLS ID2SYM(rb_intern("some_symbol"))!
34. And a bunch more! andremedeiros/ruby-c-cheat-sheet
35. Good Practices
36. Define what your API looks like first
37. Return self as much as possible
38. Provide bang methods as much as possible.
39. Ruby doesn’t always map 1:1 to C libraries