philiprehberger-queue_stack 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff50a60ddd8a9bd5d462120f2030251c948659105edfe76ee9a87646d16f3a7d
-  data.tar.gz: e34e36ff80548f16e92aa9fd2b604161f74140caff317efec05ae48648bf732e
+  metadata.gz: d2a9266feb351be5204a7e04178e22531c6e74d0a905c71f878eefe8cf94b606
+  data.tar.gz: e52a17282b21d3961e042bd235e9eb0bcb3885fbc9b5998e15224e07a8e8bbd9
 SHA512:
-  metadata.gz: bb6a2bade86267597f71fe64a549fd82b85f5376a3c4e57b4f2ecc96a5f944abc9f63112c0c50407c185ee41ffa8336a6f1328c866ee70ee21ebbd5eff0eac25
-  data.tar.gz: 0ba54d2272dee5f4fa95ce8e614ef4a7bde2f1db07c3887adf4caee7495395fb387ec76288cd0fc59ed87b7af1fa9d137e4ea866c777a06aa510b147255bdfc7
+  metadata.gz: 89a316f59b197ba77230f35da990b9c5ef6c27199466c91cfe039e3574f9b92a217469586975e3814e3ed13a0f9c0223321872d595ec6be07185a15467bc2855
+  data.tar.gz: cf85a470ea4e242be5f99452d0b74f771187f27037b86e7c17960a5968e9ffe83eaef6eb862c38cae65754901e24053235170e93f58b19173b5e1b36cda12104

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-03
+
+### Added
+- `drain` method to remove and return all items at once
+- `each` and `to_a` for non-destructive iteration
+- `close` / `closed?` for graceful shutdown semantics
+- `ClosedError` raised when adding to a closed container
+
+## [0.1.5] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.1.4] - 2026-03-31
 
 ### Changed

data/README.md

@@ -66,6 +66,44 @@ s = Philiprehberger::QueueStack::Stack.new
 item = s.try_pop(timeout: 5)  # waits up to 5 seconds
 ```
 
+### Drain
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue('a')
+q.enqueue('b')
+q.enqueue('c')
+q.drain  # => ['a', 'b', 'c'] (queue is now empty)
+
+s = Philiprehberger::QueueStack::Stack.new
+s.push('a')
+s.push('b')
+s.push('c')
+s.drain  # => ['c', 'b', 'a'] (stack is now empty)
+```
+
+### Iteration
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue('a')
+q.enqueue('b')
+q.each { |item| puts item }  # prints 'a', 'b'
+q.to_a                        # => ['a', 'b'] (queue unchanged)
+```
+
+### Close / Shutdown
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue('a')
+q.close
+q.closed?     # => true
+q.dequeue     # => 'a'
+q.dequeue     # => nil (closed and empty)
+q.enqueue('b') # raises Philiprehberger::QueueStack::ClosedError
+```
+
 ### Capacity Limits
 
 ```ruby
@@ -87,6 +125,11 @@ q.full?   # => true
 | `#dequeue` | Remove and return front item (blocks if empty) |
 | `#try_dequeue(timeout:)` | Dequeue with timeout, returns nil on timeout |
 | `#peek` | View front item without removing |
+| `#drain` | Remove and return all items as array (FIFO order) |
+| `#each` | Iterate items without removing (returns Enumerator if no block) |
+| `#to_a` | Snapshot as array (FIFO order) |
+| `#close` | Mark as closed (new enqueues raise `ClosedError`) |
+| `#closed?` | Whether the queue has been closed |
 | `#size` | Number of items |
 | `#empty?` | Whether the queue is empty |
 | `#full?` | Whether the queue is at capacity |
@@ -100,6 +143,11 @@ q.full?   # => true
 | `#pop` | Remove and return top item (blocks if empty) |
 | `#try_pop(timeout:)` | Pop with timeout, returns nil on timeout |
 | `#peek` | View top item without removing |
