philiprehberger-task_queue 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2524cd95e75d5fef01076f0bb4895a3d3aceeed233a2b68eabc596c7a731ebfa
-  data.tar.gz: 7df5392a5796de69bf086cc47484cb5481f1e131099d3994062e5e3c308d4b06
+  metadata.gz: 829177cbd19c6b70ce4e32d03b824d80e0757d833f0f222ed7336156c2491975
+  data.tar.gz: 28a1317702057efb8effe2053a5c1b531bc7c13aff26dae835217a5da82d10b8
 SHA512:
-  metadata.gz: 60adcdcd0b47caba95f1eb03c8be5e340e62aaf9fe2d9ed5ac85a702e1ac89d95e65c810a245bd5d9d0ddbd7fcbc68c493c46497a53298fe7721f90240107582
-  data.tar.gz: 1657f7b9c9b358a58ca2aae35896374e5193a295e753d47054f662233237fef68148175d8e7e40a050bf102fb68f32cf790827f79f84b9450fea7d0be75ab8ac
+  metadata.gz: 9e5ce7cda54494f0756e05a5bd56dbf722553f34890c5b9868b522ad70e6ae587e01afee2ae035b2a61bc7baec4b6d4dd34dde2549d1c93757b08ca88f630932
+  data.tar.gz: 8e380685e1a026d5344a754e27c5c74989f17509492e75683ff69ad2ccd2e457707fc272814e228da5c05bfe3cf8c50b4c32599270bb9eadbeb3025611d113ad

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-04-07
+
+### Added
+- `Queue#empty?` to check whether any pending tasks are waiting
+
+## [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

data/README.md

@@ -64,7 +64,7 @@ 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
@@ -88,7 +88,7 @@ queue.drain(timeout: 5)
 
 ### 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)
@@ -100,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
@@ -157,12 +192,17 @@ queue.shutdown(timeout: 5)
 | `#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 |
 | `#size` | _(none)_ | `Integer` | Number of pending (not yet started) tasks |
+| `#empty?` | _(none)_ | `Boolean` | Whether there are no pending tasks waiting to be started |
 | `#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,6 +19,8 @@ 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 }
@@ -48,10 +50,53 @@ module Philiprehberger
 
       # 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
 
@@ -101,6 +146,15 @@ module Philiprehberger
         @mutex.synchronize { @tasks.size }
       end
 
+      # Whether there are no pending tasks waiting to be started.
+      #
+      # In-flight tasks are not considered; use +drain+ to wait for them.
+      #
+      # @return [Boolean]
+      def empty?
+        @mutex.synchronize { @tasks.empty? }
+      end
+
       # Whether the queue is accepting new tasks.
       #
       # @return [Boolean]
@@ -128,8 +182,10 @@ module Philiprehberger
           return unless @running
 
           @running = false
+          @paused = false
           @workers.each(&:stop)
           @condition.broadcast
+          @pause_condition.broadcast
         end
       end
 
@@ -146,7 +202,8 @@ module Philiprehberger
           @workers << Worker.new(
             @tasks, @mutex, @condition,
             context: { stats: @stats, error_handler: @error_handler,
-                       complete_handler: @complete_handler, drain_condition: @drain_condition }
+                       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.3.0'
+    VERSION = '0.4.1'
   end
 end

data/lib/philiprehberger/task_queue/worker.rb

@@ -14,6 +14,8 @@ module Philiprehberger
         @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
@@ -43,6 +45,9 @@ 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

metadata

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