philiprehberger-task_queue 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0234cce054f1fc8e8923a25a414198c1863bfa035f9e9881ab38b48c484460d4
-  data.tar.gz: e93358c9bec5ab194464dbdec66cdbf9ff414970d21e4539b578c9f01effd6ff
+  metadata.gz: e3cd82560d64b9754fc30641e980afce535bfeabbbc0fff39ecdd0a2032734b5
+  data.tar.gz: ef9c65fd500093f530cb0cf0f71e3b17d934682b8dafa881baf471354abcad2b
 SHA512:
-  metadata.gz: 045c07963ff8f40a847eb375b2b04830f092fe5d0355fc3cf0db59865328083141f6859b2c18abbe46d844c8cd4af3b25143cfa79f4b01fabb28fc7e3acf0a2f
-  data.tar.gz: f6d1b9a18e472fc17b717b65a076918319e83445d30f668df121833207fe7b70345d6e1b0264951b95e3f39f79643c4d6f8e3d0e575ee918175dc152cf2d9470
+  metadata.gz: 66bbada6cc0dd9c204d673bfa097943320ec7f12ba8be66b15acdaf9670d9f1fb9052de5d88b2255bb09b1c4eb155668799cde871769a70b45ff64e0c389f230
+  data.tar.gz: '019c01d08b8e2c72b4a987d98de7e2bd58d5c6c0a5fd5dd24c9e8de7ff70a1485e87b77f1368f433e38e80c31e479c632af72fdd76f0b1d2d62a17ebe2bd90e9'

data/CHANGELOG.md

@@ -1,7 +1,22 @@
 # Changelog
 
+## 0.2.1
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+- Add Development section to README
+- Add Requirements section to README
+
 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

@@ -2,9 +2,14 @@
 
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-task_queue.svg)](https://rubygems.org/gems/philiprehberger-task_queue)
 [![CI](https://github.com/philiprehberger/rb-task-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-task-queue/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-task-queue)](LICENSE)
 
 In-process async job queue with concurrency control for Ruby.
 
+## Requirements
+
+- Ruby >= 3.1
+
 ## Installation
 
 Add to your Gemfile:
@@ -42,6 +47,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 +84,18 @@ 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) |
+
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
 
 ## 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.1"
   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.1
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-10 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight, zero-dependency, thread-safe in-process async job queue
   with configurable concurrency for Ruby applications.