workhorse 1.3.0.rc3 → 1.3.0.rc4

data/lib/workhorse/worker.rb

@@ -1,25 +1,63 @@
 module Workhorse
+  # Main worker class that manages job polling and execution.
+  # Workers poll the database for jobs, manage thread pools for parallel execution,
+  # and handle graceful shutdown and memory monitoring.
+  #
+  # @example Basic worker setup
+  #   worker = Workhorse::Worker.new(
+  #     queues: [:default, :urgent],
+  #     pool_size: 4,
+  #     polling_interval: 30
+  #   )
+  #   worker.start
+  #   worker.wait
+  #
+  # @example Auto-terminating worker
+  #   Workhorse::Worker.start_and_wait(
+  #     queues: [:email, :reports],
+  #     auto_terminate: true
+  #   )
   class Worker
     LOG_LEVELS = %i[fatal error warn info debug].freeze
     SHUTDOWN_SIGNALS = %w[TERM INT].freeze
     LOG_REOPEN_SIGNAL = 'HUP'.freeze
 
+    # @return [Array<Symbol>] The queues this worker processes
     attr_reader :queues
+
+    # @return [Symbol] Current worker state (:initialized, :running, :shutdown)
     attr_reader :state
+
+    # @return [Integer] Number of threads in the worker pool
     attr_reader :pool_size
+
+    # @return [Integer] Polling interval in seconds
     attr_reader :polling_interval
+
+    # @return [Mutex] Synchronization mutex for thread safety
     attr_reader :mutex
+
+    # @return [Logger, nil] Optional logger instance
     attr_reader :logger
+
+    # @return [Workhorse::Poller] The poller instance
     attr_reader :poller
 
     # Instantiates and starts a new worker with the given arguments and then
     # waits for its completion (i.e. an interrupt).
+    #
+    # @param args [Hash] Arguments passed to {#initialize}
+    # @return [void]
     def self.start_and_wait(**args)
       worker = new(**args)
       worker.start
       worker.wait
     end
 
+    # Returns the path to the shutdown file for a given process ID.
+    #
+    # @param pid [Integer] Process ID
+    # @return [String, nil] Path to shutdown file or nil if not in Rails
     # @private
     def self.shutdown_file_for(pid)
       return nil unless defined?(Rails)
@@ -69,6 +107,12 @@ module Workhorse
       end
     end
 
+    # Logs a message with worker ID prefix.
+    #
+    # @param text [String] The message to log
+    # @param level [Symbol] The log level (must be in LOG_LEVELS)
+    # @return [void]
+    # @raise [RuntimeError] If log level is invalid
     def log(text, level = :info)
       text = "[Job worker #{id}] #{text}"
       puts text unless @quiet
@@ -77,20 +121,33 @@ module Workhorse
       logger.send(level, text.strip)
     end
 
+    # Returns the unique identifier for this worker.
+    # Format: hostname.pid.random_hex
+    #
+    # @return [String] Unique worker identifier
     def id
       @id ||= "#{hostname}.#{pid}.#{SecureRandom.hex(3)}"
     end
 
+    # Returns the process ID of this worker.
+    #
+    # @return [Integer] Process ID
     def pid
       @pid ||= Process.pid
     end
 
+    # Returns the hostname of the machine running this worker.
+    #
+    # @return [String] Hostname
     def hostname
       @hostname ||= Socket.gethostname
     end
 
-    # Starts the worker. This call is not blocking - call {wait} for this
+    # Starts the worker. This call is not blocking - call {#wait} for this
     # purpose.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If worker is not in initialized state
     def start
       mutex.synchronize do
         assert_state! :initialized
@@ -104,13 +161,20 @@ module Workhorse
       end
     end
 
+    # Asserts that the worker is in the expected state.
+    #
+    # @param state [Symbol] Expected state
+    # @return [void]
+    # @raise [RuntimeError] If worker is not in expected state
     def assert_state!(state)
       fail "Expected worker to be in state #{state} but current state is #{self.state}." unless self.state == state
     end
 
-    # Shuts down worker and DB poller. Jobs currently beeing processed are
+    # Shuts down worker and DB poller. Jobs currently being processed are
     # properly finished before this method returns. Subsequent calls to this
     # method are ignored.
+    #
+    # @return [void]
     def shutdown
       # This is safe to be checked outside of the mutex as 'shutdown' is the
       # final state this worker can be in.
@@ -131,19 +195,28 @@ module Workhorse
       end
     end
 
-    # Waits until the worker is shut down. This only happens if shutdown gets
+    # Waits until the worker is shut down. This only happens if {#shutdown} gets
     # called - either by another thread or by enabling `auto_terminate` and
     # receiving a respective signal. Use this method to let worker run
-    # undefinitely.
+    # indefinitely.
+    #
+    # @return [void]
     def wait
       @poller.wait
       @pool.wait
     end
 
