class Ractor

Ractor.new creates a new Ractor, which can run in parallel with other ractors.

# The simplest ractor
r = Ractor.new {puts "I am in Ractor!"}
r.join # wait for it to finish
# Here, "I am in Ractor!" is printed

Ractors do not share all objects with each other. There are two main benefits to this: across ractors, thread-safety concerns such as data-races and race-conditions are not possible. The other benefit is parallelism.

To achieve this, object sharing is limited across ractors. Unlike in threads, ractors can’t access all the objects available in other ractors. For example, objects normally available through variables in the outer scope are prohibited from being used across ractors.

a = 1
r = Ractor.new {puts "I am in Ractor! a=#{a}"}
# fails immediately with
# ArgumentError (can not isolate a Proc because it accesses outer variables (a).)

The object must be explicitly shared:

a = 1
r = Ractor.new(a) { |a1| puts "I am in Ractor! a=#{a1}"}

On CRuby (the default implementation), the Global Virtual Machine Lock (GVL) is held per ractor, so ractors can run in parallel. This is unlike the situation with threads on CRuby.

Instead of accessing shared state, objects should be passed to and from ractors by sending and receiving them as messages.

a = 1
r = Ractor.new do
  a_in_ractor = receive # receive blocks the Thread until our default port gets sent a message
  puts "I am in Ractor! a=#{a_in_ractor}"
end
r.send(a)  # pass it
r.join
# Here, "I am in Ractor! a=1" is printed

In addition to that, any arguments passed to Ractor.new are passed to the block and available there as if received by Ractor.receive, and the last block value can be received with Ractor#value.

Shareable and unshareable objects

When an object is sent to a ractor, it’s important to understand whether the object is shareable or unshareable. Most Ruby objects are unshareable objects. Even frozen objects can be unshareable if they contain (through their instance variables) unfrozen objects.

Shareable objects are those which can be used by several ractors at once without compromising thread-safety, for example numbers, true and false. Ractor.shareable? allows you to check this, and Ractor.make_shareable tries to make the object shareable if it’s not already and gives an error if it can’t do it.

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

ary = ['hello', 'world']
ary.frozen?                 #=> false
ary[0].frozen?              #=> false
Ractor.make_shareable(ary)
ary.frozen?                 #=> true
ary[0].frozen?              #=> true
ary[1].frozen?              #=> true

