類別 Ractor

傳回目前正在執行或封鎖（等待）的 Ractor 數目。

Ractor.count                   #=> 1
r = Ractor.new(name: 'example') { Ractor.yield(1) }
Ractor.count                   #=> 2 (main + example ractor)
r.take                         # wait for Ractor.yield(1)
r.take                         # wait until r will finish
Ractor.count                   #=> 1

# File ruby_3_3_0/ractor.rb, line 302
def self.count
  __builtin_cexpr! %q{
    ULONG2NUM(GET_VM()->ractor.cnt);
  }
end

傳回目前正在執行的 Ractor。

Ractor.current #=> #<Ractor:#1 running>

# File ruby_3_3_0/ractor.rb, line 288
def self.current
  __builtin_cexpr! %q{
    rb_ractor_self(rb_ec_ractor_ptr(ec));
  }
end

傳回主 ractor

# File ruby_3_3_0/ractor.rb, line 848
def self.main
  __builtin_cexpr! %q{
    rb_ractor_self(GET_VM()->ractor.main_ractor);
  }
end

讓 obj 在 ractor 之間可共用。

obj 及其所參照的所有物件都將凍結，除非它們已經可共用。

如果 copy 關鍵字為 true，它會在凍結物件之前複製物件，且不會修改 obj 或其內部物件。

請注意，此方法的規格和實作尚未成熟，未來可能會變更。

obj = ['test']
Ractor.shareable?(obj)     #=> false
Ractor.make_shareable(obj) #=> ["test"]
Ractor.shareable?(obj)     #=> true
obj.frozen?                #=> true
obj[0].frozen?             #=> true

# Copy vs non-copy versions:
obj1 = ['test']
obj1s = Ractor.make_shareable(obj1)
obj1.frozen?                        #=> true
obj1s.object_id == obj1.object_id   #=> true
obj2 = ['test']
obj2s = Ractor.make_shareable(obj2, copy: true)
obj2.frozen?                        #=> false
obj2s.frozen?                       #=> true
obj2s.object_id == obj2.object_id   #=> false
obj2s[0].object_id == obj2[0].object_id #=> false

另請參閱 Ractor 類別文件中的「可共用和不可共用物件」區段。

# File ruby_3_3_0/ractor.rb, line 825
def self.make_shareable obj, copy: false
  if copy
    __builtin_cexpr! %q{
      rb_ractor_make_shareable_copy(obj);
    }
  else
    __builtin_cexpr! %q{
      rb_ractor_make_shareable(obj);
    }
  end
end

使用 args 和區塊建立新的 Ractor。

指定的區塊 (Proc) 會被隔離（無法存取任何外部變數）。區塊內的 self 會參照目前的 Ractor。

r = Ractor.new { puts "Hi, I am #{self.inspect}" }
r.take
# Prints "Hi, I am #<Ractor:#2 test.rb:1 running>"

傳遞的任何 args 都會透過與透過 send/Ractor.receive 傳送的物件相同的規則傳播到區塊參數。如果 args 中的參數不可共用，它將會被複製（透過深度複製，這可能會很低效）。

arg = [1, 2, 3]
puts "Passing: #{arg} (##{arg.object_id})"
r = Ractor.new(arg) {|received_arg|
  puts "Received: #{received_arg} (##{received_arg.object_id})"
}
r.take
# Prints:
#   Passing: [1, 2, 3] (#280)
#   Received: [1, 2, 3] (#300)

Ractor 的 name 可設定為除錯目的

r = Ractor.new(name: 'my ractor') {}; r.take
p r
#=> #<Ractor:#3 my ractor test.rb:1 terminated>

# File ruby_3_3_0/ractor.rb, line 273
def self.new(*args, name: nil, &block)
  b = block # TODO: builtin bug
  raise ArgumentError, "must be called with a block" unless block
  if __builtin_cexpr!("RBOOL(ruby_single_main_ractor)")
    warn("Ractor is experimental, and the behavior may change in future versions of Ruby! " \
         "Also there are many implementation issues.", uplevel: 0, category: :experimental)
  end
  loc = caller_locations(1, 1).first
  loc = "#{loc.path}:#{loc.lineno}"
  __builtin_ractor_create(loc, name, args, b)
end

從目前 ractor 的輸入埠接收訊息（由另一個 ractor 的 send 傳送至該埠）。

