philiprehberger-task_queue 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5017b6c1de6e4dfabd256db6ce882673c7c6feb06b9f77d379120f73ca488332
-  data.tar.gz: 62178c519c689ec28af19af6bbb2fa5bf5e54095bcb9cb22da0ceb5ffc413d58
+  metadata.gz: 3b052683a824db4cfaab12c8216cb66a99d40580d085ae630a3dfda88879b82d
+  data.tar.gz: de60b9e402664d5688461aa1e5659a3a686646de142ce2123728c61f5da7ff35
 SHA512:
-  metadata.gz: 82445514d31e2af3423bcb480bb14c0dfb20a410bdf745137f2f646c6412e791bec548bbdd46e32bb52d238eb6931b3812fdb7137f007bed061e5c93feafb713
-  data.tar.gz: 15e97b694846cf81d93183e257ae9dd8b12f4d0d43f6a71309a43f2ebefcd7dfb0624055d0a564b3052ad4e32a50b2f18c0173ea5c228fb7d9ec303da852528b
+  metadata.gz: 76e39073b3e7a723836810427fc10a7e7777831e4f5473ecd5cb4cd0a9424eb9b91c4f303d5d9bc8e33f293e8d6342d77d6e8f9f45e75a9bfeedfa6c551779e1
+  data.tar.gz: 287f3097f118a996bd0dc0b10edb86c9c904fdf62cfd8d4113b72e1808582309cae98409a520dd0d3edd39e7320f4af5b845848d318a2f0ea11d5be2d78ba2cc

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-30
+
+### Added
+- Bounded queue — `max_size:` constructor option caps the number of pending tasks (`nil`, the default, keeps the queue unbounded); the capacity check and enqueue happen atomically under the queue mutex
+- `Philiprehberger::TaskQueue::QueueFullError` (subclass of `Error`) raised by `push`/`<<` when a bounded queue is full
+- `Queue#full?` — whether the pending task count has reached `max_size` (always `false` when unbounded)
+- `Queue#max_size` — reader for the configured limit
+
+### Changed
+- `.gitignore` aligned with the gem guide template
+- CI workflow aligned with the gem guide template, publishing via a RubyGems credentials file
+- Feature request issue template now includes a proposed-API code placeholder
+
 ## [0.8.0] - 2026-07-15
 
 ### Added

data/README.md

@@ -200,6 +200,23 @@ queue.drain(timeout: 5)
 # low
 ```
 
+### Bounded queue
+
+Pass `max_size:` to cap the number of pending (not yet started) tasks. Once the limit is reached, `push` and `<<` raise `Philiprehberger::TaskQueue::QueueFullError` (a subclass of `Philiprehberger::TaskQueue::Error`) instead of growing without bound. The capacity check and the enqueue happen atomically, so concurrent producers can never overfill the queue. Tasks requeued for a retry are not counted against the limit. The default, `nil`, leaves the queue unbounded.
+
+```ruby
+queue = Philiprehberger::TaskQueue.new(concurrency: 2, max_size: 100)
+puts queue.max_size  # => 100
+
+begin
+  queue.push { process(job) }
+rescue Philiprehberger::TaskQueue::QueueFullError
+  # apply backpressure: drop, retry later, or slow the producer
+end
+
+puts queue.full?  # => true once 100 tasks are pending
+```
+
 ### FIFO ordering guarantees
 
 Tasks are stored in an internal array and dequeued in priority-then-FIFO order. With the default priority of `0`, ordering is pure FIFO. When `concurrency` is `1`, equal-priority tasks execute strictly in the order they were pushed. With higher concurrency, dequeue order is still priority-then-FIFO but tasks may complete out of order depending on individual execution time.
@@ -248,9 +265,9 @@ queue.shutdown(timeout: 5)
 
 | Method | Parameters | Returns | Description |
 |---|---|---|---|
-| `.new(concurrency:, max_retries:, retry_backoff:, retry_base_delay:)` | `concurrency` — max worker threads (Integer, default `4`); `max_retries` — retries before a task counts as failed (Integer, default `0`); `retry_backoff` — `:none`/`:fixed`/`:exponential` (default `:none`); `retry_base_delay` — base delay in seconds (Numeric, default `0.1`) | `Queue` | Create a new queue; raises `ArgumentError` on a negative `max_retries` or unknown `retry_backoff` |
-| `#push(&block)` | `priority` — dequeue priority, higher runs first (Integer, default `0`); `&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 |
+| `.new(concurrency:, max_retries:, retry_backoff:, retry_base_delay:, max_size:)` | `concurrency` — max worker threads (Integer, default `4`); `max_retries` — retries before a task counts as failed (Integer, default `0`); `retry_backoff` — `:none`/`:fixed`/`:exponential` (default `:none`); `retry_base_delay` — base delay in seconds (Numeric, default `0.1`); `max_size` — max pending tasks (Integer or `nil`, default `nil` for unbounded) | `Queue` | Create a new queue; raises `ArgumentError` on a negative `max_retries`, unknown `retry_backoff`, or a `max_size` that is not a positive Integer |
+| `#push(&block)` | `priority` — dequeue priority, higher runs first (Integer, default `0`); `&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, raises `QueueFullError` if the queue holds `max_size` pending tasks |
+| `#<<(callable)` | `callable` — any object responding to `#call` | `self` | Alias for `#push`; convenient for lambdas and procs; raises `QueueFullError` when full |
 | `#size` | _(none)_ | `Integer` | Number of pending (not yet started) tasks |
 | `#empty?` | _(none)_ | `Boolean` | Whether there are no pending tasks waiting to be started |
 | `#busy?` | _(none)_ | `Boolean` | Whether the queue has any pending tasks or in-flight tasks |