+    # Returns the number of idle threads in the pool.
+    #
+    # @return [Integer] Number of idle threads
     def idle
       @pool.idle
     end
 
+    # Schedules a job for execution in the thread pool.
+    #
+    # @param db_job_id [Integer] The ID of the {Workhorse::DbJob} to perform
+    # @return [void]
     def perform(db_job_id)
       begin # rubocop:disable Style/RedundantBegin
         mutex.synchronize do
@@ -166,6 +239,10 @@ module Workhorse
 
     private
 
+    # Checks current memory usage and initiates shutdown if limit exceeded.
+    #
+    # @return [Boolean] True if memory is within limits, false if exceeded
+    # @private
     def check_memory
       mem = current_memory_consumption
 
@@ -191,12 +268,20 @@ module Workhorse
       return false
     end
 
+    # Returns current memory consumption in MB.
+    #
+    # @return [Integer, nil] Memory usage in MB or nil if unable to determine
+    # @private
     def current_memory_consumption
       mem = `ps -p #{pid} -o rss=`&.strip
       return nil if mem.blank?
       return mem.to_i / 1024
     end
 
+    # Sets up signal handler for log file reopening (HUP signal).
+    #
+    # @return [void]
+    # @private
     def trap_log_reopen
       Signal.trap(LOG_REOPEN_SIGNAL) do
         Thread.new do
@@ -209,6 +294,10 @@ module Workhorse
       end
     end
 
+    # Sets up signal handlers for graceful termination (TERM/INT signals).
+    #
+    # @return [void]
+    # @private
     def trap_termination
       SHUTDOWN_SIGNALS.each do |signal|
         Signal.trap(signal) do

data/lib/workhorse.rb

@@ -8,58 +8,83 @@ require 'workhorse/enqueuer'
 require 'workhorse/scoped_env'
 require 'workhorse/active_job_extension'
 
+# Main Gem module.
 module Workhorse
   # Check if the available Arel version is greater or equal than 7.0.0
   AREL_GTE_7 = Gem::Version.new(Arel::VERSION) >= Gem::Version.new('7.0.0')
 
   extend Workhorse::Enqueuer
 
-  # Returns the performer currently performing the active job. This can only be
-  # called from within a job and the same thread.
+  # Returns the performer currently performing the active job.
+  # This can only be called from within a job and the same thread.
+  #
+  # @return [Workhorse::Performer] The current performer instance
+  # @raise [RuntimeError] If called outside of a job context
   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
 
-  # A worker will log an error and, if defined, call the on_exception callback,
-  # if it couldn't obtain the global lock for the specified number of times in a
-  # row.
+  # Maximum number of consecutive global lock failures before triggering error handling.
+  # A {Workhorse::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.
+  #
+  # @return [Integer] The maximum number of allowed consecutive lock failures
   mattr_accessor :max_global_lock_fails
   self.max_global_lock_fails = 10
 
+  # Transaction callback used for database operations.
+  # Defaults to ActiveRecord::Base.transaction.
+  #
+  # @return [Proc] The transaction callback
   mattr_accessor :tx_callback
   self.tx_callback = proc do |*args, &block|
     ActiveRecord::Base.transaction(*args, &block)
   end
 
+  # Exception callback called when an exception occurs during job processing.
+  # Override this to integrate with your error reporting system.
+  #
+  # @return [Proc] The exception callback
   mattr_accessor :on_exception
   self.on_exception = proc do |exception|
     # Do something with this exception, i.e.
     # ExceptionNotifier.notify_exception(exception)
   end
 
-  # If set to `false`, shell handler (CLI) won't lock commands using a lockfile.
-  # You should generally only disable this if you are performing the locking
-  # yourself (e.g. in a wrapper script).
+  # Controls whether {Workhorse::Daemon::ShellHandler} commands use lockfiles.
+  # Set to false if you're handling locking yourself (e.g. in a wrapper script).
+  #
+  # @return [Boolean] Whether to lock shell commands
   mattr_accessor :lock_shell_commands
   self.lock_shell_commands = true
 
-  # If set to `true`, the defined `on_exception` will not be called when the
-  # poller encounters an exception and the worker has to be shut down. The
-  # exception will still be logged.
+  # Controls whether to silence exception callbacks for {Workhorse::Poller} exceptions.
+  # When true, {.on_exception} won't be called for poller failures, but exceptions
+  # will still be logged.
+  #
+  # @return [Boolean] Whether to silence poller exception callbacks
   mattr_accessor :silence_poller_exceptions
   self.silence_poller_exceptions = false
 
-  # If set to `true`, the `watch` command won't produce any output. This does
-  # not include warnings such as the "development mode" warning.
+  # Controls output verbosity for the watch command.
+  # When true, the watch command won't produce output (warnings still shown).
+  #
+  # @return [Boolean] Whether to silence watcher output
   mattr_accessor :silence_watcher
   self.silence_watcher = false
 
