使用C++来编写Ruby程序扩展的教程

ruby 最酷的功能之一就是使用 c/c++ 定义的应用程序编程接口 (api) 扩展它。ruby 提供了 c 头文件 ruby.h，它随附提供了许多功能，可使用这些功能创建 ruby 类、模块和更多内容。除了头文件，ruby 还提供了其他几个高层抽象来扩展基于本地 ruby.h 构建的 ruby，本文要介绍的是 ruby interface for c++ extensions 或 rice。
创建 ruby 扩展

在进行任何 ruby 的 c api 或 rice 扩展前，我想明确地介绍一下创建扩展的标准过程：

•     您具有一个或多个 c/c++ 源代码，可使用它们构建共享库。
•     如果您使用 rice 创建扩展，则需要将代码链接到 libruby.a 和 librice.a。
•     将共享库复制到同一文件夹，并将该文件夹作为 rubylib 环境变量的一部分。
•     在 interactive ruby (irb) prompt/ruby 脚本中使用常见的基于 require 的加载。如果共享库名为 rubytest.so，只需键入 require 'rubytest' 即可加载共享库。

假设头文件 ruby.h 位于 /usr/lib/ruby/1.8/include 中，rice 头文件位于 /usr/local/include/rice/include 中，并且扩展代码位于文件 rubytest.cpp 中。 清单 1 显示了如何编译和加载代码。
清单 1. 编译和加载 ruby 扩展

bash# g++ -c rubytest.cpp –g –wall -i/usr/lib/ruby/1.8/include \
  -i/usr/local/include/rice/include
bash# g++ -shared –o rubytest.so rubytest.o -l/usr/lib/ruby/1.8/lib \
  -l/usr/local/lib/rice/lib -lruby –lrice –ldl -lpthread
bash# cp rubytest.so /opt/test
bash# export rubylib=$rubylib:/opt/test
bash# irb
irb> require 'rubytest'
=> true

hello world 程序

现在，您已经准备好使用 rice 创建自己的首个 hello world 程序。您使用名为 test 的 rice api 和名为 hello 的方法创建了一个类，用它来显示字符串 "hello, world!"。当 ruby 解释器加载扩展时，会调用函数 init_<shared library name>。对于 清单 1 的 rubytest 扩展，此调用意味着 rubytest.cpp 已定义了函数 init_rubytest。rice 支持您使用 api define_class 创建自己的类。清单 2 显示了相关代码。
清单 2. 使用 rice api 创建类

#include "rice/class.hpp"
extern "c"
void init_rubytest( ) { 
 class tmp_ = define_class("test");
}

当您在 irb 中编译和加载清单 2 的代码时，应得到 清单 3 所示的输出。
清单 3. 测试使用 rice 创建的类

irb> require ‘rubytest'
=> true
irb> a = test.new
=> #<test:0x1084a3928>
irb> a.methods
=> ["inspect", "tap", "clone", "public_methods", "__send__", 
   "instance_variable_defined?", "equal?", "freeze", …]

注意，有几个预定义的类方法可供使用，比如 inspect。出现这种情况是因为，定义的 test 类隐式地衍生自 object 类（每个 ruby 类都衍生自 object；实际上，ruby 中的所有内容（包括数字）都是基类为 object 的对象）。

现在，为 test 类添加一个方法。清单 4 显示了相关代码。
清单 4. 为 test 类添加方法

void hello() {
  std::cout << "hello world!";
}
extern "c"
 void init_rubytest() {
   class test_ = define_class("test")
     .define_method("hello", &hello);
}

清单 4 使用 define_method api 为 test 类添加方法。注意，define_class 是返回一个类型为 class 的对象的函数；define_method 是 module_impl 类的成员函数，该类是 class 的基类。下面是 ruby 测试，验证所有内容是否都运行良好：

irb> require ‘rubytest'
=> true
irb> test.new.hello
hello, world!
=> nil

将参数从 ruby 传递到 c/c++ 代码

现在，hello world 程序已正常运行，尝试将参数从 ruby 传递到 hello 函数，并让函数显示与标准输出 (sdtout) 相同的输出。最简单的方法是为 hello 函数添加一个字符串参数：

void hello(std::string args) {
  std::cout << args << std::endl;
}
extern "c"
 void init_rubytest() {
   class test_ = define_class("test")
     .define_method("hello", &hello);
}

在 ruby 环境中，以下是调用 hello 函数的方式：

irb> a = test.new
<test:0x0145e42112>
irb> a.hello "hello world in ruby"
hello world in ruby
=> nil

使用 rice 最出色的一点是，无需进行任何特殊操作将 ruby 字符串转换为 std::string。

