philiprehberger-task_queue 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd60112f6cfee945ef38be345d06ee98eb67f8cf41c58130d878806512f6459
-  data.tar.gz: 0def7843e02bfa558090f72aa9deee01c9383f5dbc2bbdfa7d8864f3b0e41cef
+  metadata.gz: 3b052683a824db4cfaab12c8216cb66a99d40580d085ae630a3dfda88879b82d
+  data.tar.gz: de60b9e402664d5688461aa1e5659a3a686646de142ce2123728c61f5da7ff35
 SHA512:
-  metadata.gz: e80d762e3fb12eed38918bc931c8b057052800938746ac83d35b86343e129e1aec1ab41a6f85f971ddf7f96fdcba181fd0e9d69971e347cc2b50ee371bb25340
-  data.tar.gz: 882bd1d57135f0e52e55dea6bc6a8660e443c4061e0e629dba35ae0ffff9ea43e0ce61848c2c939d4267452def0be6a546584a79219b1102dedf208f9216843d
+  metadata.gz: 76e39073b3e7a723836810427fc10a7e7777831e4f5473ecd5cb4cd0a9424eb9b91c4f303d5d9bc8e33f293e8d6342d77d6e8f9f45e75a9bfeedfa6c551779e1
+  data.tar.gz: 287f3097f118a996bd0dc0b10edb86c9c904fdf62cfd8d4113b72e1808582309cae98409a520dd0d3edd39e7320f4af5b845848d318a2f0ea11d5be2d78ba2cc

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-30
+
+### Added
+- Bounded queue — `max_size:` constructor option caps the number of pending tasks (`nil`, the default, keeps the queue unbounded); the capacity check and enqueue happen atomically under the queue mutex
+- `Philiprehberger::TaskQueue::QueueFullError` (subclass of `Error`) raised by `push`/`<<` when a bounded queue is full
+- `Queue#full?` — whether the pending task count has reached `max_size` (always `false` when unbounded)
+- `Queue#max_size` — reader for the configured limit
+
+### Changed
+- `.gitignore` aligned with the gem guide template
+- CI workflow aligned with the gem guide template, publishing via a RubyGems credentials file
+- Feature request issue template now includes a proposed-API code placeholder
+
+## [0.8.0] - 2026-07-15
+
+### Added
+- Automatic retries with backoff — `max_retries:`, `retry_backoff:` (`:none`/`:fixed`/`:exponential`), and `retry_base_delay:` constructor options; failing tasks are requeued up to `max_retries` times before counting as `failed`
+- `retried` counter in `stats` reporting the total number of retry attempts made
+- `on_error` now receives the 1-based attempt number as its third argument
+- Task priorities — `push(priority:)` dequeues higher-priority tasks first while preserving FIFO order within the same priority (default priority `0` keeps pure FIFO behavior)
+
+### Fixed
+- Callbacks registered after the first `push` (via `on_error`/`on_complete`) now fire; handlers are read live at execution time instead of being snapshotted when workers start
+- User callbacks are isolated from stats accounting and the worker loop — a raising completion or error callback can no longer corrupt the `in_flight`/`completed`/`failed` counters or kill a worker thread
+
 ## [0.7.1] - 2026-06-14
 
 ### Changed
@@ -128,3 +153,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Thread-safe task enqueuing with `push` / `<<`
 - Graceful shutdown with timeout support
 - Auto-starting worker threads on first push
+
+[Unreleased]: https://github.com/philiprehberger/rb-task-queue/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/philiprehberger/rb-task-queue/compare/v0.7.1...v0.8.0

data/README.md

@@ -66,7 +66,34 @@ queue.push { File.read("/nonexistent") }
 
 queue.drain(timeout: 5)
 puts queue.stats
