class Ractor (Ruby 4.1 リファレンスマニュアル)

要約

並列プログラミングの仕組みを提供するクラスです。

Ruby 4.1 から、クラスやモジュールを変更できるのは、それを作成した Ractor（owner）だけになりました。メソッドの定義・削除、alias、可視性の変更、include / prepend、定数の定義・削除、クラス自身のインスタンス変数・クラス変数への書き込みなどを他の Ractor から行うと、Ractor::IsolationError が発生します。読み取りは従来どおりできます。起動時や main Ractor で定義されたクラス（require したライブラリのものを含む）の owner は main Ractor なので、main 以外の Ractor からは変更できません。一方、Ractor が自分で作成したクラスは、shareable でない定数・インスタンス変数・クラス変数も含めて自由に使えます。[feature#22226]

また、Ruby 4.1 から、デフォルトの GC は Ractor ごとに動作します。各 Ractor は自分のヒープを自分のスレッドで、他の Ractor を止めずに回収します。全 Ractor を止めるグローバル GC は、明示的な GC.start、共有可能オブジェクトの増加、終了した Ractor のヒープの回収のときだけ行われます。詳しくは GC を参照してください。

特異メソッド

self[sym] -> object | nilRuby 3.4 から[permalink][rdoc][edit]

(Symbol) → untyped

このメソッドを呼び出した Ractor の Ractor-local storage の sym に対応するデータを取り出します。 sym に対応するデータがなければ nil を返します。

[PARAM] sym:: Ractor-local storage のキーを指定します。
[RETURN]: Ractor-local storage に格納されている値を返します。

self[sym] = valRuby 3.4 から[permalink][rdoc][edit]

(Symbol, untyped) → untyped

[PARAM] sym:: Ractor-local storage のキーを指定します。
[PARAM] val:: 格納するデータを指定します。

count -> IntegerRuby 3.0 から[permalink][rdoc][edit]

() → Integer

実行中の Ractor の数を返します。

current -> RactorRuby 3.0 から[permalink][rdoc][edit]

() → untyped

このメソッドを呼び出された Ractor を返します。

main -> RactorRuby 3.0 から[permalink][rdoc][edit]

() → Ractor

main Ractor（プログラムの実行が開始された Ractor）を返します。

main? -> boolRuby 3.4 から[permalink][rdoc][edit]

() → boolish

このメソッドを呼び出した Ractor が main Ractor であるとき、true を返します。

make_shareable(obj, copy: false) -> objectRuby 3.0 から[permalink][rdoc][edit]

[T] (T obj, ?copy: boolish) → T

obj が shareable になるよう変換します。

obj が shareable でない場合、obj と obj が参照する shareable でないオブジェクトをすべて freeze します。

[PARAM] obj:: Shareable にしたいオブジェクトを指定します。
[PARAM] copy:: true の場合、obj を変更する代わりに obj のコピーを作成し shareable にします。
[EXCEPTION] Ractor::Error:: obj が IO のインスタンスである場合に発生します。

new(*args, name: nil) {|*args| ... } -> RactorRuby 3.0 から[permalink][rdoc][edit]

(*untyped args, ?name: string) { (?) → untyped } → Ractor

Ractor を生成して、ブロックの評価を開始します。生成した Ractor を返します。

[PARAM] args:: ブロックの引数として渡されます。値が shareable である場合はそのインスタンスが、そうでない場合はコピーが試みられた値が渡されます。コピーできない値であった場合は例外が発生します。
[PARAM] name:: Ractor の名前を指定します。

receive(timeout: nil) -> object | nilRuby 3.0 から[permalink][rdoc][edit]

recv(timeout: nil) -> object | nil

() → untyped

このメソッドを呼び出した Ractor の default port からメッセージを受信します。

[PARAM] timeout:: メッセージを待つ秒数を数値で指定します。nil の場合は、メッセージが届くまで待ち続けます。指定した秒数が経過しても届かなかった場合は nil を返します。0 を指定した場合はブロックしません。
[EXCEPTION] ArgumentError:: timeout が負の場合に発生します。

例: timeout を指定

p Ractor.receive(timeout: 0.2) # => nil

[SEE_ALSO] Ractor::Port#receive

select(*ports, timeout: nil) -> [object, object] | nilRuby 3.0 から[permalink][rdoc][edit]

(?) → Array[untyped]

引数で指定した Ractor または Ractor::Port のいずれかが受信可能になるまで待ち、受信可能になったものと受信した値の配列を返します。

timeout を指定した場合、その秒数が経過しても受信可能になったものが無ければ nil を返します。

[PARAM] ports:: 待つ対象の Ractor または Ractor::Port を指定します。
[PARAM] timeout:: 待つ秒数を数値で指定します。nil の場合は、受信可能になるまで待ち続けます。
[EXCEPTION] ArgumentError:: timeout が負の場合や、待つ対象を 1 つも指定しなかった場合に発生します。

例: timeout を指定

port = Ractor::Port.new
p Ractor.select(port, timeout: 0.1) # => nil

shareable?(obj) -> boolRuby 3.0 から[permalink][rdoc][edit]

(untyped obj) → bool

obj が shareable である場合、true を返します。

[PARAM] obj:: Shareable であるか判定したいオブジェクトを指定します。

Ruby 4.1 から、IO のインスタンスは freeze されていても shareable ではなく、false を返します。Ruby 4.0 までは、freeze された IO は shareable でした。

shareable_lambda(self: nil) { ... } -> ProcRuby 4.0 から[permalink][rdoc][edit]

[T] () { (?) [self: nil] → T } → ^(?) [self: nil] → T

[T, S] (self: S) { (?) [self: S] → T } → ^(?) [self: S] → T

Ractor.shareable_proc と同じですが、lambda である Proc を返します。

[PARAM] self:: 作成する Proc の self にするオブジェクトを指定します。shareable でなければなりません。デフォルトは nil です。
[EXCEPTION] Ractor::IsolationError:: self が shareable でない場合や、ブロックが shareable でないオブジェクトを参照している場合に発生します。

l = Ractor.shareable_lambda { 42 }
p Ractor.shareable?(l) # => true
p l.lambda?            # => true

[SEE_ALSO] Ractor.shareable_proc

shareable_proc(self: nil) { ... } -> ProcRuby 4.0 から[permalink][rdoc][edit]

[T] () { (?) [self: nil] → T } → ^(?) [self: nil] → T

[T, S] (self: S) { (?) [self: S] → T } → ^(?) [self: S] → T

与えられたブロックから shareable な Proc を作成して返します。

通常の Proc は shareable ではないため、他の Ractor に渡せません。このメソッドで作成した Proc は shareable になるため、複数の Ractor から利用できます。

作成される Proc の self は、キーワード引数 self で指定したオブジェクトになります。ブロックが外側のローカル変数を参照している場合、その値も shareable でなければなりません。

[PARAM] self:: 作成する Proc の self にするオブジェクトを指定します。shareable でなければなりません。デフォルトは nil です。
[EXCEPTION] Ractor::IsolationError:: self が shareable でない場合や、ブロックが shareable でないオブジェクトを参照している場合に発生します。

pr = Ractor.shareable_proc { 42 }
p Ractor.shareable?(pr) # => true
p pr.lambda?            # => false

p Ractor.shareable?(proc { 42 }) # => false （通常の Proc は shareable ではない）

# 他の Ractor に渡して呼び出せる
p Ractor.new(pr) {|p| p.call }.value # => 42

例: self を指定

p Ractor.shareable_proc { self }.call               # => nil
p Ractor.shareable_proc(self: 42) { self + 1 }.call # => 43

x = 1
p Ractor.shareable_proc { x }.call # => 1

Ractor.shareable_proc(self: Object.new) { self } # ~> Ractor::IsolationError

[SEE_ALSO] Ractor.shareable_lambda, Ractor.make_shareable

store_if_absent(key) { ... } -> objectRuby 3.4 から[permalink][rdoc][edit]

[A] (Symbol) { (nil) → A } → A

このメソッドを呼び出した Ractor の Ractor-local storage の key データがない場合、ブロックを評価した結果を格納します。格納した値を返します。

[PARAM] key:: Ractor-local storage のキーを指定します。

インスタンスメソッド

self << msg, move: false -> selfRuby 3.0 から[permalink][rdoc][edit]

send(msg, move: false) -> self

(untyped obj, ?move: boolish) → Ractor

Ractor の default port に対してメッセージを送信します。

[PARAM] msg:: 送信するメッセージを指定します。
[PARAM] move:: msg を「移動」する場合は true を指定します。

[SEE_ALSO] Ractor::Port#send

self[sym] -> object | nilRuby 3.0 から[permalink][rdoc][edit]

(interned sym) → untyped

カレント Ractor(このメソッドを呼び出した Ractor)の Ractor-local storage の sym に対応するデータを取り出します。 sym に対応するデータがなければ nil を返します。

self がカレント Ractor でない場合は例外が発生します。

[PARAM] sym:: Ractor-local storage のキーを指定します。
[EXCEPTION] RuntimeError:: self がカレント Ractor でない場合に発生します。

例

Ractor.current[:user] = "me"
p Ractor.current[:user] # => "me"
p Ractor.current[:none] # => nil

[SEE_ALSO] Ractor.[], Ractor.store_if_absent

self[sym] = valRuby 3.0 から[permalink][rdoc][edit]

[T] (interned sym, T val) → T

カレント Ractor(このメソッドを呼び出した Ractor)の Ractor-local storage の sym に val を格納します。

self がカレント Ractor でない場合は例外が発生します。

[PARAM] sym:: Ractor-local storage のキーを指定します。
[PARAM] val:: 格納するデータを指定します。
[EXCEPTION] RuntimeError:: self がカレント Ractor でない場合に発生します。

[SEE_ALSO] Ractor.[]=, Ractor.store_if_absent

alive? -> boolRuby 4.1 から[permalink][rdoc][edit]

self がまだ終了していなければ true を返します。

正常に終了した場合も、捕捉されなかった例外で終了した場合も、実行を終えた後は false を返します。

例

r = Ractor.new { Ractor.receive }
p r.alive? # => true
r << :done
r.join
p r.alive? # => false

[SEE_ALSO] Ractor#join, Ractor#value

close -> boolRuby 4.0 から[permalink][rdoc][edit]

Default port を閉じます。

self がこのメソッドを呼び出した Ractor ではない場合、Ractor::Error が発生します。

default_port -> Ractor::PortRuby 4.0 から[permalink][rdoc][edit]

() → Port[untyped]

self の default port を返します。

join -> RactorRuby 4.0 から[permalink][rdoc][edit]

() → self

self が終了するまで待ちます。 Ractor の実行が例外で終了した場合には、 Ractor#valueを呼び出し、その例外を再発生させます。

monitor(port) -> boolRuby 4.0 から[permalink][rdoc][edit]

[T < Symbol] (Port[T]) → untyped

port を self の監視ポートとして登録します。 self が終了すると、port は [self, :exited]（例外なく終了した場合）または [self, :aborted]（未処理の例外で終了した場合）という配列を受信します。複数の Ractor を 1 つの port で監視しても、どの Ractor が終了したかを判別できます。

監視を登録できた（self がまだ終了していない）場合は true を返します。 self が既に終了していた場合は false を返し、port は直ちに終了を表す配列を受信します。

name -> StringRuby 3.0 から[permalink][rdoc][edit]

() → String?

self の名前を返します。

[SEE_ALSO] Ractor.new

unmonitor(port) -> selfRuby 4.0 から[permalink][rdoc][edit]

(Port[untyped]) → self

Ractor#monitor で登録した port の監視を解除します。

value -> objectRuby 4.0 から[permalink][rdoc][edit]

() → untyped

self が終了するまで待ち、その Ractor のブロックが返した値を返します。 Ractor の実行が例外で終了した場合には、その例外を再発生させます。

値を取り出せるのは 1 回だけです。2 回目以降の呼び出しでは Ractor::Error が発生します。

[EXCEPTION] Ractor::Error:: 既に値を取り出している場合に発生します。

要約

目次

特異メソッド

インスタンスメソッド