philiprehberger-expiring_map 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aed5fe4178a5814d949531b8352284b152a8ac520963541944584e602ebe0c17
-  data.tar.gz: 319d4b05843b15e90cb91c4487d6edc670dc3ffda54d26c9a77e09c035b4a843
+  metadata.gz: c9113519082c9f4bc5b232176d347f5bf07ffd282a63f27be15a68443a6aee90
+  data.tar.gz: 7b90b98bab68612c39f4723c4d7673a1149155c50531972754eb7ae0daea841c
 SHA512:
-  metadata.gz: a3a545614963d2b2a4db845a909ad9f2bafb0fea91b543ec9456eebf0a7ddf3a7af2029c8080f357aea6bf0294a9744b672015fbbcfc9b74942b3f524b3ab8d6
-  data.tar.gz: a7052a46245d890e339ed5e40b3bd78e21a1d29fb45441c86629ed0afaaf2fede1c69e7d77e9d401e1670d66eef55282bab0b63f4d3e7523e37473408a142ffb
+  metadata.gz: f55f4d5d64f2b81cd57519784e8fdce758360f72c9cd85c6789f29bea0950de80eaf3a649b1d0c070c890179db3a126893e9933aa39f9e41817fcccc765c3e34
+  data.tar.gz: 40c275b4ef7abd9dfc531bcf6ef19e44d812e25b1eb5158c4d4b2cdea07f6e0952dff5e6543a6fad9cb67ea4d2a6389dfbda2c6c2ce4dee867173d86f374fb44

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-27
+
+### Added
+- `Map#purge_expired!` — actively sweep expired entries and return the count removed; fires `on_expire` callbacks. Useful for explicit cleanup in long-running processes that read sparingly.
+- `Map#expired?(key)` — predicate for whether an entry is present-but-expired without deleting it or firing `on_expire`. Distinct from `get(key).nil?`, which can't tell "missing" from "expired".
+
+## [0.3.0] - 2026-04-17
+
+### Added
+- `Map#fetch(key, ttl: nil) { block }` atomically memoizes the block result on miss
+
 ## [0.2.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -42,6 +42,19 @@ cache.set(:config, data, ttl: 3600)   # expires in 1 hour
 cache.ttl(:token)                      # => remaining seconds
 ```
 
+### Fetch-or-compute
+
+```ruby
+cache = Philiprehberger::ExpiringMap.new(default_ttl: 300)
+
+# On miss, the block is evaluated, the result stored, and returned.
+# On hit, the stored value is returned and the block is not called.
+user = cache.fetch(:user_42) { User.find(42) }
+
+# Override the TTL for this insert only:
+token = cache.fetch(:token, ttl: 60) { Auth.issue_token }
+```
+
 ### Max Size with Eviction
 
 ```ruby
@@ -108,6 +121,33 @@ cache.each { |key, value| puts "#{key}: #{value}" }
 cache.select { |_k, v| v > 10 }
 ```
 
+### Manual Sweep
+
+Most read methods (`get`, `size`, `each`, `keys`, `values`) sweep expired
+entries lazily on access. Long-running processes that read sparingly can
+accumulate stale entries between reads — call `purge_expired!` to reclaim
+memory and fire `on_expire` callbacks for everything that has expired:
+
+```ruby
+cache.set(:a, 1, ttl: 0.01)
+cache.set(:b, 2, ttl: 10)
+sleep 0.02
+
+cache.purge_expired!  # => 1   (number of entries removed)
+cache.keys             # => [:b]
+```
+
+`expired?(key)` returns whether a present key has elapsed its TTL — without
+deleting the entry or firing `on_expire`. Distinct from `get(key).nil?`,
+which can't tell "missing" from "expired":
+
+```ruby
+cache.set(:dead, 'gone', ttl: 0.01)
+sleep 0.02
+cache.expired?(:dead)   # => true
+cache.expired?(:nope)   # => false (missing, not expired)
+```
+
 ## API
 
 | Method | Description |
@@ -115,6 +155,7 @@ cache.select { |_k, v| v > 10 }
 | `.new(default_ttl:, max_size:)` | Create a new expiring map |
 | `#set(key, value, ttl:)` | Store a value with optional per-key TTL |
 | `#get(key)` | Retrieve a value, nil if expired or missing |