@@ -266,6 +283,9 @@ queue.shutdown(timeout: 5)
 | `#clear` | _(none)_ | `Integer` | Remove all pending tasks and return the number cleared |
 | `#stats_reset!` | _(none)_ | `self` | Atomically zero the `completed` and `failed` counters while leaving pending, in-flight, workers, and callbacks untouched |
 | `#concurrency` | _(none)_ | `Integer` | Returns the configured maximum number of concurrent worker threads |
+| `#max_size` | _(none)_ | `Integer`, `nil` | Returns the configured pending-task limit, or `nil` when unbounded |
+| `#full?` | _(none)_ | `Boolean` | Whether the pending task count has reached `max_size`; always `false` when unbounded |
+| `QueueFullError` | _(class)_ | — | Raised by `#push`/`#<<` on a full bounded queue; subclass of `Philiprehberger::TaskQueue::Error` |
 
 ## Development
 

data/lib/philiprehberger/task_queue/queue.rb

@@ -19,6 +19,10 @@ module Philiprehberger
       # @return [Integer] the maximum number of concurrent worker threads
       attr_reader :concurrency
 
+      # @return [Integer, nil] the maximum number of pending tasks, or +nil+
+      #   when the queue is unbounded
+      attr_reader :max_size
+
       # @param concurrency [Integer] maximum number of concurrent worker threads
       # @param max_retries [Integer] how many times a failing task is requeued
       #   before it is counted as failed (default +0+, i.e. no retries)
@@ -26,10 +30,14 @@ module Philiprehberger
       #   +:none+, +:fixed+, or +:exponential+
       # @param retry_base_delay [Numeric] base delay in seconds used by the
       #   +:fixed+ and +:exponential+ backoff policies
-      # @raise [ArgumentError] if +max_retries+ is negative or +retry_backoff+
-      #   is not a recognized policy
-      def initialize(concurrency: 4, max_retries: 0, retry_backoff: :none, retry_base_delay: 0.1)
+      # @param max_size [Integer, nil] maximum number of pending (not yet
+      #   started) tasks; +nil+ (the default) leaves the queue unbounded
+      # @raise [ArgumentError] if +max_retries+ is negative, +retry_backoff+
+      #   is not a recognized policy, or +max_size+ is not a positive Integer
+      def initialize(concurrency: 4, max_retries: 0, retry_backoff: :none, retry_base_delay: 0.1, max_size: nil)
         @concurrency = concurrency
+        @max_size = max_size
+        validate_max_size!
         @max_retries = max_retries
         @retry_backoff = retry_backoff
         @retry_base_delay = retry_base_delay
@@ -166,16 +174,23 @@ module Philiprehberger
       # that share a priority run in FIFO (insertion) order. The +<<+ alias
       # always enqueues at the default priority of +0+.
       #
+      # When the queue was created with +max_size+, the capacity check and the
+      # enqueue happen atomically, so concurrent pushers can never overfill it.
+      # Tasks requeued for a retry are not subject to the limit.
+      #
       # @param callable [#call, nil] a callable object (used by +<<+)
       # @param priority [Integer] dequeue priority; higher runs first (default +0+)
       # @yield the block to execute (takes precedence over +callable+)
       # @return [self]
+      # @raise [ArgumentError] if neither a block nor a callable is given
+      # @raise [QueueFullError] if the queue already holds +max_size+ pending tasks
       def push(callable = nil, priority: 0, &block)
         task = block || callable
         raise ArgumentError, 'a block is required' unless task
 
         @mutex.synchronize do
           raise 'queue is shut down' unless @running
+          raise QueueFullError, "queue is full (max_size: #{@max_size})" if at_capacity?
 
           start_workers unless @started
           @tasks << Entry.new(task, priority, 0)
@@ -203,6 +218,15 @@ module Philiprehberger
         @mutex.synchronize { @tasks.empty? }
       end
 
+      # Whether the pending task count has reached +max_size+.
+      #
+      # Always +false+ for an unbounded queue.
+      #
+      # @return [Boolean]
+      def full?
+        @mutex.synchronize { at_capacity? }
+      end
+
       # Whether the queue has any pending tasks or any in-flight tasks.
       #
       # Convenient inverse of "idle" for callers polling without going
@@ -235,6 +259,18 @@ module Philiprehberger
 
       private
 
+      # Must be called while holding +@mutex+.
+      def at_capacity?
+        !@max_size.nil? && @tasks.size >= @max_size
+      end
+
+      def validate_max_size!
+        return if @max_size.nil?
+        return if @max_size.is_a?(Integer) && @max_size.positive?
+
+        raise ArgumentError, "max_size must be a positive Integer or nil, got #{@max_size.inspect}"
+      end
+
       def signal_shutdown
         @mutex.synchronize do
           return unless @running

data/lib/philiprehberger/task_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskQueue
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/lib/philiprehberger/task_queue.rb

@@ -8,6 +8,10 @@ module Philiprehberger
     # Base error class for all TaskQueue-specific errors.
     class Error < StandardError; end
 
+    # Raised by {Queue#push} when a bounded queue already holds +max_size+
+    # pending tasks.
+    class QueueFullError < Error; end
+
     # Convenience constructor.
     #
     # @param options [Hash] forwarded to {Queue#initialize}

metadata

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