r = Ractor.new do
  v1 = Ractor.receive
  puts "Received: #{v1}"
end
r.send('message1')
r.take
# Here will be printed: "Received: message1"

或者，可以使用私有執行個體方法 receive

r = Ractor.new do
  v1 = receive
  puts "Received: #{v1}"
end
r.send('message1')
r.take
# This prints: "Received: message1"

如果佇列為空，此方法會區塊。

r = Ractor.new do
  puts "Before first receive"
  v1 = Ractor.receive
  puts "Received: #{v1}"
  v2 = Ractor.receive
  puts "Received: #{v2}"
end
wait
puts "Still not received"
r.send('message1')
wait
puts "Still received only one"
r.send('message2')
r.take

輸出

Before first receive
Still not received
Received: message1
Still received only one
Received: message2

如果對 ractor 呼叫 close_incoming，且輸入佇列中沒有更多訊息，此方法會引發 Ractor::ClosedError

Ractor.new do
  close_incoming
  receive
end
wait
# in `receive': The incoming port is already closed => #<Ractor:#2 test.rb:1 running> (Ractor::ClosedError)

# File ruby_3_3_0/ractor.rb, line 430
def self.receive
  __builtin_cexpr! %q{
    ractor_receive(ec, rb_ec_ractor_ptr(ec))
  }
end

僅接收特定訊息。

Ractor.receive_if 可以取代 Ractor.receive，並在區塊中提供樣式（或任何篩選器），您可以選擇接受 ractor 輸入佇列中可用的訊息。

r = Ractor.new do
  p Ractor.receive_if{|msg| msg.match?(/foo/)} #=> "foo3"
  p Ractor.receive_if{|msg| msg.match?(/bar/)} #=> "bar1"
  p Ractor.receive_if{|msg| msg.match?(/baz/)} #=> "baz2"
end
r << "bar1"
r << "baz2"
r << "foo3"
r.take

這會輸出

foo3
bar1
baz2

如果區塊傳回真值，訊息會從輸入佇列中移除並傳回。否則，訊息會保留在輸入佇列中，且下一個訊息會由指定的區塊檢查。

如果輸入佇列中沒有訊息，此方法會區塊，直到有新訊息到達。

如果區塊被 break/return/exception/throw 跳脫，訊息會從輸入佇列中移除，就像傳回真值一樣。

r = Ractor.new do
  val = Ractor.receive_if{|msg| msg.is_a?(Array)}
  puts "Received successfully: #{val}"
end

r.send(1)
r.send('test')
wait
puts "2 non-matching sent, nothing received"
r.send([1, 2, 3])
wait

列印

2 non-matching sent, nothing received
Received successfully: [1, 2, 3]

請注意，您無法在指定的區塊中遞迴呼叫 receive/receive_if。您不應在區塊中執行訊息過濾以外的任何工作。

Ractor.current << true
Ractor.receive_if{|msg| Ractor.receive}
#=> `receive': can not call receive/receive_if recursively (Ractor::Error)

# File ruby_3_3_0/ractor.rb, line 509
def self.receive_if &b
  Primitive.ractor_receive_if b
end

等待任何 ractor 在其輸出埠中有內容，從此 ractor 讀取，然後傳回該 ractor 和收到的物件。

r1 = Ractor.new {Ractor.yield 'from 1'}
r2 = Ractor.new {Ractor.yield 'from 2'}

r, obj = Ractor.select(r1, r2)

puts "received #{obj.inspect} from #{r.inspect}"
# Prints: received "from 1" from #<Ractor:#2 test.rb:1 running>
# But could just as well print "from r2" here, either prints could be first.

如果指定的反應器之一是目前的反應器，且已選取，r 將包含 :receive 符號，而不是反應器物件。

r1 = Ractor.new(Ractor.current) do |main|
  main.send 'to main'
  Ractor.yield 'from 1'
end
r2 = Ractor.new do
  Ractor.yield 'from 2'
end

r, obj = Ractor.select(r1, r2, Ractor.current)
puts "received #{obj.inspect} from #{r.inspect}"
# Could print: received "to main" from :receive

如果提供 yield_value，如果另一個反應器呼叫 take，則可能會產生該值。在此情況下，會傳回配對 [:yield, nil]

r1 = Ractor.new(Ractor.current) do |main|
  puts "Received from main: #{main.take}"
end

