Class: Farce::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/farce/config.rb,
lib/farce/integrations/active_support/duplicable.rb

Overview

Configuration for Farce. Will be frozen by Farce once it is accessed, to prevent accidental changes and make it shareable across Ractors.

require "farce"

Farce.config do |c|
  c.fiber_scheduler = :select
end

Instance Attribute Summary collapse

ActiveSupport Integration collapse

Instance Method Summary collapse

Constructor Details

#initialize {|config| ... } ⇒ Config

Returns a new instance of Config.

Yields:

  • (config) —

    block to modify the configuration

Yield Parameters:

  • config (Config) —

    the configuration object to configure



75
76
77
78
79
80
81
82
 
# File 'lib/farce/config.rb', line 75

def initialize
  yield self if block_given?
  self.autoload_integrations = ENV.fetch("FARCE_AUTOLOAD_INTEGRATIONS", true) if autoload_integrations.nil?
  self.fiber_scheduler       = ENV["FARCE_FIBER_SCHEDULER"] unless instance_variable_defined?(:@fiber_scheduler)
  self.main_thread_pool_size       ||= ENV.fetch("FARCE_MAIN_THREAD_POOL_SIZE", 4)
  self.additional_thread_pool_size ||= ENV.fetch("FARCE_ADDITIONAL_THREAD_POOL_SIZE", 2)
  initialize_parallel_pool
end

Instance Attribute Details

#additional_thread_pool_size ⇒ BasicObject

Maximum workers in a pool created on another Ractor. Workers start lazily. Can also be set via FARCE_ADDITIONAL_THREAD_POOL_SIZE. Defaults to 2.



37
38
39
 
# File 'lib/farce/config.rb', line 37

def additional_thread_pool_size
  @additional_thread_pool_size
end

#autoload_integrations ⇒ Boolean

Automatically load integrations when their dependencies are loaded. Defaults to true. Can also be set via FARCE_AUTOLOAD_INTEGRATIONS (true/false or 1/0). Set before requiring Farce to disable startup integration loading and require hooks.

Returns:

  • (Boolean) 


29
30
31
 
# File 'lib/farce/config.rb', line 29

def autoload_integrations
  @autoload_integrations
end

#main_thread_pool_size ⇒ BasicObject

Maximum workers in a pool created on the main Ractor. Workers start lazily. Can also be set via FARCE_MAIN_THREAD_POOL_SIZE. Defaults to 4.



33
34
35
 
# File 'lib/farce/config.rb', line 33

def main_thread_pool_size
  @main_thread_pool_size
end

#parallel_pool_capacity ⇒ Integer?

Pending-task capacity of Farce.in_parallel's CRuby pool. Defaults to 1024. Set to nil for an unbounded queue.

Returns:

  • (Integer, nil) 


67
68
69
 
# File 'lib/farce/config.rb', line 67

def parallel_pool_capacity
  @parallel_pool_capacity
end

#parallel_pool_grow_after ⇒ Float

Queue wait in seconds before Farce.in_parallel's CRuby pool adds a worker. Defaults to 0.005.

Returns:

  • (Float) 


57
58
59
 
# File 'lib/farce/config.rb', line 57

def parallel_pool_grow_after
  @parallel_pool_grow_after
end

#parallel_pool_max_inflight ⇒ Integer?

Soft task limit for each worker in Farce.in_parallel's CRuby pool. Defaults to 64. Set to nil to disable the limit.

Returns:

  • (Integer, nil) 


52
53
54
 
# File 'lib/farce/config.rb', line 52

def parallel_pool_max_inflight
  @parallel_pool_max_inflight
end

#parallel_pool_max_size ⇒ Integer?

Maximum workers used by Farce.in_parallel on CRuby. Defaults to nil, which uses System.cpu_count when the pool is created.

Returns:

  • (Integer, nil) 


47
48
49
 
# File 'lib/farce/config.rb', line 47

def parallel_pool_max_size
  @parallel_pool_max_size
