workhorse 1.3.0.rc2 → 1.3.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2eebb8cbdfe18e11988f8ba9b0ef440c8e4cf0ad29efb6e8d6e98fd036fb2fe
-  data.tar.gz: 97ee81bce90ab26428b2e17b1a4049762230131840c270762f7d85b3de0b7f7c
+  metadata.gz: dca93061dd92dfbd43f1a44dcb2958181257d16079f408114af13a80197e48c6
+  data.tar.gz: 8a4c202c76b7380912288331bc8ef24a4dc8839c4455a4c455b48dddeb631588
 SHA512:
-  metadata.gz: ddca8c7bcee25b1836f9d111308450679e9773c643c8ff5ad86758e8b366f11f12d43bfbbf101ba1d52ac67ea83efa5c1c27435efbab55f8b33acdc0aa200740
-  data.tar.gz: f58bdd1efd155864dd32a99a9b514f980c4d81a30a26adaee8941b3b5be473f387d22ba4dce4e4969fd2e043ca06950ef9d75f048a51e7ce431f0a19095d63ea
+  metadata.gz: c8b5829f8d84bd7ed135bfcc467f5b9afd313acd9f36d94b90bf77e106b0cf6f627189bf89e6f0ba31aecf791875fd5217091b3b5034d109473623da5d1b4cf3
+  data.tar.gz: b50b7514b14ce6170b192835a9d61b03d84577de0466ef471bd60f5561a873930151d61aa9c1c3638dce889c0bdf6432a6ae7289f9e061ff4e8220313dc3937a

data/.github/workflows/ruby.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.5.1
+          ruby-version: 3.0.1
           bundler-cache: true
       - name: Run rubocop
         run: bundle exec rubocop

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Workhorse Changelog
 
+## 1.3.0.rc4 - 2025-08-27
+
+* Fix race-condition in polling mechanism which could result in workers 
+  trying to run a job that is not yet locked.
+
+  Sitrox reference: #128333.
+
+## 1.3.0.rc3 - 2025-06-10
+
+* Require Rails 7.0.0 or later
+
 ## 1.3.0.rc2 - 2025-06-10
 
 * Update development dependencies
@@ -46,7 +57,7 @@
 * Comply with RuboCop
 
 * Skip `at_exit` handlers when exiting in ShellHandler. This ensures
-  compatibility with the `debug` gem, which whould otherwise hang when using the
+  compatibility with the `debug` gem, which would otherwise hang when using the
   Workhorse shell handler.
 
   Sitrox reference: #128333.
@@ -296,7 +307,7 @@ battle before it can be considered stable.
 * Simplify locking during polling. Other than locking individual jobs, pollers
   now acquire a global lock. While this can lead to many pollers waiting for
   each others locks, performing a poll is usually done very quickly and the
-  performance drawback is to be considered neglegible. This change should work
+  performance drawback is to be considered negligible. This change should work
   around some deadlock issues as well as an issue where a job was obtained by
   more than one poller.
 

data/FAQ.md

@@ -2,13 +2,13 @@
 
 ## Why should I use workhorse over *X*?
 
