philiprehberger-task_queue 0.2.10 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e8b37d7bad85dce1fa4281f41df74991b9e6362d6d5bf7e1cddf1dc0612f9a
-  data.tar.gz: 54a8725dea3cad2f9b8c8ec711dfa1c21522683d27d9d3bb84861d270a5b3f4a
+  metadata.gz: 6a1d028dda2118c9948cbec0cdff5f7215eeb8d76615acdeaf9a2e7b5f6c45ce
+  data.tar.gz: 94d56b9b9acb20add7a8e91dd1977f1a87a135e442dadc4c0b8acfc4eb5b5ac1
 SHA512:
-  metadata.gz: ce894a8d984f95d2161d870ada0e0aef8f394cbbbd9f204173e5133eaa52acc0d6d59492dc4b4886fbcaa7461a360b588ba2e25fef908575a2f523aae216f610
-  data.tar.gz: f945b9c98cf3e8f13572c07dd8709ca040f340a66ba64a57d2552f6c219b9f74b0ee59293ef7859d1670f268dbcf5a936198058262e8f6fb40ca028e135e8643
+  metadata.gz: 4c6f850324f487d516626884c44278bce4927b2419ce9b0036dd2d1c399b41a006c2ab0d48a3f18ef60a9ebcf00ef82fbf6a70e3bc486b78cdea4c397e9dc246
+  data.tar.gz: efb376ce60b1b9bfe43676ccefb5c0a2d03874e61d897337a6c0268555477478528583be36ab4763c5c0422b1e0fd4734db6bfa7dd738757a9e2f7616b8415f9

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-05
+
+### Added
+- `in_flight` count in `stats` hash for monitoring active task execution
+- `Queue#pause` and `Queue#resume` for temporarily suspending task consumption
+- `Queue#paused?` to check pause state
+- `Queue#clear` to discard all pending tasks
+
+## [0.3.0] - 2026-04-04
+
+### Added
+- `on_complete(&block)` callback that fires after each successful task completion with the task result
+
+## [0.2.11] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.2.10] - 2026-03-31
 
 ### Changed

data/README.md

@@ -64,12 +64,31 @@ queue.push { File.read("/nonexistent") }
 
 queue.drain(timeout: 5)
 puts queue.stats
-# => { completed: 0, failed: 2, pending: 0 }
+# => { completed: 0, failed: 2, pending: 0, in_flight: 0 }
+```
+
+### Completion callback
+
+Register a callback to run after each successful task completion. The callback receives the return value of the task.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 2)
+
+queue.on_complete do |result|
+  puts "Task finished with: #{result}"
+end
+
+queue.push { 42 }
+queue.push { { status: "ok" } }
+
+queue.drain(timeout: 5)
+# Task finished with: 42
+# Task finished with: {:status=>"ok"}
 ```
 
 ### Statistics
 
-`stats` returns a snapshot of completed, failed, and pending counts. All counters are thread-safe and updated atomically after each task finishes.
+`stats` returns a snapshot of completed, failed, pending, and in-flight counts. All counters are thread-safe and updated atomically after each task finishes.
 
 ```ruby
 queue = Philiprehberger::TaskQueue.new(concurrency: 4)
@@ -81,9 +100,44 @@ stats = queue.stats
 puts "Completed: #{stats[:completed]}"
 puts "Failed:    #{stats[:failed]}"
 puts "Pending:   #{stats[:pending]}"
+puts "In-flight: #{stats[:in_flight]}"
 # Completed: 19
 # Failed:    1
 # Pending:   0
+# In-flight: 0
+```
+
+### Pause and resume
+
+Temporarily suspend task consumption without shutting down. In-flight tasks will finish, but no new tasks are picked up until the queue is resumed.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 4)
+
+10.times { |i| queue.push { process(i) } }
+
+queue.pause
+puts queue.paused?  # => true
+
+# Tasks already in flight will complete, but pending tasks wait.
+queue.resume
+puts queue.paused?  # => false
+
+queue.shutdown(timeout: 10)
+```
+
+### Clear pending tasks
+
+Discard all pending tasks from the queue. Returns the number of tasks removed.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 2)
+
+100.times { |i| queue.push { process(i) } }
+cleared = queue.clear
+puts "Cleared #{cleared} tasks"
+
+queue.shutdown(timeout: 5)
 ```
 
 ### FIFO ordering guarantees
@@ -140,9 +194,14 @@ queue.shutdown(timeout: 5)
 | `#size` | _(none)_ | `Integer` | Number of pending (not yet started) 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: }` with Integer counts |
+| `#stats` | _(none)_ | `Hash` | Returns `{ completed:, failed:, pending:, in_flight: }` with Integer counts |
 | `#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 |
+| `#paused?` | _(none)_ | `Boolean` | Whether the queue is currently paused |
+| `#clear` | _(none)_ | `Integer` | Remove all pending tasks and return the number cleared |
 
 ## Development
 