-# => { completed: 0, failed: 2, pending: 0, in_flight: 0 }
+# => { completed: 0, failed: 2, pending: 0, in_flight: 0, retried: 0 }
+```
+
+### Retries and backoff
+
+Failing tasks can be retried automatically. Pass `max_retries:` (default `0`, no retries) and a `retry_backoff:` policy (`:none`, `:fixed`, or `:exponential`) with a `retry_base_delay:` in seconds. A task that raises a `StandardError` is requeued up to `max_retries` times before being counted as `failed`. The `on_error` callback fires on every failed attempt and receives the attempt number as its third argument. The number of retry attempts is tracked in `stats[:retried]`.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(
+  concurrency: 4,
+  max_retries: 3,
+  retry_backoff: :exponential,  # :none | :fixed | :exponential
+  retry_base_delay: 0.5         # seconds; grows 0.5, 1.0, 2.0 for :exponential
+)
+
+queue.on_error do |exception, task, attempt|
+  warn "[TaskQueue] attempt #{attempt} failed: #{exception.message}"
+end
+
+attempts = 0
+queue.push do
+  attempts += 1
+  raise "transient failure" if attempts < 3
+  puts "succeeded on attempt #{attempts}"
+end
+
+queue.drain(timeout: 30)
+puts queue.stats[:retried]  # number of retry attempts made
 ```
 
 ### Completion callback
@@ -154,9 +181,45 @@ queue.stats_reset!
 queue.stats[:completed] # => 0
 ```
 
+### Task priorities
+
+Give tasks a `priority:` (default `0`) to have them dequeued ahead of lower-priority work. Higher priorities run first; tasks that share a priority preserve FIFO (insertion) order. The `<<` alias always enqueues at priority `0`.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 1)
+queue.pause
+
+queue.push(priority: 0)  { puts "low" }
+queue.push(priority: 10) { puts "high" }
+queue.push(priority: 5)  { puts "medium" }
+
+queue.resume
+queue.drain(timeout: 5)
+# high
+# medium
+# low
+```
+
+### Bounded queue
+
+Pass `max_size:` to cap the number of pending (not yet started) tasks. Once the limit is reached, `push` and `<<` raise `Philiprehberger::TaskQueue::QueueFullError` (a subclass of `Philiprehberger::TaskQueue::Error`) instead of growing without bound. The capacity check and the enqueue happen atomically, so concurrent producers can never overfill the queue. Tasks requeued for a retry are not counted against the limit. The default, `nil`, leaves the queue unbounded.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 2, max_size: 100)
+puts queue.max_size  # => 100
+
+begin
+  queue.push { process(job) }
+rescue Philiprehberger::TaskQueue::QueueFullError
+  # apply backpressure: drop, retry later, or slow the producer
+end
+
+puts queue.full?  # => true once 100 tasks are pending
+```
+
 ### FIFO ordering guarantees
 
-Tasks are stored in an internal array and dequeued in FIFO order. When `concurrency` is `1`, tasks execute strictly in the order they were pushed. With higher concurrency, dequeue order is still FIFO but tasks may complete out of order depending on individual execution time.
+Tasks are stored in an internal array and dequeued in priority-then-FIFO order. With the default priority of `0`, ordering is pure FIFO. When `concurrency` is `1`, equal-priority tasks execute strictly in the order they were pushed. With higher concurrency, dequeue order is still priority-then-FIFO but tasks may complete out of order depending on individual execution time.
 
 ```ruby
 results = Queue.new  # stdlib thread-safe queue for collecting output
@@ -202,17 +265,17 @@ queue.shutdown(timeout: 5)
 
 | Method | Parameters | Returns | Description |
 |---|---|---|---|