-There exist a variety of job backends for ruby,
+There are a variety of job backends for Ruby,
 [delayed_job](https://github.com/collectiveidea/delayed_job) probably being the
 closest one to workhorse.
 
 Some key advantages we feel workhorse has over other Gems:
 
-- Workhorse is less than 500 lines of code at its core. The code is supposed to
+- Workhorse is less than 500 lines of code at its core. The code is designed to
   be easily readable, understandable, and modifiable.
 
 - Workhorse allows you to run multiple jobs simultaneously *in the same
@@ -20,7 +20,7 @@ figure out which one best suits your needs.
 
 ## My code is not thread safe. How can I use workhorse safely?
 
-Job code that is not thread safe can not be executed safely in multiple threads
+Job code that is not thread safe cannot be executed safely in multiple threads
 of the same process. In these cases, set the `pool_size` to `1` and, if you
 still want to execute multiple jobs simultaneously, the daemon `count` to a
 number greater than `1`:
@@ -33,10 +33,10 @@ end
 
 ## I'm using jRuby. How can I use the daemon handler?
 
-As java processes in general can not be forked safely, the daemon handler
+As Java processes in general cannot be forked safely, the daemon handler
 provided with this Gem does not support jRuby platforms.
 
-If your jRuby application consists of one single application process, it is
+If your jRuby application consists of a single application process, it is
 recommended to just start the job backend in the same process:
 
 ```ruby
@@ -48,7 +48,7 @@ This code is non-blocking, which means that it will run as long as the process
 is up. Make sure to trap `INT` and `TERM` and call `worker.shutdown` when the
 process stops.
 
-If you have multiple application processes though, you may want to start the
+If you have multiple application processes, however, you may want to start the
 worker in a separate process. For this purpose, adapt the startup script
 `bin/workhorse.rb` so that it is blocking:
 
@@ -56,9 +56,9 @@ worker in a separate process. For this purpose, adapt the startup script
 Workhorse::Worker.start_and_wait(pool_size: 5)
 ```
 
-This can then be started and "daemonized" using standard linux tools.
+This can then be started and "daemonized" using standard Linux tools.
 
-## I'm getting random autoloading exeptions
+## I'm getting random autoloading exceptions
 
 Make sure to always start the worker in *production mode*, i.e.:
 
@@ -69,7 +69,7 @@ RAILS_ENV=production bin/workhorse.rb start
 ## I'm getting "No live threads left. Deadlock?" exceptions
 
 Make sure the Worker is logging somewhere and check the logs. Typically there is
-an underlying error that leads to the exception, e.g. missing migration in
+an underlying error that leads to the exception, e.g., a missing migration in
 production mode.
 
 ## Why does workhorse not support timeouts?
@@ -77,5 +77,5 @@ production mode.
 Generic timeout implementations are [a dangerous
 thing](http://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/)
 in Ruby. This is why we decided against providing this feature in Workhorse and
-recommend to implement the timeouts inside of your jobs - i.e. via network
+recommend to implement timeouts inside of your jobs - i.e. via network
 timeouts.

data/Gemfile

@@ -3,12 +3,12 @@ source 'https://rubygems.org'
 # Specify gem dependencies in the .gemspec file
 gemspec
 
+gem 'activejob', '~> 7.1.3'
+gem 'activerecord', '~> 7.1.3'
+gem 'benchmark-ips'
 gem 'bundler'
-gem 'rake'
-gem 'rubocop', '~> 1.28.0' # Latest version supported with Ruby 2.5
 gem 'minitest'
 gem 'mysql2'
-gem 'benchmark-ips'
-gem 'activejob', '~> 7.1.3'
-gem 'activerecord', '~> 7.1.3'
 gem 'pry'
+gem 'rake'
+gem 'rubocop', '~> 1.28.0' # Latest version supported with Ruby 2.5

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 - 2024 Sitrox
+Copyright (c) 2017 - 2025 Sitrox
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,7 +3,7 @@
 
 # Workhorse
 
-Multi-threaded job backend with database queuing for ruby. Battle-tested and ready for production-use.
+Multi-threaded job backend with database queuing for Ruby. Battle-tested and ready for production-use.
 
 ## Introduction
 
@@ -12,7 +12,7 @@ How it works:
 * Jobs are instances of classes that support the `perform` method.
 * Jobs are persisted in the database using ActiveRecord.
 * Each job has a priority, the default being 0. Jobs with higher priorities
-  (lower is higher, 0 the highest) get processed first.
+  (lower numbers have higher priority, with 0 being the highest) get processed first.
 * Each job can be set to execute after a certain date / time.
 * You can start one or more worker processes.
 * Each worker is configurable as to which queue(s) it processes. Jobs in the
@@ -34,12 +34,12 @@ What it does not do:
 ### Requirements
 
 * Ruby `>= 3.0` (may work with earlier versions but is untested)
-* Rails `>= 3.2`
+* Rails `>= 7.0`
 * A database and table handler that properly supports row-level locking (such as
   MySQL with InnoDB, PostgreSQL, or Oracle).
 * If you are planning on using the daemons handler:
   * An operating system and file system that supports file locking.
-  * MRI ruby (aka "CRuby") as jRuby does not support `fork`. See the
+  * MRI Ruby (aka "CRuby") as jRuby does not support `fork`. See the
     [FAQ](FAQ.md#im-using-jruby-how-can-i-use-the-daemon-handler) for possible workarounds.
 
 ### Installing under Rails
@@ -81,8 +81,8 @@ GRANT execute ON DBMS_LOCK TO <schema-name>;
 ### Basic jobs
 
 Workhorse can handle any jobs that support the `perform` method and are
-serializable. To queue a basic job, use the static method `Workhorse.enqueue`.
-You can optionally pass a queue name, a priority and a description (as a string).
+serializable. To queue a basic job, use `Workhorse.enqueue`.
+You can optionally pass a queue name, a priority, and a description.
 
 ```ruby
 class MyJob
@@ -108,15 +108,15 @@ method `Workhorse.enqueue_op`:
 Workhorse.enqueue_op Operations::Jobs::CleanUpDatabase, { queue: :maintenance, priority: 2 }, quiet: true
 ```
 
-The first argument of the method is the Operation you want to run. Params passed in
-using the second argument will be used by Workhorse and params passed using the
+The first argument of the method is the Operation you want to run. Parameters passed in
+using the second argument will be used by Workhorse and parameters passed using the
 third argument will be used for operation instantiation at job execution, i.e.:
 
 ```ruby
 Workhorse.enqueue_op <Operation Class Name>, { <Workhorse Options> }, { <RailsOps Options> }
 ```
 
-If you do not want to pass any params to the operation, just omit the third hash:
+If you do not want to pass any parameters to the operation, just omit the third hash:
 
 ```ruby
 Workhorse.enqueue_op Operations::Jobs::CleanUpDatabase, queue: :maintenance, priority: 2
@@ -138,9 +138,9 @@ achieving regular execution:
    by scheduling the job before knowing whether the current run will succeed.
    Proceed down this path at your own peril!)
 
-   *Example:* A job that takes 5 seconds to run and is set to reschedule itself
-   after 10 minutes is started at 12:00 sharp. After one hour it will be set to
-   execute at 13:00:30 at the earliest.
+   *Example:* A job that takes 5 seconds to run and reschedules itself every
+   10 minutes. If started at 12:00 sharp, after one hour it will execute at
+   13:00:30 at the earliest due to cumulative execution time.
 
    In its most basic form, the `perform` method of a job would look as follows:
 
@@ -198,7 +198,7 @@ achieving regular execution:
    of which is that only one 'worker' should be started by the ShellHandler.
    Otherwise there would be multiple jobs scheduled at the same time.
 
-   Please refer to the documentation on
+   Please refer to the documentation for
    [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) (or the
    scheduler of your choice) for further options concerning the timing of the
    jobs.
@@ -227,8 +227,7 @@ Workhorse::Worker.start_and_wait(
 
 See [code documentation](http://www.rubydoc.info/github/sitrox/workhorse/Workhorse%2FWorker:initialize)
 for more information on the arguments. All arguments passed to `start_and_wait`
-are passed to the initialize. All arguments passed to `start_and_wait` are
-in turn passed to the initializer of `Workhorse::Worker`.
+are passed to the initializer of `Workhorse::Worker`.
 
 ### Start workers using a daemon script
 
@@ -264,7 +263,7 @@ end
 
 ### Instant repolling
 
-Per default, each worker only polls in the given interval. This means that if
+By default, each worker only polls in the given interval. This means that if
 you schedule, for example, 50 jobs at once and have a polling interval of 1
 minute with a queue size of 1, the poller would tackle the first job and then
 wait for a whole minute until the next poll. This would mean that these 50 jobs
@@ -287,8 +286,8 @@ transaction is created.
 
 ### Transaction callback
 
-By default, transactions are created using `ActiveRecord::Base.transaction { ...
-}`. You can customize this using the setting `config.tx_callback` in your
+By default, transactions are created using `ActiveRecord::Base.transaction`.
+You can customize this using the setting `config.tx_callback` in your
 `config/initializers/workhorse.rb` (see commented out section in the generated
 configuration file).
 
@@ -342,7 +341,7 @@ You can turn off transaction wrapping in the following ways:
      end
      ```
 
-  For plain Workhrose job clases:
+  For plain Workhorse job classes:
 
   1. Add the following static method to your job class:
 
@@ -352,13 +351,14 @@ You can turn off transaction wrapping in the following ways:
          true
        end
      end
+     ```
 
 ## Exception handling
 
-Per default, exceptions occurring in a worker thread will only be visible in the
+By default, exceptions occurring in a worker thread will only be visible in the
 respective log file, usually `production.log`. If you'd like to perform specific
 actions when an exception arises, set the global option `on_exception` to a
-callback of your linking, e.g.:
+callback of your liking, e.g.:
 
 ```ruby
 # config/initializers/workhorse.rb
@@ -467,7 +467,7 @@ succeeded jobs. You can run this using your scheduler in a specific interval.
 ## Memory handling
 
 When a worker exceeds the memory limit specified by
-`config.max_worker_memory_mb` (assuming it is configured and > 0), it initiates
+`config.max_worker_memory_mb` (assuming it is configured to a value greater than 0), it initiates
 a graceful shutdown process by creating a shutdown file named
 `tmp/pids/workhorse.<pid>.shutdown`.
 
@@ -564,4 +564,4 @@ Please consult the [FAQ](FAQ.md).
 
 ## Copyright
 
-Copyright © 2017 - 2024 Sitrox. See `LICENSE` for further details.
+Copyright © 2017 - 2026 Sitrox. See `LICENSE` for further details.

data/Rakefile

@@ -11,8 +11,8 @@ task :gemspec do
     spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
     spec.require_paths = ['lib']
 
-    spec.add_dependency 'activesupport'
-    spec.add_dependency 'activerecord'
+    spec.add_dependency 'activesupport', '>= 7.0.0'
+    spec.add_dependency 'activerecord', '>= 7.0.0'
     spec.add_dependency 'concurrent-ruby'
   end
 

data/VERSION

@@ -1 +1 @@
-1.3.0.rc2
+1.3.0.rc4

data/lib/active_job/queue_adapters/workhorse_adapter.rb

@@ -1,28 +1,44 @@
 module ActiveJob
   module QueueAdapters
-    # == Workhorse adapter for Active Job
+    # Workhorse adapter for ActiveJob.
     #
-    # Workhorse is a multi-threaded job backend with database queuing for ruby.
-    # Jobs are persisted in the database using ActiveRecird.
-    # Read more about Workhorse {here}[https://github.com/sitrox/activejob].
+    # Workhorse is a multi-threaded job backend with database queuing for Ruby.
+    # Jobs are persisted in the database using ActiveRecord.
+    # Read more about Workhorse {here}[https://github.com/sitrox/workhorse].
     #
     # To use Workhorse, set the queue_adapter config to +:workhorse+.
     #
     #   Rails.application.config.active_job.queue_adapter = :workhorse
+    #
+    # @example Configuration
+    #   Rails.application.config.active_job.queue_adapter = :workhorse
     class WorkhorseAdapter
       # Defines whether enqueuing should happen implicitly to after commit when called
       # from inside a transaction. Most adapters should return true, but some adapters
       # that use the same database as Active Record and are transaction aware can return
       # false to continue enqueuing jobs as part of the transaction.
+      #
+      # @return [Boolean] False because Workhorse is transaction-aware
       def enqueue_after_transaction_commit?
         false
       end
 
-      def enqueue(job) # :nodoc:
+      # Enqueues a job for immediate execution.
+      #
+      # @param job [ActiveJob::Base] The job to enqueue
+      # @return [Workhorse::DbJob] The created database job record
+      # @api private
+      def enqueue(job)
         Workhorse.enqueue_active_job(job)
       end
 
-      def enqueue_at(job, timestamp = Time.now) # :nodoc:
+      # Enqueues a job for execution at a specific time.
+      #
+      # @param job [ActiveJob::Base] The job to enqueue
+      # @param timestamp [Time] When to execute the job
+      # @return [Workhorse::DbJob] The created database job record
+      # @api private
+      def enqueue_at(job, timestamp = Time.now)
         Workhorse.enqueue_active_job(job, perform_at: timestamp)
       end
     end

data/lib/workhorse/active_job_extension.rb

@@ -1,4 +1,5 @@
 module Workhorse
+  # Extension module for ActiveJob integration.
   module ActiveJobExtension
     extend ActiveSupport::Concern
 
@@ -8,10 +9,18 @@ module Workhorse
     end
 
     module ClassMethods
+      # Marks this job class to skip database transactions during execution.
+      # Use this for jobs that manage their own transactions or have long-running
+      # operations that should not be wrapped in a transaction.
+      #
+      # @return [void]
       def skip_tx
         self._skip_tx = true
       end
 
+      # Checks if this job class should skip database transactions.
+      #
+      # @return [Boolean] True if transactions should be skipped
       def skip_tx?
         _skip_tx
       end

data/lib/workhorse/daemon.rb

@@ -1,11 +1,28 @@
 module Workhorse
+  # Daemon class for managing multiple worker processes.
+  # Provides functionality to start, stop, restart, and monitor worker processes
+  # through a simple Ruby DSL.
   class Daemon
+    # Internal representation of a worker process.
+    # Stores worker metadata and the block to execute.
     class Worker
+      # @return [Integer] The worker's unique ID
       attr_reader :id
+
+      # @return [String] The worker's display name
       attr_reader :name
+
+      # @return [Proc] The block containing the worker's logic
       attr_reader :block
+
+      # @return [Integer, nil] The worker's process ID when running
       attr_accessor :pid
 
+      # Creates a new worker definition.
+      #
+      # @param id [Integer] Unique identifier for this worker
+      # @param name [String] Display name for this worker
+      # @param block [Proc] Code block to execute in the worker process
       def initialize(id, name, &block)
         @id = id
         @name = name
@@ -13,9 +30,16 @@ module Workhorse
       end
     end
 
+    # @return [Array<Worker>] Array of defined workers
     # @private
     attr_reader :workers
 
+    # Creates a new daemon instance.
+    #
+    # @param pidfile [String, nil] Path template for PID files (use %i placeholder for worker ID)
+    # @param quiet [Boolean] Whether to suppress output during operations
+    # @yield [ScopedEnv] Configuration block for defining workers
+    # @raise [RuntimeError] If no workers are defined or pidfile format is invalid
     def initialize(pidfile: nil, quiet: false, &_block)
       @pidfile = pidfile
       @quiet = quiet
@@ -38,10 +62,19 @@ module Workhorse
       end
     end
 
+    # Defines a worker process.
+    #
+    # @param name [String] Display name for the worker
+    # @yield Block containing the worker's execution logic
+    # @return [void]
     def worker(name = 'Job Worker', &block)
       @workers << Worker.new(@workers.size + 1, name, &block)
     end
 
+    # Starts all defined workers.
+    #
+    # @param quiet [Boolean] Whether to suppress status output
+    # @return [Integer] Exit code (0 = success, 2 = some workers already running)
     def start(quiet: false)
       code = 0
 
@@ -81,6 +114,11 @@ module Workhorse
       return code
     end
 
+    # Stops all running workers.
+    #
+    # @param kill [Boolean] Whether to use KILL signal instead of TERM/INT
+    # @param quiet [Boolean] Whether to suppress status output
+    # @return [Integer] Exit code (0 = success, 2 = some workers already stopped)
     def stop(kill = false, quiet: false)
       code = 0
 
@@ -102,6 +140,10 @@ module Workhorse
       return code
     end
 
+    # Checks the status of all workers.
+    #
+    # @param quiet [Boolean] Whether to suppress status output
+    # @return [Integer] Exit code (0 = all running, 2 = some not running)
     def status(quiet: false)
       code = 0
 
@@ -122,6 +164,10 @@ module Workhorse
       return code
     end
 
+    # Watches workers and starts them if they're not running.
+    # In Rails environments, respects the tmp/stop.txt file.
+    #
+    # @return [Integer] Exit code from start operation or 0 if no action needed
     def watch
       if defined?(Rails)
         should_be_running = !File.exist?(Rails.root.join('tmp/stop.txt'))
@@ -136,11 +182,18 @@ module Workhorse
       end
     end
 
+    # Restarts all workers by stopping and then starting them.
+    #
+    # @return [Integer] Exit code from start operation
     def restart
       stop
       return start
     end
 
+    # Sends HUP signal to all workers to restart their logging.
+    # Useful for log rotation without full process restart.
+    #
+    # @return [Integer] Exit code (0 = success, 2 = some signals failed)
     def restart_logging
       code = 0
 
@@ -163,10 +216,20 @@ module Workhorse
 
     private
 
+    # Executes the given block for each defined worker.
+    #
+    # @yield [Worker] Each worker instance
+    # @return [void]
+    # @private
     def for_each_worker(&block)
       @workers.each(&block)
     end
 
+    # Starts a single worker process.
+    #
+    # @param worker [Worker] The worker to start
+    # @return [void]
+    # @private
     def start_worker(worker)
       check_rails_env if defined?(Rails)
 
@@ -185,6 +248,13 @@ module Workhorse
       Process.detach(pid)
     end
 
+    # Stops a single worker process.
+    #
+    # @param pid_file [String] Path to the worker's PID file
+    # @param pid [Integer] The worker's process ID
+    # @param kill [Boolean] Whether to use KILL signal
+    # @return [void]
+    # @private
     def stop_worker(pid_file, pid, kill: false)
       signals = kill ? %w[KILL] : %w[TERM INT]
 
@@ -201,10 +271,20 @@ module Workhorse
       File.delete(pid_file)
     end
 
+    # Sends HUP signal to a worker process.
+    #
+    # @param pid [Integer] The worker's process ID
+    # @return [void]
+    # @private
     def hup_worker(pid)
       Process.kill('HUP', pid)
     end
 
+    # Generates a process name for a worker.
+    #
+    # @param worker [Worker] The worker instance
+    # @return [String] Process name for ps output
+    # @private
     def process_name(worker)
       if defined?(Rails)
         path = Rails.root
@@ -215,6 +295,11 @@ module Workhorse
       return "Workhorse #{worker.name} ##{worker.id}: #{path}"
     end
 
+    # Checks if a process with the given PID is running.
+    #
+    # @param pid [Integer] Process ID to check
+    # @return [Boolean] True if process is running
+    # @private
     def process?(pid)
       return begin
         Process.kill(0, pid)
@@ -224,10 +309,20 @@ module Workhorse
       end
     end
 
+    # Returns the PID file path for a worker.
+    #
+    # @param worker [Worker] The worker instance
+    # @return [String] Path to the PID file
+    # @private
     def pid_file_for(worker)
       @pidfile % worker.id
     end
 
+    # Reads PID information for a worker.
+    #
+    # @param worker [Worker] The worker instance
+    # @return [Array<String, Integer, Boolean>] PID file path, PID, and active status
+    # @private
     def read_pid(worker)
       file = pid_file_for(worker)
       pid = nil
@@ -247,6 +342,10 @@ module Workhorse
       return file, pid, active
     end
 
+    # Warns if not running in production environment.
+    #
+    # @return [void]
+    # @private
     def check_rails_env
       unless Rails.env.production?
         warn 'WARNING: Always run workhorse workers in production environment. Other environments can lead to unexpected behavior.'