+  # Controls whether jobs are performed within database transactions.
+  # Individual job classes can override this with skip_tx?.
+  #
+  # @return [Boolean] Whether to perform jobs in transactions
   mattr_accessor :perform_jobs_in_tx
   self.perform_jobs_in_tx = true
 
-  # If enabled, each poller will attempt to clean jobs that are stuck in state
-  # 'locked' or 'running' when it is starting up.
+  # Controls automatic cleanup of stuck jobs on {Workhorse::Poller} startup.
+  # When enabled, pollers will clean jobs stuck in 'locked' or 'running' states.
+  #
+  # @return [Boolean] Whether to clean stuck jobs on startup
   mattr_accessor :clean_stuck_jobs
   self.clean_stuck_jobs = false
 
@@ -75,12 +100,20 @@ module Workhorse
   mattr_accessor :stale_detection_run_time_threshold
   self.stale_detection_run_time_threshold = 12 * 60
 
-  # Maximum memory for a worker in MB. If this memory limit (RSS / resident
-  # size) is reached for a worker process, the 'watch' command will restart said
-  # worker. Set this to 0 disable this feature.
+  # Maximum memory usage per {Workhorse::Worker} process in MB.
+  # When exceeded, the watch command will restart the worker. Set to 0 to disable.
+  #
+  # @return [Integer] Memory limit in megabytes
   mattr_accessor :max_worker_memory_mb
   self.max_worker_memory_mb = 0
 
+  # Configuration method for setting up Workhorse options.
+  #
+  # @yield [self] Configuration block
+  # @example
+  #   Workhorse.setup do |config|
+  #     config.max_global_lock_fails = 5
+  #   end
   def self.setup
     yield self
   end

data/workhorse.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-# stub: workhorse 1.3.0.rc3 ruby lib
+# stub: workhorse 1.3.0.rc4 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "workhorse".freeze
-  s.version = "1.3.0.rc3"
+  s.version = "1.3.0.rc4"
 
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Sitrox".freeze]
-  s.date = "2025-06-10"
+  s.date = "2025-08-27"
   s.files = [".github/workflows/ruby.yml".freeze, ".gitignore".freeze, ".releaser_config".freeze, ".rubocop.yml".freeze, "CHANGELOG.md".freeze, "FAQ.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "RUBY_VERSION".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/rubocop".freeze, "lib/active_job/queue_adapters/workhorse_adapter.rb".freeze, "lib/generators/workhorse/install_generator.rb".freeze, "lib/generators/workhorse/templates/bin/workhorse.rb".freeze, "lib/generators/workhorse/templates/config/initializers/workhorse.rb".freeze, "lib/generators/workhorse/templates/create_table_jobs.rb".freeze, "lib/workhorse.rb".freeze, "lib/workhorse/active_job_extension.rb".freeze, "lib/workhorse/daemon.rb".freeze, "lib/workhorse/daemon/shell_handler.rb".freeze, "lib/workhorse/db_job.rb".freeze, "lib/workhorse/enqueuer.rb".freeze, "lib/workhorse/jobs/cleanup_succeeded_jobs.rb".freeze, "lib/workhorse/jobs/detect_stale_jobs_job.rb".freeze, "lib/workhorse/jobs/run_active_job.rb".freeze, "lib/workhorse/jobs/run_rails_op.rb".freeze, "lib/workhorse/performer.rb".freeze, "lib/workhorse/poller.rb".freeze, "lib/workhorse/pool.rb".freeze, "lib/workhorse/scoped_env.rb".freeze, "lib/workhorse/worker.rb".freeze, "test/active_job/queue_adapters/workhorse_adapter_test.rb".freeze, "test/lib/db_schema.rb".freeze, "test/lib/jobs.rb".freeze, "test/lib/test_helper.rb".freeze, "test/workhorse/daemon_test.rb".freeze, "test/workhorse/db_job_test.rb".freeze, "test/workhorse/enqueuer_test.rb".freeze, "test/workhorse/performer_test.rb".freeze, "test/workhorse/poller_test.rb".freeze, "test/workhorse/pool_test.rb".freeze, "test/workhorse/worker_test.rb".freeze, "workhorse.gemspec".freeze]
   s.rubygems_version = "3.4.6".freeze
   s.summary = "Multi-threaded job backend with database queuing for ruby.".freeze

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: workhorse
 version: !ruby/object:Gem::Version
-  version: 1.3.0.rc3
+  version: 1.3.0.rc4
 platform: ruby
 authors:
 - Sitrox
 bindir: bin
 cert_chain: []
-date: 2025-06-10 00:00:00.000000000 Z
+date: 2025-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport