#[macro_use] extern crate ruru;

use ruru::{Class, Fixnum, Object, VM};

class!(Calculator);

methods!(
    Calculator,
    itself,

    fn heavy_computation() -> Fixnum {
        let computation = || { 2 * 2 };
        let unblocking_function = || {};

        // release GVL for current thread until `computation` is completed
        let result = VM::thread_call_without_gvl(
            computation,
            Some(unblocking_function)
        );

        Fixnum::new(result)
    }
);

fn main() {
    Class::new("Calculator", None).define(|itself| {
        itself.def("heavy_computation", heavy_computation);
    });
}

定义一个新类

假设你有一个 Calculator 类。

class Calculator
  def pow_3(number)
    (1..number).each_with_object({}) do |index, hash|
      hash[index] = index ** 3
    end
  end
end

# ... somewhere in the application code ...
Calculator.new.pow_3(5) #=> { 1 => 1, 2 => 8, 3 => 27, 4 => 64, 5 => 125 }

你发现调用 pow_3 对于大数字来说非常慢，因此决定用 Rust 替换整个类。

#[macro_use]
extern crate ruru;

use std::error::Error;
use ruru::{Class, Fixnum, Hash, Object, VM};

class!(Calculator);

methods!(
    Calculator,
    itself,

    fn pow_3(number: Fixnum) -> Hash {
        let mut result = Hash::new();

        // Raise an exception if `number` is not a Fixnum
        if let Err(ref error) = number {
            VM::raise(error.to_exception(), error.description());
        }

        for i in 1..number.unwrap().to_i64() + 1 {
            result.store(Fixnum::new(i), Fixnum::new(i.pow(3)));
        }

        result
    }
);

#[no_mangle]
pub extern fn initialize_calculator() {
    Class::new("Calculator", None).define(|itself| {
        itself.def("pow_3", pow_3);
    });
}

Ruby

# No Calculator class in Ruby anymore

# ... somewhere in the application ...
Calculator.new.pow_3(5) #=> { 1 => 1, 2 => 8, 3 => 27, 4 => 64, 5 => 125 }

类的 API 没有发生变化，因此无需更改应用程序其他地方的任何代码。

只替换几个方法而不是整个类

如果示例中的 Calculator 类有更多的 Ruby 方法，但只想替换 pow_3，请使用 Class::from_existing()

Class::from_existing("Calculator").define(|itself| {
    itself.def("pow_3", pow_3);
});

类定义 DSL

Class::new("Hello", None).define(|itself| {
    itself.const_set("GREETING", &RString::new("Hello, World!").freeze());

    itself.attr_reader("reader");

    itself.def_self("greeting", greeting);
    itself.def("many_greetings", many_greetings);

    itself.define_nested_class("Nested", None).define(|itself| {
        itself.def_self("nested_greeting", nested_greeting);
    });
});

这对应于以下 Ruby 代码

class Hello
  GREETING = "Hello, World".freeze

  attr_reader :reader

  def self.greeting
    # ...
  end

  def many_greetings
    # ...
  end

  class Nested
    def self.nested_greeting
      # ...
    end
  end
end

有关 Class 和 Object 的更多信息，请参阅文档。

从 Rust 调用 Ruby 代码

获取名为 John 且 18 或 19 岁的 User 的账户余额。

default_balance = 0

account_balance = User
  .find_by(age: [18, 19], name: 'John')
  .account_balance

account_balance = default_balance unless account_balance.is_a?(Fixnum)

#[macro_use]
extern crate ruru;

use ruru::{Array, Class, Fixnum, Hash, Object, RString, Symbol};

fn main() {
    let default_balance = 0;
    let mut conditions = Hash::new();

    conditions.store(
        Symbol::new("age"),
        Array::new().push(Fixnum::new(18)).push(Fixnum::new(19))
    );

    conditions.store(
        Symbol::new("name"),
        RString::new("John")
    );

    // Fetch user and his balance
    // and set it to 0 if balance is not a Fixnum (for example `nil`)
    let account_balance =
        Class::from_existing("User")
            .send("find_by", vec![conditions.to_any_object()])
            .send("account_balance", vec![])
            .try_convert_to::<Fixnum>()
            .map(|balance| balance.to_i64())
            .unwrap_or(default_balance);
}

查看更多示例的 文档！

... 以及为什么 FFI 不够用？

• 不支持原生 Ruby 类型；

• 无法创建独立的应用程序来单独运行 Ruby 虚拟机；

• 无法从 Rust 中调用 Ruby 代码；

如何使用它？

警告！该软件包是工作进展中的（WIP）；

建议使用 Thermite 钩子，这是一个基于 Rake 的助手，用于构建和分发基于 Rust 的 Ruby 扩展；

要使用 Ruru，请确保您的 Ruby 版本为 2.3.0 或更高；

1. 您的本地 MRI 复制必须使用 --enable-shared 选项构建。例如，使用 rbenv

CONFIGURE_OPTS=--enable-shared rbenv install 2.3.0

2. 将 Ruru 添加到 Cargo.toml

[dependencies]
ruru = "0.9.0"

3. 将库编译为 dylib

[lib]
crate-type = ["dylib"]

4. 创建一个初始化扩展的函数

#[no_mangle]
pub extern fn initialize_my_app() {
    Class::new("SomeClass");

    // ... etc
}

5. 构建扩展

$ cargo build --release

或使用 Thermite

$ rake thermite:build

6. 在 Ruby 端，打开编译后的 dylib 并调用初始化扩展的函数

require 'fiddle'

library = Fiddle::dlopen('path_to_dylib/libmy_library.dylib')

Fiddle::Function.new(library['initialize_my_app'], [], Fiddle::TYPE_VOIDP).call

7. Ruru 准备就绪 ❤️

欢迎贡献者！

如果您有任何问题，请加入 Ruru 在 Gitter

许可证

MIT 许可证

版权所有 (c) 2015-2016 Dmitry Gritsay

特此授予任何获得此软件及其相关文档副本（以下简称“软件”）的人免费使用软件的权利，不受任何限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件的副本，并允许软件的提供方使用软件，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途的适用性和非侵权性。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任承担责任，无论此类责任是基于合同、侵权或其他方式，是否源于、因之而产生或与此软件或软件的使用或其他交易有关。

图标由 Github 设计。