philiprehberger-queue_stack 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dba395bc3ee76baae4cdbbbb100fc91103049635c386e02fe5ac3ae118e9997a
-  data.tar.gz: 921a8e4241383d570d951e154b19e7abcce5cdb682d93b42888d36c9804871a2
+  metadata.gz: aeb1d7901c33280074ac91777f24b5dcc3704f9d3144dac214a4e8baba9b8bf0
+  data.tar.gz: 21a0f6c879d8d1f95270b4d34497e5905064ee96738b30ae9a7bb870c6e3d820
 SHA512:
-  metadata.gz: 30320f35b2ae5d2e01221091e203c31cc799ec5d6a1ff279a0201a04dd9c038f254ad8319d1e4f8cf3a50e1e292e2522a813e8330383f2f49ce99b86d5704b1c
-  data.tar.gz: 2ddd79499fa0b97b99fcb45c5c941984c1f8b3ddeee25cc4edeed317b9317509d9ade981940ca685266770db6dc3d472b11e3fdb8610b45731abd44f7f3a284e
+  metadata.gz: 28ba1990bc0e94d4c79b414d1a62a69d022f4091d76bd3bdc092e6c377cc0fd7fd79d1a265126aed15bf3a705fa34ac05c05d084990ea867022e03220f23ed7d
+  data.tar.gz: d6fc9a7f47a18010cf5b1f7e096861cca61bf565f604c5687a10165cc2074196457e918b3564fe8f80a233ca2e9ad4584929af11b465db4481b3e35f40e0a6ca

data/CHANGELOG.md

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

data/README.md

@@ -159,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`
@@ -182,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`
 
@@ -203,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

@@ -225,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

@@ -213,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.5.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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 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