+| `#drain` | Remove and return all items as array (LIFO order) |
+| `#each` | Iterate items without removing (returns Enumerator if no block) |
+| `#to_a` | Snapshot as array (LIFO order) |
+| `#close` | Mark as closed (new pushes raise `ClosedError`) |
+| `#closed?` | Whether the stack has been closed |
 | `#size` | Number of items |
 | `#empty?` | Whether the stack is empty |
 | `#full?` | Whether the stack is at capacity |

data/lib/philiprehberger/queue_stack/queue.rb

@@ -9,12 +9,15 @@ module Philiprehberger
     #   q.enqueue('item')
     #   q.dequeue  # => 'item'
     class Queue
+      include Enumerable
+
       # Create a new queue.
       #
       # @param capacity [Integer, nil] maximum number of items (nil for unlimited)
       def initialize(capacity: nil)
         @items = []
         @capacity = capacity
+        @closed = false
         @mutex = Mutex.new
         @not_empty = ConditionVariable.new
         @not_full = ConditionVariable.new
@@ -24,20 +27,27 @@ module Philiprehberger
       #
       # @param item [Object] the item to enqueue
       # @return [void]
+      # @raise [ClosedError] if the queue has been closed
       def enqueue(item)
         @mutex.synchronize do
+          raise ClosedError, 'cannot enqueue on a closed queue' if @closed
+
           @not_full.wait(@mutex) while @capacity && @items.length >= @capacity
           @items.push(item)
           @not_empty.signal
         end
       end
 
-      # Remove and return the front item. Blocks if empty.
+      # Remove and return the front item. Blocks if empty (returns nil if closed and empty).
       #
-      # @return [Object] the dequeued item
+      # @return [Object, nil] the dequeued item or nil if closed and empty
       def dequeue
         @mutex.synchronize do
-          @not_empty.wait(@mutex) while @items.empty?
+          while @items.empty?
+            return nil if @closed
+
+            @not_empty.wait(@mutex)
+          end
           item = @items.shift
           @not_full.signal
           item
@@ -52,6 +62,8 @@ module Philiprehberger
         deadline = Time.now + timeout
         @mutex.synchronize do
           while @items.empty?
+            return nil if @closed
+
             remaining = deadline - Time.now
             return nil if remaining <= 0
 
@@ -63,6 +75,57 @@ module Philiprehberger
         end
       end
 
+      # Remove and return all items as an array (FIFO order). Non-blocking.
+      #
+      # @return [Array] all items in FIFO order
+      def drain
+        @mutex.synchronize do
+          result = @items.dup
+          @items.clear
+          @not_full.broadcast
+          result
+        end
+      end
+
+      # Iterate items without removing them (snapshot of current state, FIFO order).
+      # Returns an Enumerator if no block is given.
+      #
+      # @yield [item] each item in FIFO order
+      # @return [Enumerator, self]
+      def each(&block)
+        snapshot = @mutex.synchronize { @items.dup }
+        return snapshot.each unless block
+
+        snapshot.each(&block)
+        self
+      end
+
+      # Return a snapshot of items as an array (FIFO order).
+      #
+      # @return [Array]
+      def to_a
+        @mutex.synchronize { @items.dup }
+      end
+
+      # Mark the queue as closed. New enqueue calls will raise ClosedError.
+      # Existing items can still be dequeued. Wakes all waiting threads.
+      #
+      # @return [void]
+      def close
+        @mutex.synchronize do
+          @closed = true
+          @not_empty.broadcast
+          @not_full.broadcast
+        end
+      end
+
+      # Whether the queue has been closed.
+      #
+      # @return [Boolean]
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
       # Peek at the front item without removing it.
       #
       # @return [Object, nil] the front item or nil if empty

data/lib/philiprehberger/queue_stack/stack.rb

@@ -9,12 +9,15 @@ module Philiprehberger
     #   s.push('item')
     #   s.pop  # => 'item'
     class Stack