end

#parallel_pool_min_size ⇒ Integer

Minimum workers retained by Farce.in_parallel on CRuby. Defaults to 0. Configure before the first scheduler is created. Ignored on JRuby and TruffleRuby.

Returns:

  • (Integer) 


42
43
44
 
# File 'lib/farce/config.rb', line 42

def parallel_pool_min_size
  @parallel_pool_min_size
end

#parallel_pool_shrink_after ⇒ Float?

Idle time in seconds before an extra worker in Farce.in_parallel's CRuby pool retires. Defaults to 30. Set to nil to disable idle retirement.

Returns:

  • (Float, nil) 


62
63
64
 
# File 'lib/farce/config.rb', line 62

def parallel_pool_shrink_after
  @parallel_pool_shrink_after
end

Instance Method Details

#duplicable? ⇒ Boolean

Note:

This methods is only available if ActiveSupport has been loaded.

Returns true.

Returns:

  • (Boolean) —

    true



12
 
# File 'lib/farce/integrations/active_support/duplicable.rb', line 12

def duplicable? = true

#fiber_scheduler(&constructor) ⇒ Symbol, ...

Default fiber scheduler for Pool and Scheduler. Explicit constructor blocks override it.

Uses FARCE_FIBER_SCHEDULER unless assigned explicitly, including an explicit nil.

Built-in choices are :auto, :native, :jvm, :select, :kqueue, :epoll, :io_uring, and :nio. Strings are also accepted. nil or an empty string are treated like :auto.

Other names resolve constants, such as carbon_fiber to CarbonFiber. If the constant is not defined, it attempts to require the corresponding file. Modules must define their own Scheduler class.

Classes are constructed without arguments in each worker. Procs must be shareable. Custom schedulers must support the executor used by the Pool or Scheduler.

Returns:

  • (Symbol, Class, Proc) —

    normalized choice



140
141
142
143
 
# File 'lib/farce/config.rb', line 140

def fiber_scheduler(&constructor)
  self.fiber_scheduler = constructor if constructor
  @fiber_scheduler
end

#fiber_scheduler=(value) ⇒ BasicObject

Sets the default scheduler. Use config.fiber_scheduler { MyScheduler.new } or assign a proc to configure construction. Invalid assignments preserve the old value.

Raises:

  • (FrozenError) 


147
148
149
150
 
# File 'lib/farce/config.rb', line 147

def fiber_scheduler=(value)
  raise FrozenError, "can't modify frozen Config" if frozen?
  @fiber_scheduler = normalize_fiber_scheduler(value)
end

#fiber_scheduler_implementation ⇒ Symbol

Implementation used by Farce's built-in scheduler.

Returns:

  • (Symbol) —

    one of :native, :select, or :jvm



154
155
156
157
158
159
160
161
 
# File 'lib/farce/config.rb', line 154

def fiber_scheduler_implementation
  case @fiber_scheduler
  when :native, :jvm, :select     then @fiber_scheduler
  when :kqueue, :epoll, :io_uring then :native
  when :nio                       then :jvm
  else detected_fiber_scheduler_implementation
  end
end

#freeze ⇒ BasicObject

Called internally once the configuration is applied.



234
235
236
237
238
239
 
# File 'lib/farce/config.rb', line 234

def freeze
  return self if frozen?
  super # need to call this first to avoid infinite recursion in the next line
  ::Ractor.make_shareable(self) if defined?(::Ractor.make_shareable)
  self
end

#io_backend ⇒ Symbol

IO backend used by the built-in scheduler. Explicit backend: options override it. Availability is checked when a scheduler is created.

Returns:

  • (Symbol) —

    the configured backend or :auto



166
167
168
169
170
171
 
# File 'lib/farce/config.rb', line 166

def io_backend
  case @fiber_scheduler
  when :kqueue, :epoll, :io_uring, :nio, :select then @fiber_scheduler
  else :auto
  end
end