现在，尝试在 hello 函数中使用字符串数组，然后检查如何将信息从 ruby 传递到 c++ 代码。最简单的方式是使用 rice 提供的 array 数据类型。在头文件 rice/array.hpp 中定义 rice::array，使用 rice::array 的方式类似于使用 standard template library (stl) 容器。还要将常见的 stl 样式迭代器等内容定义为 array 接口的一部分。清单 5 显示了 count 例程，该例程使用 rice array 作为参数。
清单 5. 显示 ruby 数组

#include "rice/array.hpp"

void array_print (array a)  {
   array::iterator ai = a.begin();
   array::iterator ae = a.end();
   while (ai != ae) {
    std::cout << "array has " << *ai << std::endl;
    ++ai;
   }
 }

现在，下面是此解决方案的魅力所在：假设您拥有 std::vector<std::string> 作为 array_print 参数。下面是 ruby 抛出的错误：

>> t = test.new
=> #<test:0x100494688>
>> t.array_print ["g", "ggh1", "hh1"]
argumenterror: unable to convert array to std::vector<std::string, 
  std::allocator<std::string> >
 from (irb):3:in `hello'
 from (irb):3

但是，使用此处显示的 array_print 例程，rice 负责执行从 ruby 数组到 c++ array 类型的转换。下面是样例输出：

>> t = test.new
=> #<test:0x100494688>
>> t.array_print ["hello", "world", "ruby"]
array has hello
array has world
array has ruby
=> nil

现在，尝试相反的过程，将 c++ 的数组传递到 ruby 环境。请注意，在 ruby 中，数组元素不一定是同一类型的。清单 6 显示了相关代码。
清单 6. 将数组从 c++ 传递到 ruby

#include "rice/string.hpp"
#include "rice/array.hpp"
using namespace rice; 

array return_array (array a) {
   array tmp_;
   tmp_.push(1);
   tmp_.push(2.3);
   tmp_.push(string("hello"));
   return tmp_;
 }

清单 6 明确显示了您可以在 c++ 中创建具有不同类型的 ruby 数组。下面是 ruby 中的测试代码：

>> x = t.return_array
=> [1, 2.3, "hello"]
>> x[0].class
=> fixnum
>> x[1].class
=> float
>> x[2].class
=> string

如果我没有更改 c++ 参数列表的灵活性，会怎么样？

更常见的情况是具有这样的灵活性，您将发现 ruby 接口旨在将数据转换为 c++ 函数，该函数的签名无法更改。例如，考虑需要将字符串数组从 ruby 传递到 c++ 的情形。c++ 函数签名如下所示：

void print_array(std::vector<std::string> args)

实际上，您在这里寻找的是某种 from_ruby 函数，ruby 数组使用该函数并将它转换为 std::vector<std::string>。这正是 rice 提供的内容，具有下列签名的 from_ruby 函数：

template <typename t>
t from_ruby(object );

对于需要转换为 c++ 类型的每种 ruby 数据类型，需要针对模板详细说明 from_ruby 例程。例如，如果将 ruby 数组传递到上述处理函数，清单 7 显示了应如何定义 from_ruby 函数。
清单 7. 将 ruby 数组转换为 std::vector<std::string>

template<>
std::vector<std::string> from_ruby< std::vector<std::string> > (object o)  {
  array a(o);
  std::vector<std::string> v;
  for(array::iterator ai = a.begin(); ai != a.end(); ++ai)
    v.push_back(((string)*ai).str());
  return v;
  }

请注意，不需要显式地调用 from_ruby 函数。当从 ruby 环境传递作为函数参数的 string 数组时，from_ruby 将它转换为 std::vector<std::string>。清单 7 中的代码并不完美，但是您已经看到，ruby 中的数组具有不同类型。相反，您调用了 ((string)*ai).str()，以便从 rice::string 获得 std::string。（str 是 rice::string 的一种方法：查看 string.hpp 以了解有关的更多信息。）如果您处理的是最常见的情形，清单 8 显示了相关的代码。
清单 8. 将 ruby 数组转换为 std::vector<std::string>（通用情况）

template<>
std::vector<std::string> from_ruby< std::vector<std::string> > (object o)  {
  array a(o);
  std::vector<std::string> v;
  for(array::iterator ai = a.begin(); ai != a.end(); ++ai)
    v.push_back(from_ruby<std::string> (*ai));
  return v;
  }

由于 ruby 数组的每个元素仍然是类型为 string 的 ruby 对象，因此可以假设 rice 已定义了 from_ruby 方法，将此类型转换为 std::string，不需要进行其他操作。如果情况并非如此，则需要为此转换提供 from_ruby 方法。下面是 rice 资源中 to_from_ruby.ipp 的 from_ruby 方法：

template<>
inline std::string from_ruby<std::string>(rice::object x) {
 return rice::string(x).str();
}

在 ruby 环境中测试此代码。首先传递所有字符串的数组，如 清单 9 所示。
清单 9. 验证 from_ruby 功能

>> t = test.new
=> #<test:0x10e71c5c8>
>> t.print_array ["aa", "bb"]
aa bb
=> nil
>> t.print_array ["aa", "bb", 111]
typeerror: wrong argument type fixnum (expected string)
 from (irb):4:in `print_array'
 from (irb):4

