philiprehberger-task_queue 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0234cce054f1fc8e8923a25a414198c1863bfa035f9e9881ab38b48c484460d4
-  data.tar.gz: e93358c9bec5ab194464dbdec66cdbf9ff414970d21e4539b578c9f01effd6ff
+  metadata.gz: 34263f9a3370dc191d5f7f2ec9744e9c92b9e50b80e305e9916d097a070d6b8b
+  data.tar.gz: 230bf370d52a1b02eb928ac0a53b3f0abbb519cd5396903c622f831691f6128e
 SHA512:
-  metadata.gz: 045c07963ff8f40a847eb375b2b04830f092fe5d0355fc3cf0db59865328083141f6859b2c18abbe46d844c8cd4af3b25143cfa79f4b01fabb28fc7e3acf0a2f
-  data.tar.gz: f6d1b9a18e472fc17b717b65a076918319e83445d30f668df121833207fe7b70345d6e1b0264951b95e3f39f79643c4d6f8e3d0e575ee918175dc152cf2d9470
+  metadata.gz: f96333a34f87690f6ada381f4eec29e419aaf1a72aaf2237f7fd31d3af252aa6d11f2851613afcf56040f4c79bd50d12d397adf949b7eac2a01ee2d10f15b886
+  data.tar.gz: a607205711f5647aceb92c6eec0c19103681a7c074ddfd1de7b3dbda30956f356403770bb36721c9ea5a2171d9282a84117f239c66b9a99b8c1a47a73875119b

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-03-12
+
+### Added
+
+- `on_error` callback for handling task failures
+- `stats` method returning completed, failed, and pending task counts
+- `drain(timeout:)` method to wait for task completion without shutting down
+
 ## [0.1.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -42,6 +42,33 @@ queue.shutdown(timeout: 30)
 queue << -> { puts "Hello from a task!" }
 ```
 
+### Error handling
+
+```ruby
+queue = Philiprehberger::TaskQueue.new
+
+queue.on_error do |exception, task|
+  puts "Task failed: #{exception.message}"
+end
+
+queue.push { raise "oops" }
+```
+
+### Statistics
+
+```ruby
+queue.stats
+# => { completed: 5, failed: 1, pending: 2 }
+```
+
+### Draining
+
+```ruby
+10.times { |i| queue.push { process(i) } }
+queue.drain(timeout: 10)  # waits for all tasks to finish
+# queue is still running and accepting new tasks
+```
+
 ## API
 
 | Method | Description |
@@ -52,6 +79,9 @@ queue << -> { puts "Hello from a task!" }
 | `#size` | Number of pending (not yet started) tasks |
 | `#running?` | Whether the queue is accepting new tasks |
 | `#shutdown(timeout: 30)` | Gracefully stop all workers, waiting up to `timeout` seconds |
+| `#on_error(&block)` | Register error callback for failed tasks |
+| `#stats` | Returns hash with `:completed`, `:failed`, `:pending` counts |
+| `#drain(timeout: 30)` | Block until all pending tasks complete (without shutdown) |
 
 ## License
 

data/lib/philiprehberger/task_queue/queue.rb

@@ -15,9 +15,49 @@ module Philiprehberger
         @tasks = []
         @mutex = Mutex.new
         @condition = ConditionVariable.new
+        @drain_condition = ConditionVariable.new
         @workers = []
         @running = true
         @started = false
+        @error_handler = nil
+        @stats = { completed: 0, failed: 0, in_flight: 0 }
+      end
+
+      # Register a callback invoked when a task raises an exception.
+      #
+      # The callback receives the exception and the task that raised it.
+      #
+      # @yield [exception, task] called on task failure
+      # @return [self]
+      def on_error(&block)
+        @mutex.synchronize { @error_handler = block }
+        self
+      end
+
+      # Return statistics about processed tasks.
+      #
+      # @return [Hash{Symbol => Integer}] counts for :completed, :failed, :pending
+      def stats
+        @mutex.synchronize do
+          { completed: @stats[:completed], failed: @stats[:failed], pending: @tasks.size }
+        end
+      end
+
+      # Block until all pending tasks are complete without shutting down.
+      #
+      # @param timeout [Numeric] seconds to wait before returning
+      # @return [void]
+      def drain(timeout: 30)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @mutex.synchronize do
+          while !@tasks.empty? || @stats[:in_flight].positive?
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+
+            @drain_condition.wait(@mutex, remaining)
+          end
+        end
+        nil
       end
 
       # Enqueue a task to be processed asynchronously.
@@ -91,7 +131,10 @@ module Philiprehberger
 
       def start_workers
         @concurrency.times do
-          @workers << Worker.new(@tasks, @mutex, @condition)
+          @workers << Worker.new(
+            @tasks, @mutex, @condition,
+            context: { stats: @stats, error_handler: @error_handler, drain_condition: @drain_condition }
+          )
         end
         @started = true
       end

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/philiprehberger/task_queue/worker.rb

@@ -6,10 +6,13 @@ module Philiprehberger
     class Worker
       attr_reader :thread
 
-      def initialize(queue, mutex, condition)
+      def initialize(queue, mutex, condition, context:)
         @queue = queue
         @mutex = mutex
         @condition = condition
+        @stats = context[:stats]
+        @error_handler = context[:error_handler]
+        @drain_condition = context[:drain_condition]
         @running = true
         @thread = Thread.new { run }
       end
@@ -30,6 +33,7 @@ module Philiprehberger
           break unless task
 
           execute(task)
+          @mutex.synchronize { @drain_condition.broadcast }
         end
       end
 
@@ -38,14 +42,31 @@ module Philiprehberger
           @condition.wait(@mutex) while @queue.empty? && @running
           return nil unless @running || !@queue.empty?
 
+          @stats[:in_flight] += 1
           @queue.shift
         end
       end
 
       def execute(task)
         task.call
-      rescue StandardError
-        # Swallow exceptions to keep the worker alive.
+        record_completion
+      rescue StandardError => e
+        record_failure(e, task)
+      end
+
+      def record_completion
+        @mutex.synchronize do
+          @stats[:completed] += 1
+          @stats[:in_flight] -= 1
+        end
+      end
+
+      def record_failure(error, task)
+        @mutex.synchronize do
+          @stats[:failed] += 1
+          @stats[:in_flight] -= 1
+        end
+        @error_handler&.call(error, task)
       end
     end
   end

metadata

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