philiprehberger-queue_stack 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f720c2ee97526d57826cb37fba4be96e6e1143879b7627a2792cef97ffaa1dc
-  data.tar.gz: 311fdae1a3eb9f31d27f4ef77006eae1f224050418ac97721540d761ac081ac0
+  metadata.gz: aeb1d7901c33280074ac91777f24b5dcc3704f9d3144dac214a4e8baba9b8bf0
+  data.tar.gz: 21a0f6c879d8d1f95270b4d34497e5905064ee96738b30ae9a7bb870c6e3d820
 SHA512:
-  metadata.gz: fd4c5bc553fde4d2278b2efa422ed0c4c67aaf63d9c5bc049bce395066ab544533bf2b11696a564769cbd6dbdd900a4c802a12abec032d888d17c0d0d5d0dc36
-  data.tar.gz: aa1cc6ea3d889cde7c372943df2bb9b5c46d0f87f3e628659e01ebbbf3697a8ce548f41c36508a3f82af14818ca0bd852da74aa577e13abf29899f1b60e6a162
+  metadata.gz: 28ba1990bc0e94d4c79b414d1a62a69d022f4091d76bd3bdc092e6c377cc0fd7fd79d1a265126aed15bf3a705fa34ac05c05d084990ea867022e03220f23ed7d
+  data.tar.gz: d6fc9a7f47a18010cf5b1f7e096861cca61bf565f604c5687a10165cc2074196457e918b3564fe8f80a233ca2e9ad4584929af11b465db4481b3e35f40e0a6ca

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-27
+
+### Added
+- `Queue#capacity`, `Queue#remaining_capacity`, `Stack#capacity`, `Stack#remaining_capacity` — capacity introspection. `capacity` returns the configured limit (or `nil` for unlimited); `remaining_capacity` returns the number of additional items that can still be accepted (or `nil` for unlimited, `0` when full). Mutex-synchronized for consistent reads.
+
+## [0.5.0] - 2026-04-16
+
+### Added
+- `Queue#dequeue_if { |item| ... }` conditionally removes and returns the front item only when the block returns truthy; returns `nil` when empty or the block returns false (non-blocking)
+- `Stack#pop_if { |item| ... }` conditionally removes and returns the top item only when the block returns truthy; returns `nil` when empty or the block returns false (non-blocking)
+
 ## [0.4.0] - 2026-04-15
 
 ### Added

data/README.md

@@ -70,6 +70,25 @@ s = Philiprehberger::QueueStack::Stack.new
 item = s.try_pop(timeout: 5)  # waits up to 5 seconds
 ```
 
+### Conditional Removal
+
+Remove the front/top item only when a predicate holds. Non-blocking; returns `nil` if the collection is empty or the block returns false (the item stays put).
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue({ priority: 10 })
+q.enqueue({ priority: 2 })
+
+# Only take high-priority work
+q.dequeue_if { |job| job[:priority] >= 5 }  # => { priority: 10 }
+q.dequeue_if { |job| job[:priority] >= 5 }  # => nil (head priority 2 left intact)
+
+s = Philiprehberger::QueueStack::Stack.new
+s.push(:ready)
+s.pop_if { |item| item == :ready }   # => :ready
+s.pop_if { |item| item == :ready }   # => nil (empty)
+```
+
 ### Drain
 
 ```ruby
@@ -140,6 +159,22 @@ q.full?   # => true
 # enqueue blocks until space is available
 ```
 
+### Capacity
+
+Read the configured capacity and the number of additional items that can be
+accepted. Both return `nil` for unbounded containers; `remaining_capacity`
+returns `0` when full. Useful for sizing batches or backpressure decisions.
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new(capacity: 100)
+q.capacity            # => 100
+q.remaining_capacity  # => 100
+50.times { |i| q.enqueue(i) }
+q.remaining_capacity  # => 50
+
+batch_size = [items.length, q.remaining_capacity].min
+```
+
 ## API
 
 ### `Queue`
@@ -150,6 +185,7 @@ q.full?   # => true
 | `#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) |
