class Ractor

Returns the number of Ractors currently running or blocking (waiting).

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_preview3/ractor.rb, line 302
def self.count
  __builtin_cexpr! %q{
    ULONG2NUM(GET_VM()->ractor.cnt);
  }
end

Returns the currently executing Ractor.

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

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

returns main ractor

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

Make obj shareable between ractors.

obj and all the objects it refers to will be frozen, unless they are already shareable.

If copy keyword is true, it will copy objects before freezing them, and will not modify obj or its internal objects.

Note that the specification and implementation of this method are not mature and may be changed in the future.

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

See also the “Shareable and unshareable objects” section in the Ractor class docs.

# File ruby_3_3_0_preview3/ractor.rb, line 941
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

Create a new Ractor with args and a block.

The given block (Proc) will be isolated (can’t access any outer variables). self inside the block will refer to the current Ractor.

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

Any args passed are propagated to the block arguments by the same rules as objects sent via send/Ractor.receive. If an argument in args is not shareable, it will be copied (via deep cloning, which might be inefficient).

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’s name can be set for debugging purposes:

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

# File ruby_3_3_0_preview3/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

Receive a message from the incoming port of the current ractor (which was sent there by send from another ractor).

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

Alternatively, the private instance method receive may be used:

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

The method blocks if the queue is empty.

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

Output:

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

If close_incoming was called on the ractor, the method raises Ractor::ClosedError if there are no more messages in the incoming queue:

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_preview3/ractor.rb, line 546
def self.receive
  __builtin_cexpr! %q{
    ractor_receive(ec, rb_ec_ractor_ptr(ec))
  }
end

Receive only a specific message.

Instead of Ractor.receive, Ractor.receive_if can be given a pattern (or any filter) in a block and you can choose the messages to accept that are available in your ractor’s incoming queue.

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

This will output:

foo3
bar1
baz2

If the block returns a truthy value, the message is removed from the incoming queue and returned. Otherwise, the message remains in the incoming queue and the next messages are checked by the given block.

If there are no messages left in the incoming queue, the method will block until new messages arrive.

If the block is escaped by break/return/exception/throw, the message is removed from the incoming queue as if a truthy value had been returned.

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

Prints:

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

Note that you can not call receive/receive_if in the given block recursively. You should not do any tasks in the block other than message filtration.

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

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

Wait for any ractor to have something in its outgoing port, read from this ractor, and then return that ractor and the object received.

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.

If one of the given ractors is the current ractor, and it is selected, r will contain the :receive symbol instead of the ractor object.

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

If yield_value is provided, that value may be yielded if another ractor is calling take. In this case, the pair [:yield, nil] is returned:

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}"

This will print:

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

move boolean flag defines whether yielded value will be copied (default) or moved.

# File ruby_3_3_0_preview3/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?

  begin
    if ractors.delete Ractor.current
      do_receive = true
    else
      do_receive = false
    end
    selector = Ractor::Selector.new(*ractors)

    if yield_unspecified
      selector.wait receive: do_receive
    else
      selector.wait receive: do_receive, yield_value: yield_value, move: move
    end
  ensure
    selector.clear
  end
end

Checks if the object is shareable by ractors.

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

See also the “Shareable and unshareable objects” section in the Ractor class docs.

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

Send a message to the current ractor’s outgoing port to be accepted by take.

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

This method is blocking, and will return only when somebody consumes the sent message.

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

This will print:

Still not taken
Hello from ractor
Ractor: after yield

If the outgoing port was closed with close_outgoing, the method will raise:

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

The meaning of the move argument is the same as for send.

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

get a value from ractor-local storage

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

set a value in ractor-local storage

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

Closes the incoming port and returns whether it was already closed. All further attempts to Ractor.receive in the ractor, and send to the ractor will fail with 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_preview3/ractor.rb, line 865
def close_incoming
  __builtin_cexpr! %q{
    ractor_close_incoming(ec, RACTOR_PTR(self));
  }
end

Closes the outgoing port and returns whether it was already closed. All further attempts to Ractor.yield in the ractor, and take from the ractor will fail with 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_preview3/ractor.rb, line 883
def close_outgoing
  __builtin_cexpr! %q{
    ractor_close_outgoing(ec, RACTOR_PTR(self));
  }
end

The name set in Ractor.new, or nil.

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

Send a message to a Ractor’s incoming queue to be accepted by Ractor.receive.

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

The method is non-blocking (will return immediately even if the ractor is not ready to receive anything):

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

An attempt to send to a ractor which already finished its execution will raise 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)

If close_incoming was called on the ractor, the method also raises 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

If the obj is unshareable, by default it will be copied into the receiving ractor by deep cloning. If move: true is passed, the object is moved into the receiving ractor and becomes inaccessible to the sender.

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

This prints:

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

All references to the object and its parts will become invalid to the sender.

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

If the object is shareable, move: true has no effect on it:

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

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

Get a message from the ractor’s outgoing port, which was put there by Ractor.yield or at ractor’s termination.

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)

The fact that the last value is also sent to the outgoing port means that take can be used as an analog of Thread#join (“just wait until ractor finishes”). However, it will raise if somebody has already consumed that message.

If the outgoing port was closed with close_outgoing, the method will raise 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

If an uncaught exception is raised in the Ractor, it is propagated by take as a 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 is a descendant of StopIteration, so the termination of the ractor will break out of any loops that receive this message without propagating the error:

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

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

This will print:

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

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

same as Ractor.receive

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

same as Ractor.receive_if

# File ruby_3_3_0_preview3/ractor.rb, line 630
        def receive_if &b
  Primitive.ractor_receive_if b
end