puts "Trying to select"
r, obj = Ractor.select(r1, Ractor.current, yield_value: 123)
wait
puts "Received #{obj.inspect} from #{r.inspect}"

這會列印

Trying to select
Received from main: 123
Received nil from :yield

move 布林旗標定義是否會複製 (預設) 或移動產生的值。

# File ruby_3_3_0/ractor.rb, line 358
def self.select(*ractors, yield_value: yield_unspecified = true, move: false)
  raise ArgumentError, 'specify at least one ractor or `yield_value`' if yield_unspecified && ractors.empty?

  if ractors.delete Ractor.current
    do_receive = true
  else
    do_receive = false
  end

  __builtin_ractor_select_internal ractors, do_receive, !yield_unspecified, yield_value, move
end

檢查物件是否可由反應器共用。

Ractor.shareable?(1)            #=> true -- numbers and other immutable basic values are frozen
Ractor.shareable?('foo')        #=> false, unless the string is frozen due to # frozen_string_literal: true
Ractor.shareable?('foo'.freeze) #=> true

另請參閱反應器類別文件中的「可共用和不可共用物件」區段。

# File ruby_3_3_0/ractor.rb, line 784
def self.shareable? obj
  __builtin_cexpr! %q{
    RBOOL(rb_ractor_shareable_p(obj));
  }
end

傳送訊息至目前的反應器傳出埠，以供 take 接受。

r = Ractor.new {Ractor.yield 'Hello from ractor'}
puts r.take
# Prints: "Hello from ractor"

此方法會封鎖，且僅在有人使用傳送的訊息時才會傳回。

r = Ractor.new do
  Ractor.yield 'Hello from ractor'
  puts "Ractor: after yield"
end
wait
puts "Still not taken"
puts r.take

這會列印

Still not taken
Hello from ractor
Ractor: after yield

如果傳出埠已使用 close_outgoing 關閉，此方法會引發

r = Ractor.new do
  close_outgoing
  Ractor.yield 'Hello from ractor'
end
wait
# `yield': The outgoing-port is already closed (Ractor::ClosedError)

move 參數的意義與 send 相同。

# File ruby_3_3_0/ractor.rb, line 643
def self.yield(obj, move: false)
  __builtin_cexpr! %q{
    ractor_yield(ec, rb_ec_ractor_ptr(ec), obj, move)
  }
end

從反應器本機儲存空間取得值

# File ruby_3_3_0/ractor.rb, line 838
def [](sym)
  Primitive.ractor_local_value(sym)
end

在反應器本機儲存空間設定值

# File ruby_3_3_0/ractor.rb, line 843
def []=(sym, val)
  Primitive.ractor_local_value_set(sym, val)
end

關閉傳入埠，並傳回是否已關閉。在反應器中進一步嘗試 Ractor.receive，以及傳送至反應器的 send，將會因 Ractor::ClosedError 而失敗。

r = Ractor.new {sleep(500)}
r.close_incoming  #=> false
r.close_incoming  #=> true
r.send('test')
# Ractor::ClosedError (The incoming-port is already closed)

# File ruby_3_3_0/ractor.rb, line 749
def close_incoming
  __builtin_cexpr! %q{
    ractor_close_incoming(ec, RACTOR_PTR(self));
  }
end

關閉傳出埠，並傳回是否已關閉。在反應器中進一步嘗試 Ractor.yield，以及從反應器 take，將會因 Ractor::ClosedError 而失敗。

r = Ractor.new {sleep(500)}
r.close_outgoing  #=> false
r.close_outgoing  #=> true
r.take
# Ractor::ClosedError (The outgoing-port is already closed)

# File ruby_3_3_0/ractor.rb, line 767
def close_outgoing
  __builtin_cexpr! %q{
    ractor_close_outgoing(ec, RACTOR_PTR(self));
  }
end

在 Ractor.new 中設定的名稱，或為 nil。

# File ruby_3_3_0/ractor.rb, line 729
def name
  __builtin_cexpr! %q{RACTOR_PTR(self)->name}
end

傳送訊息至 Ractor 的輸入佇列，以供 Ractor.receive 接受。

r = Ractor.new do
  value = Ractor.receive
  puts "Received #{value}"
end
r.send 'message'
# Prints: "Received: message"

此方法為非封鎖式（即使 ractor 尚未準備好接收任何內容，也會立即傳回）