-| `.new(concurrency:)` | `concurrency` — max worker threads (Integer, default `4`) | `Queue` | Create a new queue with the given concurrency limit |
-| `#push(&block)` | `&block` — the task to execute | `self` | Enqueue a block for async execution; raises `ArgumentError` if no block given, raises `RuntimeError` if the queue is shut down |
-| `#<<(callable)` | `callable` — any object responding to `#call` | `self` | Alias for `#push`; convenient for lambdas and procs |
+| `.new(concurrency:, max_retries:, retry_backoff:, retry_base_delay:, max_size:)` | `concurrency` — max worker threads (Integer, default `4`); `max_retries` — retries before a task counts as failed (Integer, default `0`); `retry_backoff` — `:none`/`:fixed`/`:exponential` (default `:none`); `retry_base_delay` — base delay in seconds (Numeric, default `0.1`); `max_size` — max pending tasks (Integer or `nil`, default `nil` for unbounded) | `Queue` | Create a new queue; raises `ArgumentError` on a negative `max_retries`, unknown `retry_backoff`, or a `max_size` that is not a positive Integer |
+| `#push(&block)` | `priority` — dequeue priority, higher runs first (Integer, default `0`); `&block` — the task to execute | `self` | Enqueue a block for async execution; raises `ArgumentError` if no block given, raises `RuntimeError` if the queue is shut down, raises `QueueFullError` if the queue holds `max_size` pending tasks |
+| `#<<(callable)` | `callable` — any object responding to `#call` | `self` | Alias for `#push`; convenient for lambdas and procs; raises `QueueFullError` when full |
 | `#size` | _(none)_ | `Integer` | Number of pending (not yet started) tasks |
 | `#empty?` | _(none)_ | `Boolean` | Whether there are no pending tasks waiting to be started |
 | `#busy?` | _(none)_ | `Boolean` | Whether the queue has any pending tasks or in-flight tasks |
 | `#running?` | _(none)_ | `Boolean` | Whether the queue is accepting new tasks |
 | `#shutdown(timeout:)` | `timeout` — seconds to wait for workers (Numeric, default `30`) | `nil` | Signal workers to stop, drain remaining tasks, join threads up to `timeout` seconds |
 | `#on_complete(&block)` | `&block` — callback receiving `(result)` | `self` | Register a callback invoked after each successful task completion with the task's return value |
-| `#on_error(&block)` | `&block` — callback receiving `(exception, task)` | `self` | Register an error callback invoked when a task raises a `StandardError` |
-| `#stats` | _(none)_ | `Hash` | Returns `{ completed:, failed:, pending:, in_flight: }` with Integer counts |
+| `#on_error(&block)` | `&block` — callback receiving `(exception, task, attempt)` | `self` | Register an error callback invoked on every failed attempt when a task raises a `StandardError`; `attempt` is the 1-based attempt number |
+| `#stats` | _(none)_ | `Hash` | Returns `{ completed:, failed:, pending:, in_flight:, retried: }` with Integer counts (`retried` is the total number of retry attempts made) |
 | `#drain(timeout:)` | `timeout` — seconds to wait (Numeric, default `30`) | `nil` | Block until all pending and in-flight tasks complete without shutting down |
 | `#pause` | _(none)_ | `self` | Suspend task consumption; in-flight tasks finish but no new tasks are picked up |
 | `#resume` | _(none)_ | `self` | Resume a paused queue, waking workers to continue processing |
@@ -220,6 +283,9 @@ queue.shutdown(timeout: 5)
 | `#clear` | _(none)_ | `Integer` | Remove all pending tasks and return the number cleared |
 | `#stats_reset!` | _(none)_ | `self` | Atomically zero the `completed` and `failed` counters while leaving pending, in-flight, workers, and callbacks untouched |
 | `#concurrency` | _(none)_ | `Integer` | Returns the configured maximum number of concurrent worker threads |
+| `#max_size` | _(none)_ | `Integer`, `nil` | Returns the configured pending-task limit, or `nil` when unbounded |
+| `#full?` | _(none)_ | `Boolean` | Whether the pending task count has reached `max_size`; always `false` when unbounded |
+| `QueueFullError` | _(class)_ | — | Raised by `#push`/`#<<` on a full bounded queue; subclass of `Philiprehberger::TaskQueue::Error` |
 
 ## Development
 

data/lib/philiprehberger/task_queue/queue.rb

