philiprehberger-queue_stack 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff50a60ddd8a9bd5d462120f2030251c948659105edfe76ee9a87646d16f3a7d
-  data.tar.gz: e34e36ff80548f16e92aa9fd2b604161f74140caff317efec05ae48648bf732e
+  metadata.gz: 61b9b755594ffadcc05a80b942c0424a29043da9e01c81bc41045c5d440156e1
+  data.tar.gz: 823d4982ec931ecf197a42e37ceb7439939a4e6e06070d22ceb437eb1985f2e4
 SHA512:
-  metadata.gz: bb6a2bade86267597f71fe64a549fd82b85f5376a3c4e57b4f2ecc96a5f944abc9f63112c0c50407c185ee41ffa8336a6f1328c866ee70ee21ebbd5eff0eac25
-  data.tar.gz: 0ba54d2272dee5f4fa95ce8e614ef4a7bde2f1db07c3887adf4caee7495395fb387ec76288cd0fc59ed87b7af1fa9d137e4ea866c777a06aa510b147255bdfc7
+  metadata.gz: 0c2f235cd8a6f31bafd5d94af63806e3caabc0fff8743b82815ff90df255f74dbf6d924edccb57e5d73f0fef65958b1c7231e60e96bc9dde9aee3e94718ce0fd
+  data.tar.gz: 35d25847836f39bbd80fd7aa8ff07005c126cec030be1d1e9908a4d428d8f96cf2b662167cce8428314aefd7a1ce2384179dd8489e132f1635333e2ffd1dec48

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-09
+
+### Added
+- `Queue#try_enqueue(item, timeout: nil)` and `Stack#try_push(item, timeout: nil)` non-blocking insertion variants
+- `Queue#clear` and `Stack#clear` to discard all items and wake blocked producers
+
+## [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,66 @@ 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)
+```
+
+### Non-Blocking Insertion
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new(capacity: 1)
+q.enqueue('a')
+q.try_enqueue('b')                 # => false (full, no wait)
+q.try_enqueue('b', timeout: 0.5)   # => false after waiting up to 0.5s
+
+s = Philiprehberger::QueueStack::Stack.new(capacity: 1)
+s.push('a')
+s.try_push('b')                    # => false (full, no wait)
+```
+
+### Clear
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue('a'); q.enqueue('b')
+q.clear
+q.empty?  # => true
+```
+
+### 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
@@ -84,9 +144,16 @@ q.full?   # => true
 |--------|-------------|
 | `.new(capacity:)` | Create a queue with optional capacity limit |
 | `#enqueue(item)` | Add item to back (blocks 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) |
 | `#try_dequeue(timeout:)` | Dequeue with timeout, returns nil on timeout |
+| `#clear` | Remove all items without returning them |
 | `#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 |
@@ -97,9 +164,16 @@ q.full?   # => true
 |--------|-------------|
 | `.new(capacity:)` | Create a stack with optional capacity limit |
 | `#push(item)` | Push item on top (blocks 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) |
 | `#try_pop(timeout:)` | Pop with timeout, returns nil on timeout |
+| `#clear` | Remove all items without returning them |
 | `#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,26 +27,75 @@ 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
         end
       end
 
+      # Try to enqueue an item without blocking indefinitely.
+      #
+      # With timeout: nil, returns immediately. With a numeric timeout, waits up to
+      # that many seconds for space to become available.
+      #
+      # @param item [Object] the item to enqueue
+      # @param timeout [Numeric, nil] seconds to wait, or nil for non-blocking
+      # @return [Boolean] true if enqueued, false if full (or timed out)
+      # @raise [ClosedError] if the queue has been closed
+      def try_enqueue(item, timeout: nil)
+        @mutex.synchronize do
+          raise ClosedError, 'cannot enqueue on a closed queue' if @closed
+
+          if @capacity && @items.length >= @capacity
+            return false if timeout.nil? || timeout <= 0
+
+            deadline = Time.now + timeout
+            while @items.length >= @capacity
+              remaining = deadline - Time.now
+              return false if remaining <= 0
+
+              @not_full.wait(@mutex, remaining)
+              raise ClosedError, 'cannot enqueue on a closed queue' if @closed
+            end
+          end
+
+          @items.push(item)
+          @not_empty.signal
+          true
+        end
+      end
+
+      # Remove all items without returning them. Signals any blocked producers.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize do
+          @items.clear
+          @not_full.broadcast
+        end
+      end
+
       # Try to dequeue an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait
@@ -52,6 +104,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 +117,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,26 +27,75 @@ 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
         end
       end
 
+      # Try to push an item without blocking indefinitely.
+      #
+      # With timeout: nil, returns immediately. With a numeric timeout, waits up to
+      # that many seconds for space to become available.
+      #
+      # @param item [Object] the item to push
+      # @param timeout [Numeric, nil] seconds to wait, or nil for non-blocking
+      # @return [Boolean] true if pushed, false if full (or timed out)
+      # @raise [ClosedError] if the stack has been closed
+      def try_push(item, timeout: nil)
+        @mutex.synchronize do
+          raise ClosedError, 'cannot push on a closed stack' if @closed
+
+          if @capacity && @items.length >= @capacity
+            return false if timeout.nil? || timeout <= 0
+
+            deadline = Time.now + timeout
+            while @items.length >= @capacity
+              remaining = deadline - Time.now
+              return false if remaining <= 0
+
+              @not_full.wait(@mutex, remaining)
+              raise ClosedError, 'cannot push on a closed stack' if @closed
+            end
+          end
+
+          @items.push(item)
+          @not_empty.signal
+          true
+        end
+      end
+
+      # Remove all items without returning them. Signals any blocked producers.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize do
+          @items.clear
+          @not_full.broadcast
+        end
+      end
+
       # Try to pop an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait
@@ -52,6 +104,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 +117,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.3.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.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-09 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