r = Ractor.new {sleep(5)}
r.send('test')
puts "Sent successfully"
# Prints: "Sent successfully" immediately

嘗試傳送至已完成執行的 ractor 會引發 Ractor::ClosedError。

r = Ractor.new {}
r.take
p r
# "#<Ractor:#6 (irb):23 terminated>"
r.send('test')
# Ractor::ClosedError (The incoming-port is already closed)

如果對 ractor 呼叫 close_incoming，此方法也會引發 Ractor::ClosedError。

r =  Ractor.new do
  sleep(500)
  receive
end
r.close_incoming
r.send('test')
# Ractor::ClosedError (The incoming-port is already closed)
# The error is raised immediately, not when the ractor tries to receive

如果 obj 為不可共用，預設會透過深度複製將其複製至接收 ractor 中。如果傳遞 move: true，物件會移動至接收 ractor 中，且傳送者將無法存取。

r = Ractor.new {puts "Received: #{receive}"}
msg = 'message'
r.send(msg, move: true)
r.take
p msg

這會列印

Received: message
in `p': undefined method `inspect' for #<Ractor::MovedObject:0x000055c99b9b69b8>

物件及其部分的所有參照都會對傳送者失效。

r = Ractor.new {puts "Received: #{receive}"}
s = 'message'
ary = [s]
copy = ary.dup
r.send(ary, move: true)

s.inspect
# Ractor::MovedError (can not send any methods to a moved object)
ary.class
# Ractor::MovedError (can not send any methods to a moved object)
copy.class
# => Array, it is different object
copy[0].inspect
# Ractor::MovedError (can not send any methods to a moved object)
# ...but its item was still a reference to `s`, which was moved

如果物件可共用，move: true 對其沒有影響

r = Ractor.new {puts "Received: #{receive}"}
s = 'message'.freeze
r.send(s, move: true)
s.inspect #=> "message", still available

# File ruby_3_3_0/ractor.rb, line 599
def send(obj, move: false)
  __builtin_cexpr! %q{
    ractor_send(ec, RACTOR_PTR(self), obj, move)
  }
end

從 ractor 的輸出埠取得訊息，該訊息是由 Ractor.yield 或在 ractor 終止時放入的。

r = Ractor.new do
  Ractor.yield 'explicit yield'
  'last value'
end
puts r.take #=> 'explicit yield'
puts r.take #=> 'last value'
puts r.take # Ractor::ClosedError (The outgoing-port is already closed)

最後一個值也會傳送到輸出埠，表示 take 可用作 Thread#join 的類比（「等到 ractor 完成」）。但是，如果有人已使用該訊息，它會引發錯誤。

如果輸出埠已使用 close_outgoing 關閉，此方法會引發 Ractor::ClosedError。

r = Ractor.new do
  sleep(500)
  Ractor.yield 'Hello from ractor'
end
r.close_outgoing
r.take
# Ractor::ClosedError (The outgoing-port is already closed)
# The error would be raised immediately, not when ractor will try to receive

如果在 Ractor 中引發未捕捉的例外狀況，它會透過 take 作為 Ractor::RemoteError 進行傳播。

r = Ractor.new {raise "Something weird happened"}

begin
  r.take
rescue => e
  p e              #  => #<Ractor::RemoteError: thrown by remote Ractor.>
  p e.ractor == r  # => true
  p e.cause        # => #<RuntimeError: Something weird happened>
end

Ractor::ClosedError 是 StopIteration 的子類別，因此 ractor 的終止會中斷接收此訊息且未傳播錯誤的任何迴圈

r = Ractor.new do
  3.times {|i| Ractor.yield "message #{i}"}
  "finishing"
end

loop {puts "Received: " + r.take}
puts "Continue successfully"

這會列印

Received: message 0
Received: message 1
Received: message 2
Received: finishing
Continue successfully

# File ruby_3_3_0/ractor.rb, line 710
def take
  __builtin_cexpr! %q{
    ractor_take(ec, RACTOR_PTR(self))
  }
end

與 Ractor.receive 相同

# File ruby_3_3_0/ractor.rb, line 441
        def receive
  __builtin_cexpr! %q{
    ractor_receive(ec, rb_ec_ractor_ptr(ec))
  }
end

與 Ractor.receive_if 相同

# File ruby_3_3_0/ractor.rb, line 514
        def receive_if &b
  Primitive.ractor_receive_if b
end