philiprehberger-task_queue 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbb261ee851c5f9064db0d79ecf1684ec7134b9df747437279afc27411ac7d40
-  data.tar.gz: 3b9e9c93835a2e1406d8ac2a153a912c0ce087351e35f9c2c49faf52622e2003
+  metadata.gz: '088f95205b874279733ad703f517d81cb5f7694e7fc9ed2248c481869384e423'
+  data.tar.gz: 9d3940ad0849cd7ecbeaa7f5cb7afa3c1a19e49d95ce3ca7cd4ce2b23afd4679
 SHA512:
-  metadata.gz: b4050c1c34922d3f4c0d155152c5f29e2e612104a56e8af82bbcbbb0bfd7a1a7ba4ab0e6963224e7c79a9aace383bdefa33147eb2e25f8c299d7f10993d10059
-  data.tar.gz: e94f4f029b34ea77cbd7d7afcf5031cdfdee1935b185e65ae328d3ceae2cb65788bc14736f5a3cbb39c7e479519045b81e6bc753f2e91eaeeab91c0decfe5df3
+  metadata.gz: d8043a08aebd40789f3da64d6d88aa65342dee25cbc70aa4cadaae94400a60ba23158fcab58eb822916d04af4ce596645f6b018b57df16b77fef57a7be8b5da7
+  data.tar.gz: f4b653d153a61fb6f8126969aa0763e8f0d22c4694dffcb352d82120b53e81a85de924b7ee1b0fc6a1983a7cf60ad0b4035a83513c5344f561dd51b6847ddd65

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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

data/README.md

@@ -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.stats
-# => { completed: 5, failed: 1, pending: 2 }
+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 = 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

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = "0.2.2"
+    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.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-19 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.