和预期一样，首次调用 print_array 运行正常。由于没有 from_ruby 方法来将 fixnum 转换为 std::string，因此第二次调用时，会导致 ruby 解释器抛出 typeerror。有几种修复此错误的方法：例如，在 ruby 调用期间，仅将字符串作为数组的一部分（比如 t.print_array["aa", "bb", 111.to_s]）来传递，或者是在 c++ 代码中，调用 object.to_s。to_s 方法是 rice::object 接口的一部分，它会返回 rice::string，它还有一个返回 std::string 的预定义 str 方法。清单 10 使用了 c++ 方法。
清单 10. 使用 object.to_s 填充字符串向量

template<>
std::vector<std::string> from_ruby< std::vector<std::string> > (object o)  {
  array a(o);
  std::vector<std::string> v;
  for(array::iterator ai = a.begin(); ai != a.end(); ++ai)
    v.push_back(ai->to_s().str());
  return v;
  }

通常，清单 10 中的代码更为重要，因为您需要处理用户定义的类的自定义字符串表示。

使用 c++ 创建一个具有变量的完整类

您已经了解了在 c++ 代码内如何创建 ruby 类和相关函数。对于更通用的类，需要一种定义实例变量的方法，并提供一个 initialize 方法。要设置并获得 ruby 对象实例变量的值，可以使用 rice::object::iv_set 和 rice::object::iv_get 方法。清单 11 显示了相关的代码。
清单 11. 在 c++ 中定义 initialize 方法

void init(object self) {
   self.iv_set("@intvar", 121);
   self.iv_set("@stringvar", string("testing"));
 }
class ctest = define_class("test").
             define_method("initialize", &init);

使用 define_method api 将 c++ 函数声明为 ruby 类方法时，可选择将 c++ 函数的第一个参数声明为 object，并且 ruby 会使用调用实例的引用来填充此 object。然后，在 object 上调用 iv_set 来设置实例变量。下面是接口在 ruby 环境中的外观：

>> require 'rubytest'
=> true
>> t = test.new
=> #<test:0x1010fe400 @stringvar="testing", @intvar=121>

同样地，要返回实例变量，返回的函数需要接收在 ruby 中引用对象的 object，并对它调用 iv_get。清单 12 显示了相关的代码片段。
清单 12. 从 ruby 对象检索值

void init(object self) {
   self.iv_set("@intvar", 121);
   self.iv_set("@stringvar", string("testing"));
 }
int getvalue(object self) { 
  return self.iv_get("@intvar");
}
class ctest = define_class("test").
             define_method("initialize", &init).
             define_method("getint", &getvalue);

将 c++ 类转换为 ruby 类型

迄今为止，您已经将免费的函数（非类方法）包装为 ruby 类方法。您已经将引用传递给 ruby 对象，方法是使用第一个参数 object 声明 c 函数。这种方法有用，但是在将 c++ 类包装为 ruby 对象时，这种方法不够好用。要包装 c++ 类，仍需要使用 define_class 方法，除非现在您使用 c++ 类类型对它进行了 “模板化” 。清单 13 中的代码将 c++ 类包装为 ruby 类型。
清单 13. 将 c++ 类包装为 ruby 类型

class cpptype {
  public:
   void print(string args) {
    std::cout << args.str() << endl;
   }
};
class rb_ctest =
    define_class<cpptype>("test")
     .define_method("print", &cpptype::print);

注意，如前所述，对 define_class 进行了模板化。尽管这种方法并不是适合所有此类。下面是您试图实例化类型 test 的对象时，ruby 解释器的记录：

