philiprehberger-queue_stack 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeb1d7901c33280074ac91777f24b5dcc3704f9d3144dac214a4e8baba9b8bf0
-  data.tar.gz: 21a0f6c879d8d1f95270b4d34497e5905064ee96738b30ae9a7bb870c6e3d820
+  metadata.gz: dbcea69e9c62dd59232e450824070497d480a78224b1f04894664832e1e5c019
+  data.tar.gz: b9c91c0ff26af13c51ce30667c5eee0ad0bedce13c807164ddcd273e147d2513
 SHA512:
-  metadata.gz: 28ba1990bc0e94d4c79b414d1a62a69d022f4091d76bd3bdc092e6c377cc0fd7fd79d1a265126aed15bf3a705fa34ac05c05d084990ea867022e03220f23ed7d
-  data.tar.gz: d6fc9a7f47a18010cf5b1f7e096861cca61bf565f604c5687a10165cc2074196457e918b3564fe8f80a233ca2e9ad4584929af11b465db4481b3e35f40e0a6ca
+  metadata.gz: 8db38faf1a4c7090ee405fededf09f3f939fd11217d46d0220641ff12b3ef286ca915c845b98847e3c22e7f4e0a4ab55d5c71a14d18db9af7b99859e24b454ff
+  data.tar.gz: 748285864c78717094e6f34a8c0cf9b4fc2e9c7bde05c17d14b8bd60821790bca8687b9076e2f4d24b9f5bb3cab3a23c131e1dd87cd64f7a4b6da1b30985df38

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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
@@ -175,6 +177,21 @@ 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`
@@ -183,8 +200,10 @@ batch_size = [items.length, q.remaining_capacity].min
 |--------|-------------|
 | `.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 |
@@ -207,8 +226,10 @@ batch_size = [items.length, q.remaining_capacity].min
 |--------|-------------|
 | `.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 |

data/lib/philiprehberger/queue_stack/queue.rb

@@ -246,6 +246,47 @@ module Philiprehberger
           [@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

@@ -234,6 +234,46 @@ module Philiprehberger
           [@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.6.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.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 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