@@ -4,17 +4,44 @@ require_relative 'worker'
 
 module Philiprehberger
   module TaskQueue
+    # Internal representation of an enqueued task, carrying its priority and the
+    # number of attempts made so far (for retry accounting).
+    Entry = Struct.new(:callable, :priority, :attempts)
+
     # In-process async job queue with concurrency control.
     #
     # Tasks are enqueued as blocks or callable objects and executed by a pool of
     # worker threads. The queue is fully thread-safe.
     class Queue
+      # Supported retry backoff policies.
+      BACKOFF_POLICIES = %i[none fixed exponential].freeze
+
       # @return [Integer] the maximum number of concurrent worker threads
       attr_reader :concurrency
 
+      # @return [Integer, nil] the maximum number of pending tasks, or +nil+
+      #   when the queue is unbounded
+      attr_reader :max_size
+
       # @param concurrency [Integer] maximum number of concurrent worker threads
-      def initialize(concurrency: 4)
+      # @param max_retries [Integer] how many times a failing task is requeued
+      #   before it is counted as failed (default +0+, i.e. no retries)
+      # @param retry_backoff [Symbol] delay policy between retries — one of
+      #   +:none+, +:fixed+, or +:exponential+
+      # @param retry_base_delay [Numeric] base delay in seconds used by the
+      #   +:fixed+ and +:exponential+ backoff policies
+      # @param max_size [Integer, nil] maximum number of pending (not yet
+      #   started) tasks; +nil+ (the default) leaves the queue unbounded
+      # @raise [ArgumentError] if +max_retries+ is negative, +retry_backoff+
+      #   is not a recognized policy, or +max_size+ is not a positive Integer
+      def initialize(concurrency: 4, max_retries: 0, retry_backoff: :none, retry_base_delay: 0.1, max_size: nil)
         @concurrency = concurrency
+        @max_size = max_size
+        validate_max_size!
+        @max_retries = max_retries
+        @retry_backoff = retry_backoff
+        @retry_base_delay = retry_base_delay
+        validate_retry_options!
         @tasks = []
         @mutex = Mutex.new
         @condition = ConditionVariable.new
@@ -26,14 +53,19 @@ module Philiprehberger
         @pause_condition = ConditionVariable.new
         @error_handler = nil
         @complete_handler = nil
-        @stats = { completed: 0, failed: 0, in_flight: 0 }
+        @stats = { completed: 0, failed: 0, in_flight: 0, retried: 0 }
       end
 
       # Register a callback invoked when a task raises an exception.
       #
-      # The callback receives the exception and the task that raised it.
+      # The callback receives the exception, the task that raised it, and the
+      # attempt number (1 for the first try, incrementing on each retry). It
+      # fires on every failed attempt, including the ones that are retried.
       #
-      # @yield [exception, task] called on task failure
+      # The callback may be registered at any time — even after tasks have been
+      # pushed — and is read live when the task runs.
+      #
+      # @yield [exception, task, attempt] called on each task failure
       # @return [self]
       def on_error(&block)
         @mutex.synchronize { @error_handler = block }
@@ -53,11 +85,12 @@ module Philiprehberger
 
       # Return statistics about processed tasks.
       #
-      # @return [Hash{Symbol => Integer}] counts for :completed, :failed, :pending, :in_flight
+      # @return [Hash{Symbol => Integer}] counts for :completed, :failed,
+      #   :pending, :in_flight, and :retried (total retry attempts made)
       def stats
         @mutex.synchronize do
           { completed: @stats[:completed], failed: @stats[:failed], pending: @tasks.size,
-            in_flight: @stats[:in_flight] }
+            in_flight: @stats[:in_flight], retried: @stats[:retried] }
         end
       end
 
@@ -137,18 +170,30 @@ module Philiprehberger
 
       # Enqueue a task to be processed asynchronously.
       #
