philiprehberger-queue_stack 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dba395bc3ee76baae4cdbbbb100fc91103049635c386e02fe5ac3ae118e9997a
-  data.tar.gz: 921a8e4241383d570d951e154b19e7abcce5cdb682d93b42888d36c9804871a2
+  metadata.gz: dbcea69e9c62dd59232e450824070497d480a78224b1f04894664832e1e5c019
+  data.tar.gz: b9c91c0ff26af13c51ce30667c5eee0ad0bedce13c807164ddcd273e147d2513
 SHA512:
-  metadata.gz: 30320f35b2ae5d2e01221091e203c31cc799ec5d6a1ff279a0201a04dd9c038f254ad8319d1e4f8cf3a50e1e292e2522a813e8330383f2f49ce99b86d5704b1c
-  data.tar.gz: 2ddd79499fa0b97b99fcb45c5c941984c1f8b3ddeee25cc4edeed317b9317509d9ade981940ca685266770db6dc3d472b11e3fdb8610b45731abd44f7f3a284e
+  metadata.gz: 8db38faf1a4c7090ee405fededf09f3f939fd11217d46d0220641ff12b3ef286ca915c845b98847e3c22e7f4e0a4ab55d5c71a14d18db9af7b99859e24b454ff
+  data.tar.gz: 748285864c78717094e6f34a8c0cf9b4fc2e9c7bde05c17d14b8bd60821790bca8687b9076e2f4d24b9f5bb3cab3a23c131e1dd87cd64f7a4b6da1b30985df38

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-29
+
+### Added
+- `Queue#enqueue_all(items)` and `Stack#push_all(items)` — enqueue/push an array of items under a single mutex acquisition; each item respects capacity and `ClosedError` semantics
+- `Queue#dequeue_batch(max)` and `Stack#pop_batch(max)` — remove and return up to `max` items in one synchronized step; non-blocking; signals waiting producers
+
+## [0.6.0] - 2026-04-27
+
+### Added
+- `Queue#capacity`, `Queue#remaining_capacity`, `Stack#capacity`, `Stack#remaining_capacity` — capacity introspection. `capacity` returns the configured limit (or `nil` for unlimited); `remaining_capacity` returns the number of additional items that can still be accepted (or `nil` for unlimited, `0` when full). Mutex-synchronized for consistent reads.
+
 ## [0.5.0] - 2026-04-16
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-queue_stack.svg)](https://rubygems.org/gems/philiprehberger-queue_stack)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-queue-stack)](https://github.com/philiprehberger/rb-queue-stack/commits/main)
 
+![philiprehberger-queue_stack](https://raw.githubusercontent.com/philiprehberger/rb-queue-stack/main/package-card.webp)
+
 Thread-safe Queue and Stack with capacity limits and blocking operations
 
 ## Requirements
@@ -159,6 +161,37 @@ q.full?   # => true
 # enqueue blocks until space is available
 ```
 
+### Capacity
+
+Read the configured capacity and the number of additional items that can be
+accepted. Both return `nil` for unbounded containers; `remaining_capacity`
+returns `0` when full. Useful for sizing batches or backpressure decisions.
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new(capacity: 100)
+q.capacity            # => 100
+q.remaining_capacity  # => 100
+50.times { |i| q.enqueue(i) }
+q.remaining_capacity  # => 50
+
+batch_size = [items.length, q.remaining_capacity].min
+```
+
+### Batch Insertion and Draining
+
+`enqueue_all` / `push_all` insert an array of items under a single mutex acquisition. `dequeue_batch` / `pop_batch` remove up to `max` items at once and signal waiting producers. All four respect capacity and `ClosedError` semantics.
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue_all(%w[a b c d])
+q.dequeue_batch(2)  # => ["a", "b"]
+q.dequeue_batch(99) # => ["c", "d"]   (clamped to available)
+
+s = Philiprehberger::QueueStack::Stack.new
+s.push_all(%w[a b c])
+s.pop_batch(2)      # => ["c", "b"]   (LIFO: top first)
+```
+
 ## API
 
 ### `Queue`
@@ -167,8 +200,10 @@ q.full?   # => true
 |--------|-------------|
 | `.new(capacity:)` | Create a queue with optional capacity limit |
 | `#enqueue(item)` | Add item to back (blocks if full) |
+| `#enqueue_all(items)` | Enqueue an array of items in FIFO order (blocks per-element if full) |
 | `#try_enqueue(item, timeout: nil)` | Non-blocking enqueue, returns true/false (waits up to timeout if given) |
 | `#dequeue` | Remove and return front item (blocks if empty) |
+| `#dequeue_batch(max)` | Remove and return up to `max` items in FIFO order (non-blocking) |
 | `#dequeue_if { \|item\| ... }` | Remove and return the front item only if the block is truthy (non-blocking) |
 | `#try_dequeue(timeout:)` | Dequeue with timeout, returns nil on timeout |
 | `#clear` | Remove all items without returning them |
@@ -182,6 +217,8 @@ q.full?   # => true
 | `#size` | Number of items |
 | `#empty?` | Whether the queue is empty |
 | `#full?` | Whether the queue is at capacity |
+| `#capacity` | Configured capacity, or `nil` for an unlimited queue |
+| `#remaining_capacity` | Items the queue can still accept (`nil` for unlimited, `0` when full) |
 
 ### `Stack`
 
@@ -189,8 +226,10 @@ q.full?   # => true
 |--------|-------------|
 | `.new(capacity:)` | Create a stack with optional capacity limit |
 | `#push(item)` | Push item on top (blocks if full) |
+| `#push_all(items)` | Push an array of items in order; last becomes the top (blocks per-element if full) |
 | `#try_push(item, timeout: nil)` | Non-blocking push, returns true/false (waits up to timeout if given) |
 | `#pop` | Remove and return top item (blocks if empty) |
+| `#pop_batch(max)` | Pop up to `max` items, top first (non-blocking) |
 | `#pop_if { \|item\| ... }` | Remove and return the top item only if the block is truthy (non-blocking) |
 | `#try_pop(timeout:)` | Pop with timeout, returns nil on timeout |
 | `#clear` | Remove all items without returning them |
@@ -203,6 +242,8 @@ q.full?   # => true
 | `#size` | Number of items |
 | `#empty?` | Whether the stack is empty |
 | `#full?` | Whether the stack is at capacity |
+| `#capacity` | Configured capacity, or `nil` for an unlimited stack |
+| `#remaining_capacity` | Items the stack can still accept (`nil` for unlimited, `0` when full) |
 
 ## Development
 

data/lib/philiprehberger/queue_stack/queue.rb

@@ -225,6 +225,68 @@ module Philiprehberger
       def full?
         @mutex.synchronize { @capacity ? @items.length >= @capacity : false }
       end
+
+      # The configured capacity, or +nil+ for an unlimited queue.
+      #
+      # @return [Integer, nil]
+      def capacity
+        @mutex.synchronize { @capacity }
+      end
+
+      # Number of additional items the queue can accept before it is full.
+      #
+      # Returns +nil+ for unlimited queues. For bounded queues returns
+      # +capacity - size+, clamped to a minimum of 0.
+      #
+      # @return [Integer, nil]
+      def remaining_capacity
+        @mutex.synchronize do
+          next nil unless @capacity
+
+          [@capacity - @items.length, 0].max
+        end
+      end
+
+      # Enqueue many items in FIFO order. Each item is enqueued under the
+      # same Mutex acquisition; the call blocks while waiting for capacity
+      # exactly as +enqueue+ would for the individual elements that cannot
+      # fit immediately.
+      #
+      # @param items [Array] the items to enqueue, in order
+      # @return [void]
+      # @raise [ClosedError] if the queue has been closed
+      def enqueue_all(items)
+        @mutex.synchronize do
+          raise ClosedError, 'cannot enqueue on a closed queue' if @closed
+
+          items.each do |item|
+            @not_full.wait(@mutex) while @capacity && @items.length >= @capacity
+            raise ClosedError, 'cannot enqueue on a closed queue' if @closed
+
+            @items.push(item)
+            @not_empty.signal
+          end
+        end
+      end
+
+      # Remove and return up to +max+ items from the front of the queue.
+      # Non-blocking: returns an empty array if the queue is empty.
+      #
+      # @param max [Integer] maximum number of items to remove (must be a non-negative Integer)
+      # @return [Array] up to +max+ items in FIFO order
+      # @raise [ArgumentError] if +max+ is not a non-negative Integer
+      def dequeue_batch(max)
+        raise ArgumentError, 'max must be a non-negative Integer' unless max.is_a?(Integer) && max >= 0
+
+        @mutex.synchronize do
+          count = [max, @items.length].min
+          next [] if count.zero?
+
+          batch = @items.shift(count)
+          @not_full.broadcast
+          batch
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/queue_stack/stack.rb

@@ -213,6 +213,67 @@ module Philiprehberger
       def full?
         @mutex.synchronize { @capacity ? @items.length >= @capacity : false }
       end
+
+      # The configured capacity, or +nil+ for an unlimited stack.
+      #
+      # @return [Integer, nil]
+      def capacity
+        @mutex.synchronize { @capacity }
+      end
+
+      # Number of additional items the stack can accept before it is full.
+      #
+      # Returns +nil+ for unlimited stacks. For bounded stacks returns
+      # +capacity - size+, clamped to a minimum of 0.
+      #
+      # @return [Integer, nil]
+      def remaining_capacity
+        @mutex.synchronize do
+          next nil unless @capacity
+
+          [@capacity - @items.length, 0].max
+        end
+      end
+
+      # Push many items onto the stack in order. The last element of +items+
+      # ends up on top. Each push respects capacity exactly as +push+ would.
+      #
+      # @param items [Array] the items to push, in order
+      # @return [void]
+      # @raise [ClosedError] if the stack has been closed
+      def push_all(items)
+        @mutex.synchronize do
+          raise ClosedError, 'cannot push on a closed stack' if @closed
+
+          items.each do |item|
+            @not_full.wait(@mutex) while @capacity && @items.length >= @capacity
+            raise ClosedError, 'cannot push on a closed stack' if @closed
+
+            @items.push(item)
+            @not_empty.signal
+          end
+        end
+      end
+
+      # Pop up to +max+ items from the top of the stack in LIFO order
+      # (top first). Non-blocking: returns an empty array if the stack is
+      # empty.
+      #
+      # @param max [Integer] maximum number of items to pop (must be a non-negative Integer)
+      # @return [Array] up to +max+ items, top first
+      # @raise [ArgumentError] if +max+ is not a non-negative Integer
+      def pop_batch(max)
+        raise ArgumentError, 'max must be a non-negative Integer' unless max.is_a?(Integer) && max >= 0
+
+        @mutex.synchronize do
+          count = [max, @items.length].min
+          next [] if count.zero?
+
+          batch = Array.new(count) { @items.pop }
+          @not_full.broadcast
+          batch
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/queue_stack/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module QueueStack
-    VERSION = '0.5.0'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-queue_stack
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-05-30 00:00:00.000000000 Z
 dependencies: []
 description: Thread-safe queue and stack data structures with configurable capacity
   limits, blocking enqueue/dequeue with timeouts, and peek operations. Uses Mutex