workhorse 1.3.0.rc3 → 1.3.0.rc4

data/lib/workhorse/db_job.rb

@@ -1,4 +1,17 @@
 module Workhorse
+  # ActiveRecord model representing a job in the database.
+  # This class manages the job lifecycle and state transitions within the Workhorse system.
+  #
+  # @example Creating a job
+  #   job = DbJob.create!(
+  #     queue: 'default',
+  #     handler: Marshal.dump(job_instance),
+  #     priority: 0
+  #   )
+  #
+  # @example Querying jobs by state
+  #   waiting_jobs = DbJob.waiting
+  #   failed_jobs = DbJob.failed
   class DbJob < ActiveRecord::Base
     STATE_WAITING   = :waiting
     STATE_LOCKED    = :locked
@@ -14,26 +27,45 @@ module Workhorse
 
     self.table_name = 'jobs'
 
+    # Returns jobs in waiting state.
+    #
+    # @return [ActiveRecord::Relation] Jobs waiting to be processed
     def self.waiting
       where(state: STATE_WAITING)
     end
 
+    # Returns jobs in locked state.
+    #
+    # @return [ActiveRecord::Relation] Jobs currently locked by workers
     def self.locked
       where(state: STATE_LOCKED)
     end
 
+    # Returns jobs in started state.
+    #
+    # @return [ActiveRecord::Relation] Jobs currently being executed
     def self.started
       where(state: STATE_STARTED)
     end
 
+    # Returns jobs in succeeded state.
+    #
+    # @return [ActiveRecord::Relation] Jobs that completed successfully
     def self.succeeded
       where(state: STATE_SUCCEEDED)
     end
 
+    # Returns jobs in failed state.
+    #
+    # @return [ActiveRecord::Relation] Jobs that failed during execution
     def self.failed
       where(state: STATE_FAILED)
     end
 
+    # Returns a relation with split locked_by field for easier querying.
+    # Extracts host, PID, and random string components from locked_by.
+    #
+    # @return [ActiveRecord::Relation] Relation with additional computed columns
     # @private
     def self.with_split_locked_by
       select(<<~SQL)
@@ -74,6 +106,9 @@ module Workhorse
     # ("failed"), make sure the actions performed in the job are repeatable or
     # have been rolled back. E.g. if the job already wrote something to an
     # external API, it may cause inconsistencies if the job is performed again.
+    #
+    # @param force [Boolean] Whether to force reset without state validation
+    # @raise [RuntimeError] If job is not in a final state and force is false
     def reset!(force = false)
       unless force
         assert_state! STATE_SUCCEEDED, STATE_FAILED
@@ -90,6 +125,10 @@ module Workhorse
       save!
     end
 
+    # Marks the job as locked by a specific worker.
+    #
+    # @param worker_id [String] The ID of the worker locking this job
+    # @raise [RuntimeError] If the job is dirty or already locked
     # @private Only to be used by workhorse
     def mark_locked!(worker_id)
       if changed?
@@ -108,6 +147,9 @@ module Workhorse
       save!
     end
 
+    # Marks the job as started.
+    #
+    # @raise [RuntimeError] If the job is not in locked state
     # @private Only to be used by workhorse
     def mark_started!
       assert_state! STATE_LOCKED
@@ -117,6 +159,10 @@ module Workhorse
       save!
     end
 
+    # Marks the job as failed with the given exception.
+    #
+    # @param exception [Exception] The exception that caused the failure
+    # @raise [RuntimeError] If the job is not in locked or started state
     # @private Only to be used by workhorse
     def mark_failed!(exception)
       assert_state! STATE_LOCKED, STATE_STARTED
@@ -127,6 +173,9 @@ module Workhorse
       save!
     end
 
+    # Marks the job as succeeded.
+    #
+    # @raise [RuntimeError] If the job is not in started state
     # @private Only to be used by workhorse
     def mark_succeeded!
       assert_state! STATE_STARTED
@@ -136,6 +185,10 @@ module Workhorse
       save!
     end
 
