philiprehberger-task_queue 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3cd82560d64b9754fc30641e980afce535bfeabbbc0fff39ecdd0a2032734b5
-  data.tar.gz: ef9c65fd500093f530cb0cf0f71e3b17d934682b8dafa881baf471354abcad2b
+  metadata.gz: '088f95205b874279733ad703f517d81cb5f7694e7fc9ed2248c481869384e423'
+  data.tar.gz: 9d3940ad0849cd7ecbeaa7f5cb7afa3c1a19e49d95ce3ca7cd4ce2b23afd4679
 SHA512:
-  metadata.gz: 66bbada6cc0dd9c204d673bfa097943320ec7f12ba8be66b15acdaf9670d9f1fb9052de5d88b2255bb09b1c4eb155668799cde871769a70b45ff64e0c389f230
-  data.tar.gz: '019c01d08b8e2c72b4a987d98de7e2bd58d5c6c0a5fd5dd24c9e8de7ff70a1485e87b77f1368f433e38e80c31e479c632af72fdd76f0b1d2d62a17ebe2bd90e9'
+  metadata.gz: d8043a08aebd40789f3da64d6d88aa65342dee25cbc70aa4cadaae94400a60ba23158fcab58eb822916d04af4ce596645f6b018b57df16b77fef57a7be8b5da7
+  data.tar.gz: f4b653d153a61fb6f8126969aa0763e8f0d22c4694dffcb352d82120b53e81a85de924b7ee1b0fc6a1983a7cf60ad0b4035a83513c5344f561dd51b6847ddd65

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.2.3] - 2026-03-20
+
+### Changed
+- Expand README with detailed API documentation and usage examples
+
+## 0.2.2
+
+- Fix RuboCop Style/StringLiterals violations in gemspec
+
 ## 0.2.1
 
 - Add License badge to README

data/README.md

@@ -20,7 +20,7 @@ gem "philiprehberger-task_queue"
 
 Or install directly:
 
-```sh
+```bash
 gem install philiprehberger-task_queue
 ```
 
@@ -49,44 +49,100 @@ queue << -> { puts "Hello from a task!" }
 
 ### Error handling
 
+Register a callback to handle exceptions raised inside tasks. The callback receives the exception and the original task (callable) that failed. Unhandled errors are silently swallowed when no callback is registered.
+
 ```ruby
-queue = Philiprehberger::TaskQueue.new
+queue = Philiprehberger::TaskQueue.new(concurrency: 2)
 
 queue.on_error do |exception, task|
-  puts "Task failed: #{exception.message}"
+  warn "[TaskQueue] #{exception.class}: #{exception.message}"
+  warn exception.backtrace.first(5).join("\n")
 end
 
-queue.push { raise "oops" }
+queue.push { Integer("not_a_number") }
+queue.push { File.read("/nonexistent") }
+
+queue.drain(timeout: 5)
+puts queue.stats
+# => { completed: 0, failed: 2, pending: 0 }
 ```
 
 ### Statistics
 
+`stats` returns a snapshot of completed, failed, and pending counts. All counters are thread-safe and updated atomically after each task finishes.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 4)
+
+20.times { |i| queue.push { sleep(0.01); raise "boom" if i == 5 } }
+queue.drain(timeout: 10)
+
+stats = queue.stats
+puts "Completed: #{stats[:completed]}"
+puts "Failed:    #{stats[:failed]}"
+puts "Pending:   #{stats[:pending]}"
+# Completed: 19
+# Failed:    1
+# Pending:   0
+```
+
+### 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.
+
+```ruby
+results = Queue.new  # stdlib thread-safe queue for collecting output
+queue = Philiprehberger::TaskQueue.new(concurrency: 1)
+
+5.times { |i| queue.push { results << i } }
+queue.drain(timeout: 5)
+
+puts results.size.times.map { results.pop }
+# => [0, 1, 2, 3, 4]
+```
+
+### Graceful shutdown
+
+`shutdown` signals all worker threads to stop accepting new tasks, lets in-flight tasks finish, then drains any remaining enqueued tasks before joining threads. The `timeout` parameter caps total wait time; workers that exceed the deadline are abandoned.
+
 ```ruby
-queue.stats
-# => { completed: 5, failed: 1, pending: 2 }
+queue = Philiprehberger::TaskQueue.new(concurrency: 4)
+
+100.times { |i| queue.push { sleep(0.05) } }
+
+queue.shutdown(timeout: 10)
+puts queue.running?  # => false
+# queue.push { ... } would now raise "queue is shut down"
 ```
 
 ### Draining
 
+`drain` blocks the calling thread until all pending and in-flight tasks finish, but keeps the queue running so new tasks can still be pushed afterwards.
+
 ```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 4)
+
 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
+puts queue.running?        # => true — still accepting new tasks
+
+queue.push { process(:extra) }
+queue.shutdown(timeout: 5)
 ```
 
 ## API
 
-| Method | Description |
-|---|---|
-| `.new(concurrency: 4)` | Create a new queue with the given max worker count |
-| `#push(&block)` | Enqueue a task (block) for async execution |
-| `#<< (&block)` | Alias for `#push` |
-| `#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) |
+| 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 |
+| `#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_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 |
+| `#drain(timeout:)` | `timeout` — seconds to wait (Numeric, default `30`) | `nil` | Block until all pending and in-flight tasks complete without shutting down |
 
 
 ## Development
@@ -99,4 +155,4 @@ bundle exec rubocop
 
 ## License
 
-[MIT](LICENSE)
+MIT

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = "0.2.1"
+    VERSION = "0.2.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-task_queue
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-20 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight, zero-dependency, thread-safe in-process async job queue
   with configurable concurrency for Ruby applications.
@@ -32,6 +32,7 @@ metadata:
   homepage_uri: https://github.com/philiprehberger/rb-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
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -41,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="