+| `#fetch(key, ttl:) { block }` | Return stored value or atomically memoize block result on miss |
 | `#set_many(hash, ttl:)` | Bulk insert from a hash |
 | `#get_many(*keys)` | Bulk get returning hash of key => value |
 | `#delete(key)` | Remove and return a value |
@@ -128,6 +169,8 @@ cache.select { |_k, v| v > 10 }
 | `#on_expire { \|k, v\| }` | Register expiration callback |
 | `#clear` | Remove all entries |
 | `#each { \|k, v\| }` | Iterate over non-expired entries |
+| `#purge_expired!` | Actively sweep expired entries; fires `on_expire`; returns the count removed |
+| `#expired?(key)` | Whether the entry at `key` is present-but-expired (does not delete or fire `on_expire`) |
 
 ## Development
 

data/lib/philiprehberger/expiring_map/map.rb

@@ -66,6 +66,50 @@ module Philiprehberger
         end
       end
 
+      # Retrieve a value by key, or atomically compute and store it on miss
+      #
+      # If the key is present and not expired, returns the stored value.
+      # Otherwise evaluates the block, stores the result under +key+ with the
+      # default TTL (or +ttl:+ override), and returns it. The get/compute/set
+      # path runs under the same mutex used by +#get+ and +#set+ so there is
+      # no race with concurrent writers.
+      #
+      # @param key [Object] the key
+      # @param ttl [Numeric, nil] TTL in seconds for the inserted value on miss, uses default if nil
+      # @yieldreturn [Object] the value to memoize under +key+ on miss
+      # @raise [KeyError] if the key is missing/expired and no block is given
+      # @return [Object] the stored or freshly computed value
+      def fetch(key, ttl: nil)
+        @mutex.synchronize do
+          entry = @store[key]
+
+          if entry && !entry.expired?
+            @hits += 1
+            return entry.value
+          end
+
+          if entry&.expired?
+            @expirations += 1
+            fire_expire(key, entry.value)
+            @store.delete(key)
+          end
+
+          @misses += 1
+
+          raise KeyError, "key not found: #{key.inspect}" unless block_given?
+
+          value = yield
+          effective_ttl = ttl || @default_ttl
+          expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + effective_ttl
+
+          sweep_expired
+          evict_oldest if @max_size && @store.size >= @max_size && !@store.key?(key)
+          @store[key] = Entry.new(value, expires_at)
+
+          value
+        end
+      end
+
       # Delete a key
       #
       # @param key [Object] the key
@@ -224,6 +268,39 @@ module Philiprehberger
         end
       end
 
+      # Actively sweep expired entries and return how many were removed.
+      #
+      # Most read methods (`get`, `size`, `each`, `keys`, `values`) sweep lazily,
+      # so long-running processes that read sparingly may accumulate stale
+      # entries before the next read triggers cleanup. Call this to reclaim
+      # memory and fire `on_expire` callbacks for everything that has expired.
+      #
+      # @return [Integer] number of entries removed
+      def purge_expired!
+        @mutex.synchronize do
+          before = @store.size
+          sweep_expired
+          before - @store.size
+        end
+      end
+
+      # Whether the entry at +key+ has expired.
+      #
+      # Returns +false+ when the key is missing or still valid; returns +true+
+      # when the entry exists but its TTL has elapsed. Unlike `get`, this does
+      # not delete the entry or fire `on_expire`.
+      #
+      # @param key [Object] the key
+      # @return [Boolean]
+      def expired?(key)
+        @mutex.synchronize do
+          entry = @store[key]
+          return false unless entry
+
+          entry.expired?
+        end
+      end
+
       private
 
       # Remove all expired entries, firing callbacks

data/lib/philiprehberger/expiring_map/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-expiring_map
 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-28 00:00:00.000000000 Z
 dependencies: []
 description: A thread-safe hash map where each key has its own TTL, with automatic
   expiration, max size eviction, expiration callbacks, and Enumerable support.