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) 


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

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) 


237
238
239
 
# File 'lib/ractor/wrapper.rb', line 237

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.

Parameters:

  • value (Integer) 


257
258
259
260
261
 
# File 'lib/ractor/wrapper.rb', line 257

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) 


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

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.
  • :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.



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/ractor/wrapper.rb', line 326

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