+    # Asserts that the job is in one of the specified states.
+    #
+    # @param states [Array<Symbol>] Valid states for the job
+    # @raise [RuntimeError] If the job is not in any of the specified states
     def assert_state!(*states)
       unless states.include?(state.to_sym)
         fail "Job #{id} is not in state #{states.inspect} but in state #{state.inspect}."

data/lib/workhorse/enqueuer.rb

@@ -1,6 +1,16 @@
 module Workhorse
+  # Module providing job enqueuing functionality.
+  # Extended by the main Workhorse module to provide enqueuing capabilities.
+  # Supports plain Ruby objects, ActiveJob instances, and Rails operations.
   module Enqueuer
-    # Enqueue any object that is serializable and has a `perform` method
+    # Enqueues any object that is serializable and has a `perform` method.
+    #
+    # @param job [Object] The job object to enqueue (must respond to #perform)
+    # @param queue [String, Symbol, nil] The queue name
+    # @param priority [Integer] Job priority (lower numbers = higher priority)
+    # @param perform_at [Time] When to perform the job
+    # @param description [String, nil] Optional job description
+    # @return [Workhorse::DbJob] The created database job record
     def enqueue(job, queue: nil, priority: 0, perform_at: Time.now, description: nil)
       return DbJob.create!(
         queue:       queue,
@@ -11,7 +21,13 @@ module Workhorse
       )
     end
 
-    # Enqueue an ActiveJob job
+    # Enqueues an ActiveJob job instance.
+    #
+    # @param job [ActiveJob::Base] The ActiveJob instance to enqueue
+    # @param perform_at [Time] When to perform the job
+    # @param queue [String, Symbol, nil] Optional queue override
+    # @param description [String, nil] Optional job description
+    # @return [Workhorse::DbJob] The created database job record
     def enqueue_active_job(job, perform_at: Time.now, queue: nil, description: nil)
       wrapper_job = Jobs::RunActiveJob.new(job.serialize)
       queue ||= job.queue_name if job.queue_name.present?
@@ -26,7 +42,12 @@ module Workhorse
       return db_job
     end
 
-    # Enqueue the execution of an operation by its class and params
+    # Enqueues the execution of a Rails operation by its class and parameters.
+    #
+    # @param cls [Class] The operation class to execute
+    # @param args [Array] Variable arguments (workhorse_args, op_args)
+    # @return [Workhorse::DbJob] The created database job record
+    # @raise [ArgumentError] If wrong number of arguments provided
     def enqueue_op(cls, *args)
       case args.size
       when 0

data/lib/workhorse/jobs/cleanup_succeeded_jobs.rb

@@ -1,4 +1,14 @@
 module Workhorse::Jobs
+  # Job for cleaning up old succeeded jobs from the database.
+  # This maintenance job helps keep the jobs table from growing indefinitely
+  # by removing successfully completed jobs older than a specified age.
+  #
+  # @example Schedule cleanup job
+  #   Workhorse.enqueue(CleanupSucceededJobs.new(max_age: 30))
+  #
+  # @example Daily cleanup with cron
+  #   # Clean up jobs older than 14 days every day at 2 AM
+  #   Workhorse.enqueue(CleanupSucceededJobs.new, perform_at: 1.day.from_now.beginning_of_day + 2.hours)
   class CleanupSucceededJobs
     # Instantiates a new job.
     #
@@ -8,6 +18,9 @@ module Workhorse::Jobs
       @max_age = max_age
     end
 
