TruffleRuby 附加功能

TruffleRuby 旨在作为标准的 Ruby 实现使用，可以运行在其他实现上开发的程序，但它也提供了超越其他实现的附加功能。

有关与其他 Ruby 实现的兼容性，请参阅兼容性指南。

检测是否在 TruffleRuby 上运行 #

您可以使用 --version 命令行选项。例如，TruffleRuby 将报告

truffleruby ..., like ruby ..., GraalVM CE Native [x86_64-darwin]

在 Ruby 代码中，您可以查看标准的 RUBY_ENGINE 常量，它将是 'truffleruby'。在 C 代码中，TRUFFLERUBY 被定义。

也可以使用特性检测，而不是查看 RUBY_ENGINE。

您可以使用标准的 RUBY_ENGINE_VERSION 常量来查找 TruffleRuby 的版本号。

TruffleRuby 方法和类 #

TruffleRuby 提供了这些非标准方法和类，它们在 TruffleRuby 模块中提供了附加功能

TruffleRuby.jit? 报告 GraalVM 编译器是否可用并将被使用。
TruffleRuby.native? 报告 TruffleRuby 是否编译为原生可执行文件。
TruffleRuby.cexts? 报告 TruffleRuby 是否提供了用于 C 扩展的 GraalVM LLVM 运行时。
TruffleRuby.revision 报告用于构建 TruffleRuby 的源代码控制修订版本，以字符串形式。也可用作 RUBY_REVISION，类似于 CRuby 2.7+。
TruffleRuby.full_memory_barrier 确保屏障前的加载或存储与屏障后的加载或存储不会发生重排序。
TruffleRuby.graalvm_home 返回 GraalVM 主目录，如果在 GraalVM 之外运行则返回 nil（例如，原生独立运行）。
TruffleRuby.synchronized(object) { } 将在每个对象实例持有一个隐式锁时运行该块。

原子引用 #

atomic_reference = TruffleRuby::AtomicReference.new(value=nil) 创建一个新的原子引用，指向给定对象。
atomic_reference.get 获取原子引用的值，并返回该值。
atomic_reference.set(new_value) 设置原子引用的值，并导致涉及 new_value 的写入操作产生内存屏障。
atomic_reference.get_and_set(new_value) 设置原子引用的值，返回旧值，并导致涉及 new_value 的写入操作产生内存屏障。
atomic_reference.compare_and_set(expected_value, new_value) 设置原子引用的值，仅当它当前具有预期值时，返回一个布尔值指示是否已设置，并导致涉及 new_value 的写入操作产生内存屏障。对于数值对象，它将获取当前值，然后检查当前值是否也是数值，并通过调用 == 检查其是否等于预期值，然后执行原子比较并设置。
AtomicReference 是可序列化的。

并发映射 #

TruffleRuby::ConcurrentMap 是一种键值数据结构，类似于 Hash，使用 #hash 和 #eql? 比较键，并使用标识比较值。与 Hash 不同，它是无序的。TruffleRuby::ConcurrentMap 上的所有方法都是线程安全的，但应比完全同步的实现具有更高的并发性。它旨在由诸如 concurrent-ruby 等 gem 使用 — 请通过此 gem 而非直接使用。

map = TruffleRuby::ConcurrentMap.new([initial_capacity: ...], [load_factor: ...])
map[key] = new_value
map[key]
map.compute_if_absent(key) { computed_value } 如果未找到键，则运行该块并存储结果。该块最多运行一次。返回计算出的值。
map.compute_if_present(key) { |current_value| computed_value } 如果找到键，则运行该块并存储结果。如果该块返回 nil，则移除该键的条目。该块最多运行一次。返回最终值，如果该块返回 nil 则返回 nil。
map.compute(key) { |current_value| computed_value } 运行该块，如果存在当前值则传入当前值或 nil，并存储结果。如果该块返回 nil，则移除该键的条目。返回计算出的值。
map.merge_pair(key, new_value) { |existing_value| merged_value } 如果未找到键或键为 nil，则存储新值；否则调用该块并存储结果，如果该块返回 nil 则移除该条目。返回该条目的最终值，如果该块返回 nil 则返回 nil。
map.replace_pair(key, expected_value, new_value) 替换键的值，但仅当其现有值与 expected_value 相同（通过标识比较）时才替换。返回该值是否已替换。
map.replace_if_exists(key, value) 替换键的值，但仅当找到该键时才替换。如果键存在则返回 value，否则返回 nil。
map.get_and_set(key, new_value) 设置键的值并返回旧值。
map.key?(key) 返回键是否存在于映射中。
map.delete(key) 如果键存在则从映射中移除该键，并返回其值；如果键不存在则返回 nil。
map.delete_pair(key, expected_value) 删除键，但仅当其现有值与 expected_value 相同（通过标识比较）时才删除。返回键是否已删除。
map.clear 从映射中移除所有条目。
map.size 返回映射中的条目数。
map.get_or_default(key, default_value)
map.each_pair { |key, value| ... }

FFI #

TruffleRuby 包含一个 Ruby-FFI 后端。这应该是透明的：您只需像往常一样安装 ffi gem，它将使用 TruffleRuby 的 FFI 后端。TruffleRuby 还包含一个默认版本的 FFI gem，因此即使未安装该 gem，require "ffi" 在 TruffleRuby 上也始终有效。

多语言编程 #

Polyglot 和 Java 模块提供了对 GraalVM 多语言编程功能的访问。它们在多语言编程指南中有所描述。

不支持的附加功能 #

您可能会发现一些此处未列出但看起来很有趣的其他模块和方法，例如 Truffle::POSIX 或 Truffle::FFI。本文档中未列出的其他模块和方法旨在支持 TruffleRuby 的实现，不应使用。它们将来可能会被修改或对用户程序不可见，因此您不应使用它们。

TruffleRuby C 扩展头文件中，除 MRI 提供的之外的额外宏、函数和变量，例如以 rb_tr_* 开头的，均不受支持，任何 C 扩展都不应使用。