+| `#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 |
 | `#peek` | View front item without removing |
@@ -162,6 +198,8 @@ q.full?   # => true
 | `#size` | Number of items |
 | `#empty?` | Whether the queue is empty |
 | `#full?` | Whether the queue is at capacity |
+| `#capacity` | Configured capacity, or `nil` for an unlimited queue |
+| `#remaining_capacity` | Items the queue can still accept (`nil` for unlimited, `0` when full) |
 
 ### `Stack`
 
@@ -171,6 +209,7 @@ q.full?   # => true
 | `#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) |
+| `#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 |
 | `#peek` | View top item without removing |
@@ -182,6 +221,8 @@ q.full?   # => true
 | `#size` | Number of items |
 | `#empty?` | Whether the stack is empty |
 | `#full?` | Whether the stack is at capacity |
+| `#capacity` | Configured capacity, or `nil` for an unlimited stack |
+| `#remaining_capacity` | Items the stack can still accept (`nil` for unlimited, `0` when full) |
 
 ## Development
 

data/lib/philiprehberger/queue_stack/queue.rb

@@ -96,6 +96,24 @@ module Philiprehberger
         end
       end
 
+      # Conditionally dequeue the front item. The block is called with the item
+      # that would be dequeued next. If the block returns truthy, the item is
+      # removed and returned. Otherwise the item is left in place and +nil+ is
+      # returned. Returns +nil+ immediately if the queue is empty (non-blocking).
+      #
+      # @yield [item] the front item
+      # @return [Object, nil] the removed item, or nil if empty or block returned false
+      def dequeue_if
+        @mutex.synchronize do
+          return nil if @items.empty?
+          return nil unless yield(@items.first)
+
+          item = @items.shift
+          @not_full.signal
+          item
+        end
+      end
+
       # Try to dequeue an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait
@@ -207,6 +225,27 @@ module Philiprehberger
       def full?
         @mutex.synchronize { @capacity ? @items.length >= @capacity : false }
       end
+
+      # The configured capacity, or +nil+ for an unlimited queue.
+      #
+      # @return [Integer, nil]
+      def capacity
+        @mutex.synchronize { @capacity }
+      end
+
+      # Number of additional items the queue can accept before it is full.
+      #
+      # Returns +nil+ for unlimited queues. For bounded queues returns
+      # +capacity - size+, clamped to a minimum of 0.
+      #
+      # @return [Integer, nil]
+      def remaining_capacity
+        @mutex.synchronize do
+          next nil unless @capacity
+
+          [@capacity - @items.length, 0].max
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/queue_stack/stack.rb

@@ -96,6 +96,24 @@ module Philiprehberger
         end
       end
 
+      # Conditionally pop the top item. The block is called with the item that
+      # would be popped next. If the block returns truthy, the item is removed
+      # and returned. Otherwise the item is left in place and +nil+ is returned.
+      # Returns +nil+ immediately if the stack is empty (non-blocking).
+      #
+      # @yield [item] the top item
+      # @return [Object, nil] the removed item, or nil if empty or block returned false
+      def pop_if
+        @mutex.synchronize do
+          return nil if @items.empty?
+          return nil unless yield(@items.last)
+
+          item = @items.pop
+          @not_full.signal
+          item
+        end
+      end
+
       # Try to pop an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait
@@ -195,6 +213,27 @@ module Philiprehberger
       def full?
         @mutex.synchronize { @capacity ? @items.length >= @capacity : false }
       end
+
+      # The configured capacity, or +nil+ for an unlimited stack.
+      #
+      # @return [Integer, nil]
+      def capacity
+        @mutex.synchronize { @capacity }
+      end
+
+      # Number of additional items the stack can accept before it is full.
+      #
+      # Returns +nil+ for unlimited stacks. For bounded stacks returns
+      # +capacity - size+, clamped to a minimum of 0.
+      #
+      # @return [Integer, nil]
+      def remaining_capacity
+        @mutex.synchronize do
+          next nil unless @capacity
+
+          [@capacity - @items.length, 0].max
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/queue_stack/version.rb

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

metadata

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