Class: Ractor::Wrapper::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/ractor/wrapper.rb

Overview

Configuration for a Ractor::Wrapper. An instance of this class is yielded by #initialize if a block is provided. Any settings made to the Configuration before the block returns take effect when the Wrapper is constructed.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#enable_logging=(value) ⇒ Object

Enable or disable internal debug logging.

Parameters:

  • value (Boolean) 


254
255
256
 
# File 'lib/ractor/wrapper.rb', line 254

def enable_logging=(value)
  @enable_logging = value ? true : false
end

#name=(value) ⇒ Object

Set the name of the wrapper. This is shown in logging and is also used as the name of the wrapping Ractor.

Parameters:

  • value (String, nil) 


245
246
247
 
# File 'lib/ractor/wrapper.rb', line 245

def name=(value)
  @name = value ? value.to_s.freeze : nil
end

#threads=(value) ⇒ Object

Set the number of worker threads. If the underlying object is thread-safe, a value of 2 or more allows concurrent calls. Leave at the default of 0 to handle calls sequentially without worker threads.

The number of worker threads only needs to reflect the desired concurrency of independent calls. It does not need to be sized to the depth of re-entrant block calls, because suspended methods do not occupy a worker thread while waiting for a block to complete.

Parameters:

  • value (Integer) 


270
271
272
273
274
 
# File 'lib/ractor/wrapper.rb', line 270

def threads=(value)
  value = value.to_i
  value = 0 if value.negative?
  @threads = value
end

#use_current_ractor=(value) ⇒ Object

If set to true, the wrapper server runs as Thread(s) inside the current Ractor rather than spawning a new isolated Ractor. Use this for objects that cannot be moved between Ractors.

Parameters:

  • value (Boolean) 


283
284
285
 
# File 'lib/ractor/wrapper.rb', line 283

def use_current_ractor=(value)
  @use_current_ractor = value ? true : false
end

Instance Method Details

#configure_method(method_name = nil, arguments: nil, results: nil, block_arguments: nil, block_results: nil, block_environment: nil) ⇒ Object

Configure how argument and return values are communicated for the given method.

In general, the following values are recognized for the data-moving settings:

  • :copy - Method arguments or return values that are not shareable, are deep copied when communicated between the caller and the object.
  • :move - Method arguments or return values that are not shareable, are moved when communicated between the caller and the object. This means they are no longer available to the source; that is, the caller can no longer access objects that were moved to method arguments, and the wrapped object can no longer access objects that were used as return values.
  • :void - This option is available for return values and block results. It disables return values for the given method, and is intended to avoid copying or moving objects that are not intended to be return values. The recipient will receive nil.

The following settings are recognized for the block_environment setting:

  • :caller - Blocks are executed in the caller's context. This means the wrapper sends a message back to the caller to execute the block in its original context. This means the block will have access to its lexical scope and any other data available to the calling Ractor. Such blocks may safely re-enter the wrapper to invoke other methods on it, unless the wrapped method invoked the block from a nested Fiber (such as inside an Enumerator) or a spawned Thread, in which case re-entrant calls from the block may deadlock. If you need to invoke the block from a nested Fiber or a spawned Thread and the block does not need re-entrancy, prefer the :wrapped setting.
  • :wrapped - Blocks are executed directly in the wrapped object's context. This does not require any communication, but it means the block is removed from the caller's environment and does not have access to the caller's lexical scope or Ractor-accessible data.

All settings are optional. If not provided, they will fall back to a default. If you are configuring a particular method, by specifying the method_name argument, any unspecified setting will fall back to the method default settings (which you can set by omitting the method name.) If you are configuring the method default settings, by omitting the method_name argument, unspecified settings will fall back to :copy for the data movement settings, and :caller for the block_environment setting.

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    The name of the method being configured, or nil to set defaults for all methods not configured explicitly.

  • arguments (:move, :copy) (defaults to: nil) —

    How to communicate method arguments.

  • results (:move, :copy, :void) (defaults to: nil) —

    How to communicate method return values.

  • block_arguments (:move, :copy) (defaults to: nil) —

    How to communicate block arguments.

  • block_results (:move, :copy, :void) (defaults to: nil) —

    How to communicate block result values.

  • block_environment (:caller, :wrapped) (defaults to: nil) —

    How to execute blocks, and what scope blocks have access to.



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/ractor/wrapper.rb', line 345

def configure_method(method_name = nil,
                     arguments: nil,
                     results: nil,
                     block_arguments: nil,
                     block_results: nil,
                     block_environment: nil)
  method_name = method_name.to_sym unless method_name.nil?
  @method_settings[method_name] =
    MethodSettings.new(arguments: arguments,
                       results: results,
                       block_arguments: block_arguments,
                       block_results: block_results,
                       block_environment: block_environment)
  self
end