When a shareable object is sent via send, no additional processing occurs on it and it becomes usable by both ractors. When an unshareable object is sent, it can be either copied or moved. Copying is the default, and it copies the object fully by deep cloning (Object#clone) the non-shareable parts of its structure.

data = ['foo'.dup, 'bar'.freeze]
r = Ractor.new do
  data2 = Ractor.receive
  puts "In ractor: #{data2.object_id}, #{data2[0].object_id}, #{data2[1].object_id}"
end
r.send(data)
r.join
puts "Outside  : #{data.object_id}, #{data[0].object_id}, #{data[1].object_id}"

This will output something like:

In ractor: 8, 16, 24
Outside  : 32, 40, 24

Note that the object ids of the array and the non-frozen string inside the array have changed in the ractor because they are different objects. The second array’s element, which is a shareable frozen string, is the same object.

Deep cloning of objects may be slow, and sometimes impossible. Alternatively, move: true may be used during sending. This will move the unshareable object to the receiving ractor, making it inaccessible to the sending ractor.

data = ['foo', 'bar']
r = Ractor.new do
  data_in_ractor = Ractor.receive
  puts "In ractor: #{data_in_ractor.object_id}, #{data_in_ractor[0].object_id}"
end
r.send(data, move: true)
r.join
puts "Outside: moved? #{Ractor::MovedObject === data}"
puts "Outside: #{data.inspect}"

This will output:

In ractor: 100, 120
Outside: moved? true
test.rb:9:in `method_missing': can not send any methods to a moved object (Ractor::MovedError)

Notice that even inspect and more basic methods like __id__ are inaccessible on a moved object.

Class and Module objects are shareable and their class/module definitions are shared between ractors. Ractor objects are also shareable. All operations on shareable objects are thread-safe across ractors. Defining mutable, shareable objects in Ruby is not possible, but C extensions can introduce them.

It is prohibited to access (get) instance variables of shareable objects in other ractors if the values of the variables aren’t shareable. This can occur because modules/classes are shareable, but they can have instance variables whose values are not. In non-main ractors, it’s also prohibited to set instance variables on classes/modules (even if the value is shareable).

class C
  class << self
    attr_accessor :tricky
  end
end

C.tricky = "unshareable".dup

r = Ractor.new(C) do |cls|
  puts "I see #{cls}"
  puts "I can't see #{cls.tricky}"
  cls.tricky = true # doesn't get here, but this would also raise an error
end
r.join
# I see C
# can not access instance variables of classes/modules from non-main Ractors (RuntimeError)

Ractors can access constants if they are shareable. The main Ractor is the only one that can access non-shareable constants.

GOOD = 'good'.freeze
BAD = 'bad'.dup

r = Ractor.new do
  puts "GOOD=#{GOOD}"
  puts "BAD=#{BAD}"
end
r.join
# GOOD=good
# can not access non-shareable objects in constant Object::BAD by non-main Ractor. (NameError)

# Consider the same C class from above

r = Ractor.new do
  puts "I see #{C}"
  puts "I can't see #{C.tricky}"
end
r.join
# I see C
# can not access instance variables of classes/modules from non-main Ractors (RuntimeError)

See also the description of # shareable_constant_value pragma in Comments syntax explanation.

Ractors vs threads

Each ractor has its own main Thread. New threads can be created from inside ractors (and, on CRuby, they share the GVL with other threads of this ractor).

r = Ractor.new do
  a = 1
  Thread.new {puts "Thread in ractor: a=#{a}"}.join
end
r.join
# Here "Thread in ractor: a=1" will be printed

Note on code examples

In the examples below, sometimes we use the following method to wait for ractors to make progress or finish.

def wait
  sleep(0.1)
end

This is **only for demonstration purposes** and shouldn’t be used in a real code. Most of the time, join is used to wait for ractors to finish and Ractor.receive is used to wait for messages.

Reference

See Ractor design doc for more details.

Public Class Methods

[] (sym)

Source

# File ractor.rb, line 490
def self.[](sym)
  Primitive.ractor_local_value(sym)
end

Gets a value from ractor-local storage for the current Ractor.

[]= (sym, val)

Source

# File ractor.rb, line 495
def self.[]=(sym, val)
  Primitive.ractor_local_value_set(sym, val)
end

Sets a value in ractor-local storage for the current Ractor.

count ()

Source

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

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

Ractor.count                   #=> 1
r = Ractor.new(name: 'example') { Ractor.receive }
Ractor.count                   #=> 2 (main + example ractor)
r << 42                        # r's Ractor.receive will resume
r.join                         # wait for r's termination
Ractor.count                   #=> 1

current ()

Source

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

Returns the currently executing Ractor.

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

main ()

Source

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

Returns the main ractor.

main? ()

Source

# File ractor.rb, line 526
def self.main?
  __builtin_cexpr! %q{
    RBOOL(GET_VM()->ractor.main_ractor == rb_ec_ractor_ptr(ec))
  }
end

Returns true if the current ractor is the main ractor.

make_shareable(obj, copy: false) → shareable_obj

Source

# File ractor.rb, line 459
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

Makes 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.

new(*args, name: nil) {|*args| block } → ractor

Source

# File ractor.rb, line 229
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)")
    Kernel.warn("Ractor API is experimental and may change in future versions of Ruby.",
                uplevel: 0, category: :experimental)
  end
  loc = caller_locations(1, 1).first
  loc = "#{loc.path}:#{loc.lineno}"
  __builtin_ractor_create(loc, name, args, b)
end

Creates a new Ractor with args and a block.

The given block (Proc) is 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.join
# 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.join
# 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.join
p r
#=> #<Ractor:#3 my ractor test.rb:1 terminated>

receive → obj

Source

# File ractor.rb, line 349
def self.receive
  Ractor.current.default_port.receive
end

Receives a message from the current ractor’s default port.

Also aliased as: recv

recv

Alias for: receive

select(*ractors_or_ports) → [ractor or port, obj]

Source

# File ractor.rb, line 308
def self.select(*ports)
  raise ArgumentError, 'specify at least one Ractor::Port or Ractor' if ports.empty?

  monitors = {} # Ractor::Port => Ractor

  ports = ports.map do |arg|
    case arg
    when Ractor
      port = Ractor::Port.new
      monitors[port] = arg
      arg.monitor port
      port
    when Ractor::Port
      arg
    else
      raise ArgumentError, "should be Ractor::Port or Ractor"
    end
  end

  begin
    result_port, obj = __builtin_ractor_select_internal(ports)

    if r = monitors[result_port]
      [r, r.value]
    else
      [result_port, obj]
    end
  ensure
    # close all ports for join
    monitors.each do |port, r|
      r.unmonitor port
      port.close
    end
  end
end

Blocks the current Thread until one of the given ports has received a message. Returns an array of two elements where the first element is the Port and the second is the received object. This method can also accept Ractor objects themselves, and in that case will wait until one has terminated and return a two-element array where the first element is the ractor and the second is its termination value.

p1, p2 = Ractor::Port.new, Ractor::Port.new
ps = [p1, p2]
rs = 2.times.map do |i|
  Ractor.new(ps.shift, i) do |p, i|
    sleep rand(0.99)
    p.send("r#{i}")
    sleep rand(0.99)
    "r#{i} done"
  end
end

waiting_on = [p1, p2, *rs]
until waiting_on.empty?
  received_on, obj = Ractor.select(*waiting_on)
  waiting_on.delete(received_on)
  puts obj
end

# r0
# r1
# r1 done
# r0 done

The following example is almost equivalent to ractors.map(&:value) except the thread is unblocked when any of the ractors has terminated as opposed to waiting for their termination in the array element order.

values = []
until ractors.empty?
  r, val = Ractor.select(*ractors)
  ractors.delete(r)
  values << val
end

shareable?(obj) → true | false

Source

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

Checks if the object is shareable by ractors.

Ractor.shareable?(1)            #=> true -- numbers are shareable
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.

shareable_lambda(self: nil){} → shareable lambda

Source

# File ractor.rb, line 681
def self.shareable_lambda self: nil
  Primitive.attr! :use_block

  __builtin_cexpr!(%Q{
    ractor_shareable_proc(ec, *LOCAL_PTR(self), true)
  })
end

Same as Ractor.shareable_proc, but returns a lambda Proc.

shareable_proc(self: nil){} → shareable proc

Source

# File ractor.rb, line 667
def self.shareable_proc self: nil
  Primitive.attr! :use_block

  __builtin_cexpr!(%Q{
    ractor_shareable_proc(ec, *LOCAL_PTR(self), false)
  })
end

Returns a shareable copy of the given block’s Proc. The value of self in the Proc will be replaced with the value passed via the ‘self:` keyword, or nil if not given.

In a shareable Proc, access to any outer variables if prohibited.

a = 42
Ractor.shareable_proc{ p a }
#=> can not isolate a Proc because it accesses outer variables (a). (ArgumentError)

The value of ‘self` in the Proc must be a shareable object.

Ractor.shareable_proc(self: self){}
#=> self should be shareable: main (Ractor::IsolationError)

store_if_absent(key){ init_block }

Source

# File ractor.rb, line 513
def self.store_if_absent(sym)
  Primitive.attr! :use_block
  Primitive.ractor_local_value_store_if_absent(sym)
end

If the corresponding ractor-local value is not set, yields a value with init_block and stores the value in a thread-safe manner. This method returns the stored value.

(1..10).map{
  Thread.new(it){|i|
    Ractor.store_if_absent(:s){ f(); i }
    #=> return stored value of key :s
  }
}.map(&:value).uniq.size #=> 1 and f() is called only once

Public Instance Methods

Alias for: send

[] (sym)

Source

# File ractor.rb, line 473
def [](sym)
  if (self != Ractor.current)
    raise RuntimeError, "Cannot get ractor local storage for non-current ractor"
  end
  Primitive.ractor_local_value(sym)
end

Gets a value from ractor-local storage for the current Ractor. Obsolete, use Ractor.[] instead.

[]= (sym, val)

Source

# File ractor.rb, line 482
def []=(sym, val)
  if (self != Ractor.current)
    raise RuntimeError, "Cannot set ractor local storage for non-current ractor"
  end
  Primitive.ractor_local_value_set(sym, val)
end

Sets a value in ractor-local storage for the current Ractor. Obsolete, use Ractor.[]= instead.

close → true | false

Source

# File ractor.rb, line 403
def close
  default_port.close
end

Closes the default port. Closing a port is allowed only by the ractor which created the port. Therefore, the receiver must be the current ractor.

default_port → port object

Source

# File ractor.rb, line 566
def default_port
  __builtin_cexpr! %q{
    ractor_default_port_value(RACTOR_PTR(self))
  }
end

Returns the default port of the Ractor.

inspect ()

Source

# File ractor.rb, line 374
def inspect
  loc  = __builtin_cexpr! %q{ RACTOR_PTR(self)->loc }
  name = __builtin_cexpr! %q{ RACTOR_PTR(self)->name }
  id   = __builtin_cexpr! %q{ UINT2NUM(rb_ractor_id(RACTOR_PTR(self))) }
  status = __builtin_cexpr! %q{
    rb_str_new2(ractor_status_str(RACTOR_PTR(self)->status_))
  }
  "#<Ractor:##{id}#{name ? ' '+name : ''}#{loc ? " " + loc : ''} #{status}>"
end

Also aliased as: to_s

join → self

Source

# File ractor.rb, line 585
def join
  port = Port.new

  self.monitor port
  if port.receive == :aborted
    __builtin_ractor_value
  end

  self
ensure
  port.close
end

Waits for the termination of the Ractor. If the Ractor was aborted (terminated by an unhandled exception), the exception is raised in the current ractor.

Ractor.new{}.join #=> ractor

Ractor.new{ raise "foo" }.join
#=> raises the exception "foo (RuntimeError)"

monitor(port) → self

Source

# File ractor.rb, line 634
def monitor port
  __builtin_ractor_monitor(port)
end

Registers the port as a monitoring port for this ractor. When the ractor terminates, the port receives a Symbol object.

:exited is sent if the ractor terminates without an unhandled exception.

:aborted is sent if the ractor terminates by an unhandled exception.

r = Ractor.new{ some_task() }
r.monitor(port = Ractor::Port.new)
port.receive #=> :exited and r is terminated

r = Ractor.new{ raise "foo" }
r.monitor(port = Ractor::Port.new)
port.receive #=> :aborted and r is terminated by the RuntimeError "foo"

name ()

Source

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

Returns the name set in Ractor.new, or nil.

recv ()

Alias for: receive

send(msg, move: false) → self

Source

# File ractor.rb, line 368
def send(...)
  default_port.send(...)
  self
end

This is equivalent to Port#send to the ractor’s default_port.

Also aliased as: <<

to_s ()

Alias for: inspect

unmonitor(port) → self

Source

# File ractor.rb, line 644
def unmonitor port
  __builtin_ractor_unmonitor(port)
end

Unregisters the port from the monitoring ports for this ractor.

value → obj

Source

# File ractor.rb, line 611
def value
  self.join
  __builtin_ractor_value
end

Waits for ractor to complete and returns its value or raises the exception which terminated the Ractor. The termination value will be moved to the calling Ractor. Therefore, at most 1 Ractor can receive another ractor’s termination value.

r = Ractor.new{ [1, 2] }
r.value #=> [1, 2] (unshareable object)

Ractor.new(r){|r| r.value} #=> Ractor::Error

Private Instance Methods

receive ()

Source

# File ractor.rb, line 358
        def receive
  default_port.receive
end

same as Ractor.receive

Also aliased as: recv