philiprehberger-queue_stack 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2a9266feb351be5204a7e04178e22531c6e74d0a905c71f878eefe8cf94b606
-  data.tar.gz: e52a17282b21d3961e042bd235e9eb0bcb3885fbc9b5998e15224e07a8e8bbd9
+  metadata.gz: 61b9b755594ffadcc05a80b942c0424a29043da9e01c81bc41045c5d440156e1
+  data.tar.gz: 823d4982ec931ecf197a42e37ceb7439939a4e6e06070d22ceb437eb1985f2e4
 SHA512:
-  metadata.gz: 89a316f59b197ba77230f35da990b9c5ef6c27199466c91cfe039e3574f9b92a217469586975e3814e3ed13a0f9c0223321872d595ec6be07185a15467bc2855
-  data.tar.gz: cf85a470ea4e242be5f99452d0b74f771187f27037b86e7c17960a5968e9ffe83eaef6eb862c38cae65754901e24053235170e93f58b19173b5e1b36cda12104
+  metadata.gz: 0c2f235cd8a6f31bafd5d94af63806e3caabc0fff8743b82815ff90df255f74dbf6d924edccb57e5d73f0fef65958b1c7231e60e96bc9dde9aee3e94718ce0fd
+  data.tar.gz: 35d25847836f39bbd80fd7aa8ff07005c126cec030be1d1e9908a4d428d8f96cf2b662167cce8428314aefd7a1ce2384179dd8489e132f1635333e2ffd1dec48

data/CHANGELOG.md

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

data/README.md

@@ -92,6 +92,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,8 +144,10 @@ 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) |
@@ -140,8 +164,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

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.3.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.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-03 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