Module: Workhorse

Extended by:
Enqueuer
Defined in:
lib/workhorse.rb,
lib/workhorse/pool.rb,
lib/workhorse/daemon.rb,
lib/workhorse/db_job.rb,
lib/workhorse/poller.rb,
lib/workhorse/worker.rb,
lib/workhorse/enqueuer.rb,
lib/workhorse/performer.rb,
lib/workhorse/scoped_env.rb,
lib/workhorse/active_job_extension.rb,
lib/workhorse/daemon/shell_handler.rb,
lib/generators/workhorse/install_generator.rb

Overview

Main Gem module.

Defined Under Namespace

Modules: ActiveJobExtension, Enqueuer, Jobs Classes: Daemon, DbJob, InstallGenerator, Performer, Poller, Pool, ScopedEnv, Worker

Constant Summary collapse

AREL_GTE_7 =

Check if the available Arel version is greater or equal than 7.0.0

Gem::Version.new(Arel::VERSION) >= Gem::Version.new('7.0.0')

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enqueuer

enqueue, enqueue_active_job, enqueue_op

Class Method Details

.debug_log(message) ⇒ void

This method returns an undefined value.

Writes a debug message to the debug log file. Does nothing if #debug_log_path is nil. Silently ignores all exceptions to avoid interfering with normal operation.

Parameters:

  • message (String) —

    The message to log



125
126
127
128
129
130
131
132
133
 
# File 'lib/workhorse.rb', line 125

def self.debug_log(message)
  return unless debug_log_path

  File.open(debug_log_path, 'a') do |f|
    f.write("[#{Time.now.iso8601(3)}] [PID #{Process.pid}] #{message}\n")
    f.flush
  end
rescue Exception # rubocop:disable Lint/SuppressedException
end

.performer ⇒ Workhorse::Performer

Returns the performer currently performing the active job. This can only be called from within a job and the same thread.

Returns:

Raises:

  • (RuntimeError) —

    If called outside of a job context



23
24
25
26
 
# File 'lib/workhorse.rb', line 23

def self.performer
  Thread.current[:workhorse_current_performer] \
    || fail('No performer is associated with the current thread. This method must always be called inside of a job.')
end

.setup {|self| ... } ⇒ Object

Configuration method for setting up Workhorse options.

Examples:

Workhorse.setup do |config|
  config.max_global_lock_fails = 5
end

Yields:

  • (self) —

    Configuration block



142
143
144
 
# File 'lib/workhorse.rb', line 142

def self.setup
  yield self
end

Instance Method Details

#clean_stuck_jobs ⇒ Boolean

Controls automatic cleanup of stuck jobs on Poller startup. When enabled, pollers will clean jobs stuck in ‘locked’ or ‘running’ states.

Returns:

  • (Boolean) —

    Whether to clean stuck jobs on startup



88
 
# File 'lib/workhorse.rb', line 88

mattr_accessor :clean_stuck_jobs

#debug_log_path ⇒ String?

Path to a debug log file for diagnosing log rotation and signal handling issues. When set, Workhorse writes timestamped debug entries to this file at key points (worker startup, HUP signal handling, restart-logging command flow). Set to nil to disable (default).

Returns:

  • (String, nil) —

    Path to debug log file



116
 
# File 'lib/workhorse.rb', line 116

mattr_accessor :debug_log_path

#lock_shell_commands ⇒ Boolean

Controls whether Workhorse::Daemon::ShellHandler commands use lockfiles. Set to false if you’re handling locking yourself (e.g. in a wrapper script).

Returns:

  • (Boolean) —

    Whether to lock shell commands



59
 
# File 'lib/workhorse.rb', line 59

mattr_accessor :lock_shell_commands

#max_global_lock_fails ⇒ Integer

Maximum number of consecutive global lock failures before triggering error handling. A Worker will log an error and call the #on_exception callback if it can’t obtain the global lock for this many times in a row.

Returns:

  • (Integer) —

    The maximum number of allowed consecutive lock failures



33
 
# File 'lib/workhorse.rb', line 33

mattr_accessor :max_global_lock_fails

#max_worker_memory_mb ⇒ Integer

Maximum memory usage per Worker process in MB. When exceeded, the watch command will restart the worker. Set to 0 to disable.

Returns:

  • (Integer) —

    Memory limit in megabytes



107
 
# File 'lib/workhorse.rb', line 107

mattr_accessor :max_worker_memory_mb

#on_exception ⇒ Proc

Exception callback called when an exception occurs during job processing. Override this to integrate with your error reporting system.

Returns:

  • (Proc) —

    The exception callback



49
 
# File 'lib/workhorse.rb', line 49

mattr_accessor :on_exception

#perform_jobs_in_tx ⇒ Boolean

Controls whether jobs are performed within database transactions. Individual job classes can override this with skip_tx?.

Returns:

  • (Boolean) —

    Whether to perform jobs in transactions



81
 
# File 'lib/workhorse.rb', line 81

mattr_accessor :perform_jobs_in_tx

#silence_poller_exceptions ⇒ Boolean

Controls whether to silence exception callbacks for Poller exceptions. When true, #on_exception won’t be called for poller failures, but exceptions will still be logged.

Returns:

  • (Boolean) —

    Whether to silence poller exception callbacks



67
 
# File 'lib/workhorse.rb', line 67

mattr_accessor :silence_poller_exceptions

#silence_watcher ⇒ Boolean

Controls output verbosity for the watch command. When true, the watch command won’t produce output (warnings still shown).

Returns:

  • (Boolean) —

    Whether to silence watcher output



74
 
# File 'lib/workhorse.rb', line 74

mattr_accessor :silence_watcher

#tx_callback ⇒ Proc

Transaction callback used for database operations. Defaults to ActiveRecord::Base.transaction.

Returns:

  • (Proc) —

    The transaction callback



40
 
# File 'lib/workhorse.rb', line 40

mattr_accessor :tx_callback