>> t = test.new
typeerror: allocator undefined for test
 from (irb):3:in `new'
 from (irb):3

刚刚发生了什么事？您需要将构造函数显式地绑定到 ruby 类型。（这是 rice 的怪异之处之一。）rice 为您提供了 define_constructor 方法来关联 c++ 类型的构造函数。您还需要包含头文件 constructor.hpp。注意，即使在您的代码中没有显式构造函数，您也必须这样做。清单 14 提供了示例代码。
清单 14. 将 c++ 构造函数与 ruby 类型关联起来

#include "rice/constructor.hpp"
#include "rice/string.hpp"
class cpptype {
  public:
  void print(string args) {
    std::cout << args.str() << endl;
   }
  };

class rb_ctest =
    define_class<cpptype>("test")
     .define_constructor(constructor<cpptype>())
    .define_method("print", &cpptype::print);

还可以将构造函数与使用 define_constructor 方法的参数列表关联起来。rice 进行此操作的方法是为模板列表添加参数类型。例如，如果 cpptype 有一个接收整数的构造函数，那么您必须将 define_constructor 作为 define_constructor(constructor<cpptype, int>()) 进行调用。关于此处的一条警告：ruby 类型没有多个构造函数。因此，如果您有具有多个构造函数的 c++ 类型，并使用 define_constructor 将它们关联起来，那么从 ruby 环境的角度讲，您可以像源代码最后一个 define_constructor 定义的那样，初始化具有（或没有）参数的类型。清单 15 解释了刚刚讨论的所有内容。
清单 15. 将构造函数与参数关联起来

class cpptype {
  public:
   cpptype(int m) {
    std::cout << m << std::endl;
   }
   cpptype(array a) {
    std::cout << a.size() << std::endl;
   }
   void print(string args) {
    std::cout << args.str() << endl;
   }
  };
class rb_ctest =
    define_class<cpptype>("test")
     .define_constructor(constructor<cpptype, int>())
     .define_constructor(constructor<cpptype, array>())
     .define_method("print", &cpptype::print);

下面是来自 ruby 环境的记录。注意，最后关联的构造函数是 ruby 理解的构造函数：

>> t = test.new 2
typeerror: wrong argument type fixnum (expected array)
 from (irb):2:in `initialize'
 from (irb):2:in `new'
 from (irb):2
>> t = test.new [1, 2]
2
=> #<test:0x10d52cf48>

将新 ruby 类型定义为模块的一部分

从 c++ 定义新 ruby 模块可归结为调用 define_module。要定义仅作为所述模块一部分的类，请使用 define_class_under 而不是常用的 define_class 方法。define_class_under 的第一个参数是模块对象。根据 清单 14，如果您打算将 cpptype 定义为名为 types 的 ruby 模块的一部分，清单 16 显示了如何进行此操作。
清单 16. 将类型声明为模块的一部分

#include "rice/constructor.hpp"
#include "rice/string.hpp"
class cpptype {
  public:
  void print(string args) {
    std::cout << args.str() << endl;
   }
  };

module rb_cmodule = define_module("types");
class rb_ctest =
    define_class_under<cpptype>(rb_cmodule, "test")
     .define_constructor(constructor<cpptype>())
    .define_method("print", &cpptype::print);

下面是在 ruby 中使用相同声明的方法：

>> include types
=> object
>> y = types::test.new [1, 1, 1]
3
=> #<types::test:0x1058efbd8>

注意，在 ruby 中，模块名称和类名称必须以大写字母开头。如果您将模块命名为 types 而不是 types，rice 不会出错。

使用 c++ 代码创建 ruby 结构

您在 ruby 中使用 struct 构造函数来快速创建样本 ruby 类。清单 17 显示了使用名为 a、ab 和 aab 的三个变量创建类型 newclass 的新类的方法。
清单 17. 使用 ruby struct 创建新类

>> newclass = struct.new(:a, :ab, :aab)
=> newclass
>> newclass.class
=> class
>> a = newclass.new
=> #<struct newclass a=nil, ab=nil, aab=nil>
>> a.a = 1
=> 1
>> a.ab = "test"
=> "test"
>> a.aab = 2.33
=> 2.33
>> a
=> #<struct newclass a=1, ab="test", aab=2.33>
>> a.a.class
=> fixnum
>> a.ab.class
=> string
>> a.aab.class
=> float

要在 c++ 中进行 清单 17 的等效编码，您需要使用头文件 rice/struct.hpp 中声明的 define_struct( ) api。此 api 返回 rice::struct。您将此 struct 创建的 ruby 类与该类所属的模块关联起来。这是 initialize 方法的目的。使用 define_member 函数调用定义各个类成员。注意，您已经创建了一个新的 ruby 类型，可惜您没有将任何 c++ 类型或函数与它关联起来。下面是创建名为 newclass 的类的方法：

#include "rice/struct.hpp"
…
module rb1 = define_module("types");
define_struct().
    define_member("a").
    define_member("ab").
    define_member("aab").
    initialize(rb1, "newclass");

结束语

本文介绍了一些背景知识：使用 c++ 代码创建 ruby 对象，将 c 样式的函数作为 ruby 对象方法进行关联，在 ruby 和 c++ 之间转换数据类型，创建实例变量，以及将 c++ 类包装为 ruby 类型。您可以使用 ruby.h 头文件和 libruby 实现所有这些操作，但是您需要编写大量样板代码来结束所有操作。rice 使这些工作变得更加简单。在这里，祝您使用 c++ 针对 ruby 环境编写新扩展愉快！ world!