Class: Teek::BackgroundWork

Inherits:
Object
  • Object
show all
Defined in:
lib/teek/ractor_support.rb

Overview

Unified background work API. Delegates to a mode-specific implementation selected via the mode: parameter.

Modes:

  • :thread — traditional threading; best for I/O-bound work where the GVL is released during blocking calls. Always available.
  • :ractor — true parallel execution via Ractor (Ruby 4.x+ only); best for CPU-bound work.

Examples:

Basic usage

task = Teek::BackgroundWork.new(app, data, mode: :thread) do |t, d|
  d.each { |item| t.yield(process(item)) }
end
task.on_progress { |r| update_ui(r) }
    .on_done { puts "Finished" }

Pause / resume / stop

task.pause
task.resume
task.stop

Configuration

Teek::BackgroundWork.poll_ms = 16
Teek::BackgroundWork.drop_intermediate = true
Teek::BackgroundWork.abort_on_error = false

Constant Summary collapse

RACTOR_SUPPORTED =

Returns whether Ractor mode is available (Ruby 4.x+).

Returns:

  • (Boolean) —

    whether Ractor mode is available (Ruby 4.x+)

Ractor.respond_to?(:shareable_proc)

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(app, data, mode: :thread, worker: nil) {|task, data| ... } ⇒ BackgroundWork

Returns a new instance of BackgroundWork.

Parameters:

  • app (Teek::App) —

    the application instance

  • data (Object) —

    data passed to the worker block

  • mode (Symbol) (defaults to: :thread) —

    :thread or :ractor

  • worker (Class, nil) (defaults to: nil) —

    optional worker class (must respond to #call(task, data))

Yields:

  • (task, data) —

    block executed in the background

Yield Parameters:

Raises:

  • (ArgumentError) —

    if mode is unknown



100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/teek/ractor_support.rb', line 100

def initialize(app, data, mode: :thread, worker: nil, &block)
  impl_class = self.class.background_mode_class(mode)
  unless impl_class
    available = self.class.background_modes.keys.join(', ')
    raise ArgumentError, "Unknown mode: #{mode}. Available: #{available}"
  end

  @impl = impl_class.new(app, data, worker: worker, &block)
  @mode = mode
  @name = nil
end

Class Attribute Details

.abort_on_error ⇒ Boolean

Returns when true, raise on ractor errors instead of warning (default false).

Returns:

  • (Boolean) —

    when true, raise on ractor errors instead of warning (default false)



54
55
56
 
# File 'lib/teek/ractor_support.rb', line 54

def abort_on_error
  @abort_on_error
end

.drop_intermediate ⇒ Boolean

Returns when true, only the latest progress value per poll cycle is delivered (default true).

Returns:

  • (Boolean) —

    when true, only the latest progress value per poll cycle is delivered (default true)



51
52
53
 
# File 'lib/teek/ractor_support.rb', line 51

def drop_intermediate
  @drop_intermediate
end

.poll_ms ⇒ Integer

Returns UI poll interval in milliseconds (default 16).

Returns:

  • (Integer) —

    UI poll interval in milliseconds (default 16)



48
49
50
 
# File 'lib/teek/ractor_support.rb', line 48

def poll_ms
  @poll_ms
end

Instance Attribute Details

#name ⇒ String?

Returns optional name for this task.

Returns:

  • (String, nil) —

    optional name for this task



90
91
92
 
# File 'lib/teek/ractor_support.rb', line 90

def name
  @name
end

Class Method Details

.background_mode_class(name) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



77
78
79
 
# File 'lib/teek/ractor_support.rb', line 77

def self.background_mode_class(name)
  @background_modes[name.to_sym]
end

.background_modes ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



72
73
74
 
# File 'lib/teek/ractor_support.rb', line 72

def self.background_modes
  @background_modes
end

.register_background_mode(name, klass) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



67
68
69
 
# File 'lib/teek/ractor_support.rb', line 67

def self.register_background_mode(name, klass)
  @background_modes[name.to_sym] = klass
end

Instance Method Details

#close ⇒ self

Force-close the worker and associated resources.

Returns:

  • (self) 


179
180
181
182
 
# File 'lib/teek/ractor_support.rb', line 179

def close
  @impl.close if @impl.respond_to?(:close)
  self
end

#done? ⇒ Boolean

Returns:

  • (Boolean) 


118
119
120
 
# File 'lib/teek/ractor_support.rb', line 118

def done?
  @impl.done?
end

#mode ⇒ Symbol

Returns the active mode (+:thread+ or :ractor).

Returns:

  • (Symbol) —

    the active mode (+:thread+ or :ractor)



113
114
115
 
# File 'lib/teek/ractor_support.rb', line 113

def mode
  @mode
end

#on_done { ... } ⇒ self

Yields:

  • called on the main thread when the worker completes

Returns:

  • (self) 


136
137
138
139
 
# File 'lib/teek/ractor_support.rb', line 136

def on_done(&block)
  @impl.on_done(&block)
  self
end

#on_message {|msg| ... } ⇒ self

Yields:

  • (msg) —

    called on the main thread with custom worker messages

Returns:

  • (self) 


143
144
145
146
 
# File 'lib/teek/ractor_support.rb', line 143

def on_message(&block)
  @impl.on_message(&block)
  self
end

#on_progress {|value| ... } ⇒ self

Yields:

  • (value) —

    called on the main thread with each result

Returns:

  • (self) 


129
130
131
132
 
# File 'lib/teek/ractor_support.rb', line 129

def on_progress(&block)
  @impl.on_progress(&block)
  self
end

#pause ⇒ self

Pause the worker.

Returns:

  • (self) 


158
159
160
161
 
# File 'lib/teek/ractor_support.rb', line 158

def pause
  @impl.pause
  self
end

#paused? ⇒ Boolean

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/teek/ractor_support.rb', line 123

def paused?
  @impl.paused?
end

#resume ⇒ self

Resume a paused worker.

Returns:

  • (self) 


165
166
167
168
 
# File 'lib/teek/ractor_support.rb', line 165

def resume
  @impl.resume
  self
end

#send_message(msg) ⇒ self

Send a message to the worker.

Parameters:

  • msg (Object) —

    any value (must be Ractor-shareable in :ractor mode)

Returns:

  • (self) 


151
152
153
154
 
# File 'lib/teek/ractor_support.rb', line 151

def send_message(msg)
  @impl.send_message(msg)
  self
end

#start ⇒ self

Explicitly start the worker. Called automatically by #on_progress and #on_done.

Returns:

  • (self) 


187
188
189
190
 
# File 'lib/teek/ractor_support.rb', line 187

def start
  @impl.start
  self
end

#stop ⇒ self

Request the worker to stop.

Returns:

  • (self) 


172
173
174
175
 
# File 'lib/teek/ractor_support.rb', line 172

def stop
  @impl.stop
  self
end