data/lib/philiprehberger/task_queue/queue.rb

@@ -19,7 +19,10 @@ module Philiprehberger
         @workers = []
         @running = true
         @started = false
+        @paused = false
+        @pause_condition = ConditionVariable.new
         @error_handler = nil
+        @complete_handler = nil
         @stats = { completed: 0, failed: 0, in_flight: 0 }
       end
 
@@ -34,12 +37,66 @@ module Philiprehberger
         self
       end
 
+      # Register a callback invoked after each successful task completion.
+      #
+      # The callback receives the return value of the completed task.
+      #
+      # @yield [result] called on task success
+      # @return [self]
+      def on_complete(&block)
+        @mutex.synchronize { @complete_handler = block }
+        self
+      end
+
       # Return statistics about processed tasks.
       #
-      # @return [Hash{Symbol => Integer}] counts for :completed, :failed, :pending
+      # @return [Hash{Symbol => Integer}] counts for :completed, :failed, :pending, :in_flight
       def stats
         @mutex.synchronize do
-          { completed: @stats[:completed], failed: @stats[:failed], pending: @tasks.size }
+          { completed: @stats[:completed], failed: @stats[:failed], pending: @tasks.size,
+            in_flight: @stats[:in_flight] }
+        end
+      end
+
+      # Pause the queue so workers stop dequeuing new tasks.
+      #
+      # In-flight tasks will finish, but no new tasks will be picked up until
+      # +resume+ is called.
+      #
+      # @return [self]
+      def pause
+        @mutex.synchronize do
+          @paused = true
+        end
+        self
+      end
+
+      # Resume a paused queue, waking workers to continue processing.
+      #
+      # @return [self]
+      def resume
+        @mutex.synchronize do
+          @paused = false
+          @pause_condition.broadcast
+        end
+        self
+      end
+
+      # Whether the queue is currently paused.
+      #
+      # @return [Boolean]
+      def paused?
+        @mutex.synchronize { @paused }
+      end
+
+      # Remove all pending tasks from the queue.
+      #
+      # @return [Integer] number of tasks cleared
+      def clear
+        @mutex.synchronize do
+          count = @tasks.size
+          @tasks.clear
+          count
         end
       end
 
@@ -116,8 +173,10 @@ module Philiprehberger
           return unless @running
 
           @running = false
+          @paused = false
           @workers.each(&:stop)
           @condition.broadcast
+          @pause_condition.broadcast
         end
       end
 
@@ -133,7 +192,9 @@ module Philiprehberger
         @concurrency.times do
           @workers << Worker.new(
             @tasks, @mutex, @condition,
-            context: { stats: @stats, error_handler: @error_handler, drain_condition: @drain_condition }
+            context: { stats: @stats, error_handler: @error_handler,
+                       complete_handler: @complete_handler, drain_condition: @drain_condition,
+                       paused: -> { @paused }, pause_condition: @pause_condition }
           )
         end
         @started = true

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = '0.2.10'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/task_queue/worker.rb

@@ -12,7 +12,10 @@ module Philiprehberger
         @condition = condition
         @stats = context[:stats]
         @error_handler = context[:error_handler]
+        @complete_handler = context[:complete_handler]
         @drain_condition = context[:drain_condition]
+        @paused = context[:paused]
+        @pause_condition = context[:pause_condition]
         @running = true
         @thread = Thread.new { run }
       end
@@ -42,23 +45,27 @@ module Philiprehberger
           @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?
+
           @stats[:in_flight] += 1
           @queue.shift
         end
       end
 
       def execute(task)
-        task.call
-        record_completion
+        result = task.call
+        record_completion(result)
       rescue StandardError => e
         record_failure(e, task)
       end
 
-      def record_completion
+      def record_completion(result)
         @mutex.synchronize do
           @stats[:completed] += 1
           @stats[:in_flight] -= 1
         end
+        @complete_handler&.call(result)
       end
 
       def record_failure(error, task)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-task_queue
 version: !ruby/object:Gem::Version
-  version: 0.2.10
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-06 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight, zero-dependency, thread-safe in-process async job queue
   with configurable concurrency for Ruby applications.
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/task_queue/queue.rb
 - lib/philiprehberger/task_queue/version.rb
 - lib/philiprehberger/task_queue/worker.rb
-homepage: https://github.com/philiprehberger/rb-task-queue
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-task_queue
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-task-queue
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-task_queue
   source_code_uri: https://github.com/philiprehberger/rb-task-queue
   changelog_uri: https://github.com/philiprehberger/rb-task-queue/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-task-queue/issues