+      # Higher-priority tasks are dequeued before lower-priority ones; tasks
+      # that share a priority run in FIFO (insertion) order. The +<<+ alias
+      # always enqueues at the default priority of +0+.
+      #
+      # When the queue was created with +max_size+, the capacity check and the
+      # enqueue happen atomically, so concurrent pushers can never overfill it.
+      # Tasks requeued for a retry are not subject to the limit.
+      #
       # @param callable [#call, nil] a callable object (used by +<<+)
+      # @param priority [Integer] dequeue priority; higher runs first (default +0+)
       # @yield the block to execute (takes precedence over +callable+)
       # @return [self]
-      def push(callable = nil, &block)
+      # @raise [ArgumentError] if neither a block nor a callable is given
+      # @raise [QueueFullError] if the queue already holds +max_size+ pending tasks
+      def push(callable = nil, priority: 0, &block)
         task = block || callable
         raise ArgumentError, 'a block is required' unless task
 
         @mutex.synchronize do
           raise 'queue is shut down' unless @running
+          raise QueueFullError, "queue is full (max_size: #{@max_size})" if at_capacity?
 
           start_workers unless @started
-          @tasks << task
+          @tasks << Entry.new(task, priority, 0)
           @condition.signal
         end
 
@@ -173,6 +218,15 @@ module Philiprehberger
         @mutex.synchronize { @tasks.empty? }
       end
 
+      # Whether the pending task count has reached +max_size+.
+      #
+      # Always +false+ for an unbounded queue.
+      #
+      # @return [Boolean]
+      def full?
+        @mutex.synchronize { at_capacity? }
+      end
+
       # Whether the queue has any pending tasks or any in-flight tasks.
       #
       # Convenient inverse of "idle" for callers polling without going
@@ -205,6 +259,18 @@ module Philiprehberger
 
       private
 
+      # Must be called while holding +@mutex+.
+      def at_capacity?
+        !@max_size.nil? && @tasks.size >= @max_size
+      end
+
+      def validate_max_size!
+        return if @max_size.nil?
+        return if @max_size.is_a?(Integer) && @max_size.positive?
+
+        raise ArgumentError, "max_size must be a positive Integer or nil, got #{@max_size.inspect}"
+      end
+
       def signal_shutdown
         @mutex.synchronize do
           return unless @running
@@ -229,13 +295,24 @@ module Philiprehberger
         @concurrency.times do
           @workers << Worker.new(
             @tasks, @mutex, @condition,
-            context: { stats: @stats, error_handler: @error_handler,
-                       complete_handler: @complete_handler, drain_condition: @drain_condition,
-                       paused: -> { @paused }, pause_condition: @pause_condition }
+            context: { stats: @stats,
+                       error_handler: -> { @error_handler },
+                       complete_handler: -> { @complete_handler },
+                       drain_condition: @drain_condition,
+                       paused: -> { @paused }, pause_condition: @pause_condition,
+                       max_retries: @max_retries, retry_backoff: @retry_backoff,
+                       retry_base_delay: @retry_base_delay }
           )
         end
         @started = true
       end
+
+      def validate_retry_options!
+        raise ArgumentError, 'max_retries must be >= 0' if @max_retries.negative?
+        return if BACKOFF_POLICIES.include?(@retry_backoff)
+
+        raise ArgumentError, "unknown retry_backoff: #{@retry_backoff.inspect} (expected one of #{BACKOFF_POLICIES})"
+      end
     end
   end
 end

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = '0.7.1'
+    VERSION = '0.9.0'
   end
 end

data/lib/philiprehberger/task_queue/worker.rb

@@ -16,6 +16,9 @@ module Philiprehberger
         @drain_condition = context[:drain_condition]
         @paused = context[:paused]
         @pause_condition = context[:pause_condition]
+        @max_retries = context[:max_retries]
+        @retry_backoff = context[:retry_backoff]
+        @retry_base_delay = context[:retry_base_delay]
         @running = true
         @thread = Thread.new { run }
       end
@@ -39,32 +42,49 @@ module Philiprehberger
 
       def run
         loop do