+      include Enumerable
+
       # Create a new stack.
       #
       # @param capacity [Integer, nil] maximum number of items (nil for unlimited)
       def initialize(capacity: nil)
         @items = []
         @capacity = capacity
+        @closed = false
         @mutex = Mutex.new
         @not_empty = ConditionVariable.new
         @not_full = ConditionVariable.new
@@ -24,20 +27,27 @@ module Philiprehberger
       #
       # @param item [Object] the item to push
       # @return [void]
+      # @raise [ClosedError] if the stack has been closed
       def push(item)
         @mutex.synchronize do
+          raise ClosedError, 'cannot push on a closed stack' if @closed
+
           @not_full.wait(@mutex) while @capacity && @items.length >= @capacity
           @items.push(item)
           @not_empty.signal
         end
       end
 
-      # Pop and return the top item. Blocks if empty.
+      # Pop and return the top item. Blocks if empty (returns nil if closed and empty).
       #
-      # @return [Object] the popped item
+      # @return [Object, nil] the popped item or nil if closed and empty
       def pop
         @mutex.synchronize do
-          @not_empty.wait(@mutex) while @items.empty?
+          while @items.empty?
+            return nil if @closed
+
+            @not_empty.wait(@mutex)
+          end
           item = @items.pop
           @not_full.signal
           item
@@ -52,6 +62,8 @@ module Philiprehberger
         deadline = Time.now + timeout
         @mutex.synchronize do
           while @items.empty?
+            return nil if @closed
+
             remaining = deadline - Time.now
             return nil if remaining <= 0
 
@@ -63,6 +75,57 @@ module Philiprehberger
         end
       end
 
+      # Remove and return all items as an array (LIFO order, top first). Non-blocking.
+      #
+      # @return [Array] all items in LIFO order (top first)
+      def drain
+        @mutex.synchronize do
+          result = @items.reverse
+          @items.clear
+          @not_full.broadcast
+          result
+        end
+      end
+
+      # Iterate items without removing them (snapshot of current state, LIFO order).
+      # Returns an Enumerator if no block is given.
+      #
+      # @yield [item] each item in LIFO order (top first)
+      # @return [Enumerator, self]
+      def each(&block)
+        snapshot = @mutex.synchronize { @items.reverse }
+        return snapshot.each unless block
+
+        snapshot.each(&block)
+        self
+      end
+
+      # Return a snapshot of items as an array (LIFO order, top first).
+      #
+      # @return [Array]
+      def to_a
+        @mutex.synchronize { @items.reverse }
+      end
+
+      # Mark the stack as closed. New push calls will raise ClosedError.
+      # Existing items can still be popped. Wakes all waiting threads.
+      #
+      # @return [void]
+      def close
+        @mutex.synchronize do
+          @closed = true
+          @not_empty.broadcast
+          @not_full.broadcast
+        end
+      end
+
+      # Whether the stack has been closed.
+      #
+      # @return [Boolean]
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
       # Peek at the top item without removing it.
       #
       # @return [Object, nil] the top item or nil if empty

data/lib/philiprehberger/queue_stack/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module QueueStack
-    VERSION = '0.1.4'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/queue_stack.rb

@@ -7,5 +7,6 @@ require_relative 'queue_stack/stack'
 module Philiprehberger
   module QueueStack
     class Error < StandardError; end
+    class ClosedError < Error; end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-queue_stack
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-03 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
@@ -26,11 +26,11 @@ files:
 - lib/philiprehberger/queue_stack/queue.rb
 - lib/philiprehberger/queue_stack/stack.rb
 - lib/philiprehberger/queue_stack/version.rb
-homepage: https://github.com/philiprehberger/rb-queue-stack
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-queue_stack
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-queue-stack
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-queue_stack
   source_code_uri: https://github.com/philiprehberger/rb-queue-stack
   changelog_uri: https://github.com/philiprehberger/rb-queue-stack/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-queue-stack/issues