+    # Executes the cleanup by deleting old succeeded jobs.
+    #
+    # @return [void]
     def perform
       age_limit = seconds_ago(@max_age)
       Workhorse::DbJob.where(
@@ -17,6 +30,11 @@ module Workhorse::Jobs
 
     private
 
+    # Calculates a timestamp for the given number of days ago.
+    #
+    # @param days [Integer] Number of days in the past
+    # @return [Time] Timestamp for the specified days ago
+    # @private
     def seconds_ago(days)
       Time.now - (days * 24 * 60 * 60)
     end

data/lib/workhorse/jobs/detect_stale_jobs_job.rb

@@ -1,22 +1,36 @@
 module Workhorse::Jobs
-  # This job picks up jobs that remained `locked` or `started` (running) for
+  # Job that detects and reports stale jobs in the system.
+  # This monitoring job picks up jobs that remained `locked` or `started` (running) for
   # more than a certain amount of time. If any of these jobs are found, an
   # exception is thrown (which may cause a notification if you configured
-  # `on_exception` accordingly).
+  # {Workhorse.on_exception} accordingly).
   #
   # The thresholds are obtained from the configuration options
-  # {Workhorse.stale_detection_locked_to_started_threshold
-  # config.stale_detection_locked_to_started_threshold} and
-  # {Workhorse.stale_detection_run_time_threshold
-  # config.stale_detection_run_time_threshold}.
+  # {Workhorse.stale_detection_locked_to_started_threshold} and
+  # {Workhorse.stale_detection_run_time_threshold}.
+  #
+  # @example Schedule stale job detection
+  #   Workhorse.enqueue(DetectStaleJobsJob.new)
+  #
+  # @example Configure thresholds
+  #   Workhorse.setup do |config|
+  #     config.stale_detection_locked_to_started_threshold = 300  # 5 minutes
+  #     config.stale_detection_run_time_threshold = 3600         # 1 hour
+  #   end
   class DetectStaleJobsJob
-    # @private
+    # Creates a new stale job detection job.
+    # Reads configuration thresholds at initialization time.
     def initialize
       @locked_to_started_threshold = Workhorse.stale_detection_locked_to_started_threshold
       @run_time_threshold          = Workhorse.stale_detection_run_time_threshold
     end
 
-    # @private
+    # Executes the stale job detection.
+    # Checks for jobs that have been locked or running too long and raises
+    # an exception if any are found.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If stale jobs are detected
     def perform
       messages = []
 

data/lib/workhorse/jobs/run_active_job.rb

@@ -1,15 +1,32 @@
 module Workhorse::Jobs
+  # Wrapper job for executing ActiveJob instances within Workhorse.
+  # This job handles the deserialization and execution of ActiveJob jobs
+  # that have been enqueued through the Workhorse adapter.
+  #
+  # @example Internal usage
+  #   wrapper = RunActiveJob.new(job.serialize)
+  #   wrapper.perform
   class RunActiveJob
+    # @return [Hash] Serialized ActiveJob data
     attr_reader :job_data
 
+    # Creates a new ActiveJob wrapper.
+    #
+    # @param job_data [Hash] Serialized ActiveJob data from job.serialize
     def initialize(job_data)
       @job_data = job_data
     end
 
+    # Returns the ActiveJob class for this job.
+    #
+    # @return [Class, nil] The job class or nil if not found
     def job_class
       @job_data['job_class'].safe_constantize
     end
 
+    # Executes the wrapped ActiveJob.
+    #
+    # @return [void]
     def perform
       ActiveJob::Base.execute(@job_data)
     end

data/lib/workhorse/jobs/run_rails_op.rb

@@ -1,14 +1,33 @@
 module Workhorse::Jobs
+  # Job wrapper for executing Rails operations (trailblazer-operation or similar).
+  # This job allows enqueuing of operation classes with parameters for later execution.
+  #
+  # @example Enqueue an operation
+  #   Workhorse.enqueue_op(MyOperation, { user_id: 123 })
+  #
+  # @example Manual instantiation
+  #   job = RunRailsOp.new(MyOperation, { user_id: 123 })
+  #   Workhorse.enqueue(job)
   class RunRailsOp
+    # Creates a new Rails operation job.
+    #
+    # @param cls [Class] The operation class to execute
+    # @param params [Hash] Parameters to pass to the operation
     def initialize(cls, params = {})
       @cls = cls
       @params = params
     end
 
+    # Returns the operation class for this job.
+    #
+    # @return [Class] The operation class
     def job_class
       @cls
     end
 
+    # Executes the Rails operation with the provided parameters.
+    #
+    # @return [void]
     def perform
       @cls.run!(@params)
     end

data/lib/workhorse/performer.rb

@@ -1,13 +1,30 @@
 module Workhorse
+  # Executes individual jobs within worker processes.
+  # The Performer handles job lifecycle management, error handling,
+  # and integration with Rails application executors.
+  #
+  # @example Basic usage (typically called internally)
+  #   performer = Workhorse::Performer.new(job_id, worker)
+  #   performer.perform
   class Performer
+    # @return [Workhorse::Worker] The worker that owns this performer
     attr_reader :worker
 
+    # Creates a new performer for a specific job.
+    #
+    # @param db_job_id [Integer] The ID of the {Workhorse::DbJob} to perform
+    # @param worker [Workhorse::Worker] The worker instance managing this performer
     def initialize(db_job_id, worker)
       @db_job = Workhorse::DbJob.find(db_job_id)
       @worker = worker
       @started = false
     end
 
+    # Executes the job with full error handling and state management.
+    # This method can only be called once per performer instance.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If called more than once
     def perform
       begin # rubocop:disable Style/RedundantBegin
         fail 'Performer can only run once.' if @started
@@ -20,6 +37,12 @@ module Workhorse
 
     private
 
+    # Internal job execution with thread-local performer tracking.
+    # Wraps the job execution with Rails application executor if available.
+    #
+    # @return [void]
+    # @raise [Exception] Any exception raised during job execution
+    # @private
     def perform!
       begin # rubocop:disable Style/RedundantBegin
         Thread.current[:workhorse_current_performer] = self
@@ -50,6 +73,13 @@ module Workhorse
       end
     end
 
+    # Core job execution logic with state transitions.
+    # Handles marking job as started, deserializing and executing the job,
+    # and marking as succeeded.
+    #
+    # @return [void]
+    # @raise [Exception] Any exception raised during job execution
+    # @private
     def perform_wrapped
       # ---------------------------------------------------------------
       # Mark job as started
@@ -87,11 +117,23 @@ module Workhorse
       end
     end
 
+    # Logs a message with job ID prefix.
+    #
+    # @param text [String] The message to log
+    # @param level [Symbol] The log level
+    # @return [void]
+    # @private
     def log(text, level = :info)
       text = "[#{@db_job.id}] #{text}"
       worker.log text, level
     end
 
+    # Deserializes the job from the database handler field.
+    # Uses Marshal.load which is safe as long as jobs are enqueued through
+    # {Workhorse::Enqueuer}.
+    #
+    # @return [Object] The deserialized job instance
+    # @private
     def deserialized_job
       # The source is safe as long as jobs are always enqueued using
       # Workhorse::Enqueuer so it is ok to use Marshal.load.

data/lib/workhorse/poller.rb

@@ -1,4 +1,11 @@
 module Workhorse
+  # Database poller that discovers and locks jobs for execution.
+  # Handles job querying, global locking, and job distribution to workers.
+  # Supports both MySQL and Oracle databases with database-specific optimizations.
+  #
+  # @example Basic usage (typically used internally)
+  #   poller = Workhorse::Poller.new(worker, proc { true })
+  #   poller.start
   class Poller
     MIN_LOCK_TIMEOUT = 0.1 # In seconds
     MAX_LOCK_TIMEOUT = 1.0 # In seconds
@@ -6,9 +13,16 @@ module Workhorse
     ORACLE_LOCK_MODE   = 6           # X_MODE (exclusive)
     ORACLE_LOCK_HANDLE = 478_564_848 # Randomly chosen number
 
+    # @return [Workhorse::Worker] The worker this poller serves
     attr_reader :worker
+
+    # @return [Arel::Table] The jobs table for query building
     attr_reader :table
 
+    # Creates a new poller for the given worker.
+    #
+    # @param worker [Workhorse::Worker] The worker to serve
+    # @param before_poll [Proc] Callback executed before each poll (should return boolean)
     def initialize(worker, before_poll = proc { true })
       @worker = worker
       @running = false
@@ -20,10 +34,17 @@ module Workhorse
       @before_poll = before_poll
     end
 
+    # Checks if the poller is currently running.
+    #
+    # @return [Boolean] True if poller is running
     def running?
       @running
     end
 
+    # Starts the poller in a background thread.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If poller is already running
     def start
       fail 'Poller is already running.' if running?
       @running = true
@@ -55,18 +76,27 @@ module Workhorse
       end
     end
 
+    # Shuts down the poller and waits for completion.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If poller is not running
     def shutdown
       fail 'Poller is not running.' unless running?
       @running = false
       wait
     end
 
+    # Waits for the poller thread to complete.
+    #
+    # @return [void]
     def wait
       @thread.join
     end
 
-    # Call this to interrupt current sleep and perform the next poll as soon as
-    # possible, then resume in the normal polling interval.
+    # Interrupts current sleep and performs the next poll immediately.
+    # After the poll, resumes normal polling interval.
+    #
+    # @return [void]
     def instant_repoll!
       worker.log 'Aborting next sleep to perform instant repoll', :debug
       @instant_repoll.make_true
@@ -74,6 +104,11 @@ module Workhorse
 
     private
 
+    # Cleans up jobs stuck in locked or started states from dead processes.
+    # Only cleans jobs from the current hostname.
+    #
+    # @return [void]
+    # @private
     def clean_stuck_jobs!
       with_global_lock timeout: MAX_LOCK_TIMEOUT do
         Workhorse.tx_callback.call do
@@ -131,6 +166,10 @@ module Workhorse
       end
     end
 
+    # Sleeps for the configured polling interval with instant repoll support.
+    #
+    # @return [void]
+    # @private
     def sleep
       remaining = worker.polling_interval
 
@@ -140,6 +179,14 @@ module Workhorse
       end
     end
 
+    # Executes a block with a global database lock.
+    # Supports both MySQL GET_LOCK and Oracle DBMS_LOCK.
+    #
+    # @param name [Symbol] Lock name identifier
+    # @param timeout [Integer] Lock timeout in seconds
+    # @yield Block to execute while holding the lock
+    # @return [void]
+    # @private
     def with_global_lock(name: :workhorse, timeout: 2, &_block)
       begin # rubocop:disable Style/RedundantBegin
         if @is_oracle
@@ -201,14 +248,18 @@ module Workhorse
       end
     end
 
+    # Performs a single poll cycle to discover and lock jobs.
+    #
+    # @return [void]
+    # @private
     def poll
       @instant_repoll.make_false
 
       timeout = [MIN_LOCK_TIMEOUT, [MAX_LOCK_TIMEOUT, worker.polling_interval].min].max
       with_global_lock timeout: timeout do
-        Workhorse.tx_callback.call do
-          job_ids = []
+        job_ids = []
 
+        Workhorse.tx_callback.call do
           # As we are the only thread posting into the worker pool, it is safe to
           # get the number of idle threads without mutex synchronization. The
           # actual number of idle workers at time of posting can only be larger
@@ -230,13 +281,23 @@ module Workhorse
             worker.log 'Rolling back transaction to unlock jobs, as worker has been shut down in the meantime'
             fail ActiveRecord::Rollback
           end
-
-          job_ids.each { |job_id| worker.perform(job_id) }
         end
+
+        # This needs to be outside the above transaction because it runs the job
+        # in a new thread which opens a new connection. Even though it would be
+        # non-blocking and thus directly conclude the block and the transaction,
+        # there would still be a risk that the transaction is not committed yet
+        # when the job starts.
+        job_ids.each { |job_id| worker.perform(job_id) } if running?
       end
     end
 
-    # Returns an Array of #{Workhorse::DbJob}s that can be started
+    # Returns an array of {Workhorse::DbJob}s that can be started.
+    # Uses complex SQL with UNIONs to respect queue ordering and limits.
+    #
+    # @param limit [Integer] Maximum number of jobs to return
+    # @return [Array<Workhorse::DbJob>] Jobs ready for execution
+    # @private
     def queued_db_jobs(limit)
       # ---------------------------------------------------------------
       # Select jobs to execute

data/lib/workhorse/pool.rb

@@ -1,9 +1,22 @@
 module Workhorse
-  # Abstraction layer of a simple thread pool implementation used by the worker.
+  # Thread pool abstraction used by workers for concurrent job execution.
+  # Wraps Concurrent::ThreadPoolExecutor to provide a simpler interface
+  # and custom behavior for job processing.
+  #
+  # @example Basic usage
+  #   pool = Workhorse::Pool.new(4)
+  #   pool.post { puts "Working..." }
+  #   pool.shutdown
   class Pool
+    # @return [Mutex] Synchronization mutex for thread safety
     attr_reader :mutex
+
+    # @return [Concurrent::AtomicFixnum] Thread-safe counter of active threads
     attr_reader :active_threads
 
+    # Creates a new thread pool with the specified size.
+    #
+    # @param size [Integer] Maximum number of threads in the pool
     def initialize(size)
       @size = size
       @executor = Concurrent::ThreadPoolExecutor.new(
@@ -18,11 +31,19 @@ module Workhorse
       @on_idle = nil
     end
 
+    # Sets a callback to be executed when the pool becomes idle.
+    #
+    # @yield Block to execute when all threads become idle
+    # @return [void]
     def on_idle(&block)
       @on_idle = block
     end
 
-    # Posts a new work unit to the pool.
+    # Posts a new work unit to the pool for execution.
+    #
+    # @yield The work block to execute
+    # @return [void]
+    # @raise [RuntimeError] If all threads are busy
     def post
       mutex.synchronize do
         if idle.zero?
@@ -44,14 +65,18 @@ module Workhorse
       end
     end
 
-    # Returns the number of idle threads.
+    # Returns the number of idle threads in the pool.
+    #
+    # @return [Integer] Number of idle threads
     def idle
       @size - @active_threads.value
     end
 
     # Waits until the pool is shut down. This will wait forever unless you
-    # eventually call shutdown (either before calling `wait` or after it in
+    # eventually call {#shutdown} (either before calling `wait` or after it in
     # another thread).
+    #
+    # @return [void]
     def wait
       # Here we use a loop-sleep combination instead of using
       # ThreadPoolExecutor's `wait_for_termination`. See issue #21 for more
@@ -63,6 +88,9 @@ module Workhorse
     end
 
     # Shuts down the pool and waits for termination.
+    # All currently executing jobs will complete before shutdown.
+    #
+    # @return [void]
     def shutdown
       @executor.shutdown
       wait

data/lib/workhorse/scoped_env.rb

@@ -1,11 +1,26 @@
 module Workhorse
+  # Scoped environment for method delegation.
+  # Used internally to provide scoped access to daemon configuration methods.
+  #
+  # @private
   class ScopedEnv
+    # Creates a new scoped environment.
+    #
+    # @param delegation_object [Object] Object to delegate method calls to
+    # @param methods [Array<Symbol>] Methods that should be delegated
+    # @param backup_binding [Object, nil] Fallback object for method resolution
     def initialize(delegation_object, methods, backup_binding = nil)
       @delegation_object = delegation_object
       @methods = methods
       @backup_binding = backup_binding
     end
 
+    # Handles method delegation to the configured objects.
+    #
+    # @param symbol [Symbol] Method name
+    # @param args [Array] Method arguments
+    # @param block [Proc, nil] Block to pass to the method
+    # @return [Object] Result of the delegated method call
     def method_missing(symbol, *args, &block)
       if @methods.include?(symbol)
         @delegation_object.send(symbol, *args, &block)
@@ -16,6 +31,11 @@ module Workhorse
       end
     end
 
+    # Checks if this object can respond to the given method.
+    #
+    # @param symbol [Symbol] Method name to check
+    # @param include_private [Boolean] Whether to include private methods
+    # @return [Boolean] True if method can be handled
     def respond_to_missing?(symbol, include_private = false)
       @methods.include?(symbol) || super
     end