philiprehberger-queue_stack 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2a9266feb351be5204a7e04178e22531c6e74d0a905c71f878eefe8cf94b606
-  data.tar.gz: e52a17282b21d3961e042bd235e9eb0bcb3885fbc9b5998e15224e07a8e8bbd9
+  metadata.gz: 8f720c2ee97526d57826cb37fba4be96e6e1143879b7627a2792cef97ffaa1dc
+  data.tar.gz: 311fdae1a3eb9f31d27f4ef77006eae1f224050418ac97721540d761ac081ac0
 SHA512:
-  metadata.gz: 89a316f59b197ba77230f35da990b9c5ef6c27199466c91cfe039e3574f9b92a217469586975e3814e3ed13a0f9c0223321872d595ec6be07185a15467bc2855
-  data.tar.gz: cf85a470ea4e242be5f99452d0b74f771187f27037b86e7c17960a5968e9ffe83eaef6eb862c38cae65754901e24053235170e93f58b19173b5e1b36cda12104
+  metadata.gz: fd4c5bc553fde4d2278b2efa422ed0c4c67aaf63d9c5bc049bce395066ab544533bf2b11696a564769cbd6dbdd900a4c802a12abec032d888d17c0d0d5d0dc36
+  data.tar.gz: aa1cc6ea3d889cde7c372943df2bb9b5c46d0f87f3e628659e01ebbbf3697a8ce548f41c36508a3f82af14818ca0bd852da74aa577e13abf29899f1b60e6a162

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-15
+
+### Added
+- `Queue#peek_at(index)` returns the item at the given position without removing it, supporting negative indices like `Array#[]` and returning `nil` when out of range
+
+## [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

data/README.md

@@ -40,9 +40,13 @@ item = q.dequeue  # => 'task'
 q = Philiprehberger::QueueStack::Queue.new(capacity: 10)
 q.enqueue('first')
 q.enqueue('second')
-q.dequeue   # => 'first'
-q.peek      # => 'second'
-q.size      # => 1
+q.enqueue('third')
+q.peek         # => 'first'
+q.peek_at(1)   # => 'second'
+q.peek_at(-1)  # => 'third'
+q.peek_at(99)  # => nil (out of range)
+q.dequeue      # => 'first'
+q.size         # => 2
 ```
 
 ### Stack (LIFO)
@@ -92,6 +96,28 @@ 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
@@ -122,9 +148,12 @@ 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 |
+| `#peek_at(index)` | View item at the given position (supports negative indices, returns nil if out of range) |
 | `#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) |
@@ -140,8 +169,10 @@ 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) |

data/lib/philiprehberger/queue_stack/queue.rb

@@ -54,6 +54,48 @@ module Philiprehberger
         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
@@ -133,6 +175,18 @@ module Philiprehberger
         @mutex.synchronize { @items.first }
       end
 
+      # Peek at the item at the given position without removing it.
+      #
+      # Indexing follows +Array#[]+ semantics: +0+ is the front of the queue,
+      # +size - 1+ is the back, and negative indices count from the back
+      # (+-1+ is the last item). Returns +nil+ when the index is out of range.
+      #
+      # @param index [Integer] position in the queue (supports negative indices)
+      # @return [Object, nil] the item at the position or nil if out of range
+      def peek_at(index)
+        @mutex.synchronize { @items[index] }
+      end
+
       # Return the number of items in the queue.
       #
       # @return [Integer]

data/lib/philiprehberger/queue_stack/stack.rb

@@ -54,6 +54,48 @@ module Philiprehberger
         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

data/lib/philiprehberger/queue_stack/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-queue_stack
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-03 00:00:00.000000000 Z
+date: 2026-04-15 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