-          task = next_task
-          break unless task
+          entry = next_task
+          break unless entry
 
-          execute(task)
+          execute(entry)
           @mutex.synchronize { @drain_condition.broadcast }
         end
       end
 
       def next_task
         @mutex.synchronize do
-          @condition.wait(@mutex) while @queue.empty? && @running
-          return nil unless @running || !@queue.empty?
+          loop do
+            @condition.wait(@mutex) while @queue.empty? && @running
+            return nil unless @running || !@queue.empty?
 
-          @pause_condition.wait(@mutex) while @paused&.call && @running
-          return nil unless @running || !@queue.empty?
+            @pause_condition.wait(@mutex) while @paused&.call && @running
+            return nil unless @running || !@queue.empty?
 
-          @stats[:in_flight] += 1
-          @queue.shift
+            # Another worker may have taken the last task while we waited.
+            next if @queue.empty?
+
+            @stats[:in_flight] += 1
+            return dequeue
+          end
+        end
+      end
+
+      # Remove and return the highest-priority pending entry. Ties are broken by
+      # insertion order (FIFO), so equal-priority tasks keep their arrival order.
+      def dequeue
+        best = 0
+        index = 1
+        while index < @queue.size
+          best = index if @queue[index].priority > @queue[best].priority
+          index += 1
         end
+        @queue.delete_at(best)
       end
 
-      def execute(task)
-        result = task.call
+      def execute(entry)
+        result = entry.callable.call
         record_completion(result)
       rescue StandardError => e
-        record_failure(e, task)
+        handle_failure(entry, e)
       end
 
       def record_completion(result)
@@ -72,15 +92,62 @@ module Philiprehberger
           @stats[:completed] += 1
           @stats[:in_flight] -= 1
         end
-        @complete_handler&.call(result)
+        invoke_complete(result)
+      end
+
+      def handle_failure(entry, error)
+        entry.attempts += 1
+        attempt = entry.attempts
+        invoke_error(error, entry.callable, attempt)
+
+        if attempt <= @max_retries
+          requeue(entry, attempt)
+        else
+          record_failure
+        end
+      end
+
+      def requeue(entry, attempt)
+        delay = backoff_delay(attempt)
+        sleep(delay) if delay.positive?
+        @mutex.synchronize do
+          @stats[:in_flight] -= 1
+          @stats[:retried] += 1
+          @queue << entry
+          @condition.signal
+        end
       end
 
-      def record_failure(error, task)
+      def record_failure
         @mutex.synchronize do
           @stats[:failed] += 1
           @stats[:in_flight] -= 1
         end
-        @error_handler&.call(error, task)
+      end
+
+      def backoff_delay(attempt)
+        case @retry_backoff
+        when :fixed then @retry_base_delay
+        when :exponential then @retry_base_delay * (2**(attempt - 1))
+        else 0
+        end
+      end
+
+      # User callbacks run outside the stats-accounting path and are each
+      # isolated in their own rescue, so a raising callback can neither corrupt
+      # the counters nor unwind the worker thread.
+      def invoke_complete(result)
+        handler = @complete_handler.call
+        handler&.call(result)
+      rescue StandardError
+        nil
+      end
+
+      def invoke_error(error, task, attempt)
+        handler = @error_handler.call
+        handler&.call(error, task, attempt)
+      rescue StandardError
+        nil
       end
     end
   end

data/lib/philiprehberger/task_queue.rb

@@ -5,6 +5,13 @@ require_relative 'task_queue/queue'
 
 module Philiprehberger
   module TaskQueue
+    # Base error class for all TaskQueue-specific errors.
+    class Error < StandardError; end
+
+    # Raised by {Queue#push} when a bounded queue already holds +max_size+
+    # pending tasks.
+    class QueueFullError < Error; end
+
     # Convenience constructor.
     #
     # @param options [Hash] forwarded to {Queue#initialize}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-task_queue
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight, zero-dependency, thread-safe in-process async job queue
   with configurable concurrency for Ruby applications.