zache 0.13.2 → 0.14.0

data/lib/zache.rb

@@ -1,26 +1,7 @@
 # frozen_string_literal: true
 
-# (The MIT License)
-#
-# Copyright (c) 2018-2024 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 # It is a very simple thread-safe in-memory cache with an ability to expire
 # keys automatically, when their lifetime is over. Use it like this:
@@ -34,35 +15,60 @@
 # {README}[https://github.com/yegor256/zache/blob/master/README.md] file.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
 # License:: MIT
 class Zache
   # Fake implementation that doesn't cache anything, but behaves like it
   # does. It implements all methods of the original class, but doesn't do
   # any caching. This is very useful for testing.
   class Fake
+    # Returns a fixed size of 1.
+    # @return [Integer] Always returns 1
     def size
       1
     end
 
+    # Always returns the result of the block, never caches.
+    # @param [Object] key Ignored
+    # @param [Hash] opts Ignored
+    # @yield Block that provides the value
+    # @return [Object] The result of the block
     def get(*)
       yield
     end
 
+    # Always returns true regardless of the key.
+    # @param [Object] key Ignored
+    # @param [Hash] opts Ignored
+    # @return [Boolean] Always returns true
     def exists?(*)
       true
     end
 
+    # Always returns false.
+    # @return [Boolean] Always returns false
     def locked?
       false
     end
 
+    # No-op method that ignores the input.
+    # @param [Object] key Ignored
+    # @param [Object] value Ignored
+    # @param [Hash] opts Ignored
+    # @return [nil] Always returns nil
     def put(*); end
 
+    # No-op method that ignores the key.
+    # @param [Object] _key Ignored
+    # @return [nil] Always returns nil
     def remove(_key); end
 
+    # No-op method.
+    # @return [nil] Always returns nil
     def remove_all; end
 
+    # No-op method.
+    # @return [nil] Always returns nil
     def clean; end
   end
 
@@ -73,7 +79,11 @@ class Zache
   # unless you really know what you are doing.
   #
   # If the <tt>dirty</tt> argument is set to <tt>true</tt>, a previously
-  # calculated result will be returned if it exists and is already expired.
+  # calculated result will be returned if it exists, even if it is already expired.
+  #
+  # @param sync [Boolean] Whether the hash is thread-safe
+  # @param dirty [Boolean] Whether to return expired values
+  # @return [Zache] A new instance of the cache
   def initialize(sync: true, dirty: false)
     @hash = {}
     @sync = sync
@@ -82,6 +92,8 @@ class Zache
   end
 
   # Total number of keys currently in cache.
+  #
+  # @return [Integer] Number of keys in the cache
   def size
     @hash.size
   end
@@ -90,17 +102,39 @@ class Zache
   #
   # If the value is not
   # found in the cache, it will be calculated via the provided block. If
-  # the block is not given, an exception will be raised (unless <tt>dirty</tt>
-  # is set to <tt>true</tt>). The lifetime
+  # the block is not given and the key doesn't exist or is expired, an exception will be raised
+  # (unless <tt>dirty</tt> is set to <tt>true</tt>). The lifetime
   # must be in seconds. The default lifetime is huge, which means that the
   # key will never be expired.
   #
   # If the <tt>dirty</tt> argument is set to <tt>true</tt>, a previously
-  # calculated result will be returned if it exists and is already expired.
-  def get(key, lifetime: 2**32, dirty: false, &block)
+  # calculated result will be returned if it exists, even if it is already expired.
+  #
+  # @param key [Object] The key to retrieve from the cache
+  # @param lifetime [Integer] Time in seconds until the key expires
+  # @param dirty [Boolean] Whether to return expired values
+  # @param eager [Boolean] Whether to return placeholder while working?
+  # @param placeholder [Object] The placeholder to return in eager mode
+  # @yield Block to calculate the value if not in cache
+  # @yieldreturn [Object] The value to cache
+  # @return [Object] The cached value
+  def get(key, lifetime: 2**32, dirty: false, placeholder: nil, eager: false, &block)
     if block_given?
       return @hash[key][:value] if (dirty || @dirty) && locked? && expired?(key) && @hash.key?(key)
-      synchronized { calc(key, lifetime, &block) }
+      if eager
+        return @hash[key][:value] if @hash.key?(key)
+        put(key, placeholder, lifetime: 0)
+        Thread.new do
+          synchronized do
+            calc(key, lifetime, &block)
+          end
+        end
+        placeholder
+      else
+        synchronized do
+          calc(key, lifetime, &block)
+        end
+      end
     else
       rec = @hash[key]
       if expired?(key)
@@ -114,8 +148,12 @@ class Zache
   end
 
   # Checks whether the value exists in the cache by the provided key. Returns
-  # TRUE if the value is here. If the key is already expired in the hash,
+  # TRUE if the value is here. If the key is already expired in the cache,
   # it will be removed by this method and the result will be FALSE.
+  #
+  # @param key [Object] The key to check in the cache
+  # @param dirty [Boolean] Whether to consider expired values as existing
+  # @return [Boolean] True if the key exists and is not expired (unless dirty is true)
   def exists?(key, dirty: false)
     rec = @hash[key]
     if expired?(key) && !dirty && !@dirty
@@ -127,6 +165,9 @@ class Zache
 
   # Checks whether the key exists in the cache and is expired. If the
   # key is absent FALSE is returned.
+  #
+  # @param key [Object] The key to check in the cache
+  # @return [Boolean] True if the key exists and is expired
   def expired?(key)
     rec = @hash[key]
     !rec.nil? && rec[:start] < Time.now - rec[:lifetime]
@@ -134,17 +175,27 @@ class Zache
 
   # Returns the modification time of the key, if it exists.
   # If not, current time is returned.
+  #
+  # @param key [Object] The key to get the modification time for
+  # @return [Time] The modification time of the key or current time if key doesn't exist
   def mtime(key)
     rec = @hash[key]
     rec.nil? ? Time.now : rec[:start]
   end
 
   # Is cache currently locked doing something?
+  #
+  # @return [Boolean] True if the cache is locked
   def locked?
     @mutex.locked?
   end
 
   # Put a value into the cache.
+  #
+  # @param key [Object] The key to store the value under
+  # @param value [Object] The value to store in the cache
+  # @param lifetime [Integer] Time in seconds until the key expires (default: never expires)
+  # @return [Object] The value stored
   def put(key, value, lifetime: 2**32)
     synchronized do
       @hash[key] = {
@@ -157,35 +208,65 @@ class Zache
 
   # Removes the value from the cache, by the provided key. If the key is absent
   # and the block is provided, the block will be called.
+  #
+  # @param key [Object] The key to remove from the cache
+  # @yield Block to call if the key is not found
+  # @return [Object] The removed value or the result of the block
   def remove(key)
     synchronized { @hash.delete(key) { yield if block_given? } }
   end
 
   # Remove all keys from the cache.
+  #
+  # @return [Hash] Empty hash
   def remove_all
     synchronized { @hash = {} }
   end
 
   # Remove all keys that match the block.
+  #
+  # @yield [key] Block that should return true for keys to be removed
+  # @yieldparam key [Object] The cache key to evaluate
+  # @return [Integer] Number of keys removed
   def remove_by
     synchronized do
+      count = 0
       @hash.each_key do |k|
-        @hash.delete(k) if yield(k)
+        if yield(k)
+          @hash.delete(k)
+          count += 1
+        end
       end
+      count
     end
   end
 
-  # Remove keys that are expired.
+  # Remove keys that are expired. This cleans up the cache by removing all keys
+  # where the lifetime has been exceeded.
+  #
+  # @return [Integer] Number of keys removed
   def clean
-    synchronized { @hash.delete_if { |key, _value| expired?(key) } }
+    synchronized do
+      size_before = @hash.size
+      @hash.delete_if { |key, _value| expired?(key) }
+      size_before - @hash.size
+    end
   end
 
+  # Returns TRUE if the cache is empty, FALSE otherwise.
+  #
+  # @return [Boolean] True if the cache is empty
   def empty?
     @hash.empty?
   end
 
   private
 
+  # Calculates or retrieves a cached value for the given key.
+  # @param key [Object] The key to store the value under
+  # @param lifetime [Integer] Time in seconds until the key expires
+  # @yield Block that provides the value if not cached
+  # @return [Object] The cached or newly calculated value
   def calc(key, lifetime)
     rec = @hash[key]
     rec = nil if expired?(key)
@@ -199,11 +280,15 @@ class Zache
     @hash[key][:value]
   end
 
+  # Executes a block within a synchronized context if sync is enabled.
+  # @param block [Proc] The block to execute
+  # @yield The block to execute in a synchronized context
+  # @return [Object] The result of the block
   def synchronized(&block)
     if @sync
       @mutex.synchronize(&block)
     else
-      block.call
+      yield
     end
   end
 end

data/logo.svg

@@ -16,4 +16,4 @@
             </g>
         </g>
     </g>
-</svg>
+</svg>

data/test/test__helper.rb

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2024 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 $stdout.sync = true
 
 require 'simplecov'
-SimpleCov.start
+require 'simplecov-cobertura'
+unless SimpleCov.running || ENV['PICKS']
+  SimpleCov.command_name('test')
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::CoberturaFormatter
+    ]
+  )
+  SimpleCov.minimum_coverage 90
+  SimpleCov.minimum_coverage_by_file 90
+  SimpleCov.start do
+    add_filter 'test/'
+    add_filter 'vendor/'
+    add_filter 'target/'
+    track_files 'lib/**/*.rb'
+    track_files '*.rb'
+  end
+end
+
 require 'minitest/autorun'
-require_relative '../lib/zache'
+require 'minitest/reporters'
+Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]

data/test/test_zache.rb

@@ -1,155 +1,138 @@
 # frozen_string_literal: true
 
-# (The MIT License)
-#
-# Copyright (c) 2018-2024 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
+require 'concurrent'
 require 'minitest/autorun'
+require 'securerandom'
 require 'threads'
 require 'timeout'
-require 'concurrent'
 require_relative '../lib/zache'
+require_relative 'test__helper'
 
 Thread.report_on_exception = true
 
 # Cache test.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
 # License:: MIT
 class ZacheTest < Minitest::Test
   def test_caches
     cache = Zache.new(sync: false)
-    first = cache.get(:hey, lifetime: 5) { Random.rand }
-    second = cache.get(:hey) { Random.rand }
-    assert(first == second)
+    first = cache.get(:hey, lifetime: 5) { rand }
+    second = cache.get(:hey) { rand }
+    assert_equal(first, second)
     assert_equal(1, cache.size)
   end
 
   def test_caches_and_expires
     cache = Zache.new
-    first = cache.get(:hey, lifetime: 0.01) { Random.rand }
+    first = cache.get(:hey, lifetime: 0.01) { rand }
     sleep 0.1
-    second = cache.get(:hey) { Random.rand }
-    assert(first != second)
+    second = cache.get(:hey) { rand }
+    refute_equal(first, second)
   end
 
   def test_calculates_age
     cache = Zache.new
-    cache.get(:hey) { Random.rand }
+    cache.get(:hey) { rand }
     sleep 0.1
-    assert(cache.mtime(:hey) < Time.now - 0.05)
+    assert_operator(cache.mtime(:hey), :<, Time.now - 0.05)
   end
 
   def test_caches_in_threads
     cache = Zache.new
     Threads.new(10).assert(100) do
-      cache.get(:hey, lifetime: 0.0001) { Random.rand }
+      cache.get(:hey, lifetime: 0.0001) { rand }
     end
   end
 
   def test_key_exists
     cache = Zache.new
-    cache.get(:hey) { Random.rand }
+    cache.get(:hey) { rand }
     exists_result = cache.exists?(:hey)
     not_exists_result = cache.exists?(:bye)
-    assert(exists_result == true)
-    assert(not_exists_result == false)
+    assert(exists_result)
+    refute(not_exists_result)
   end
 
   def test_put_and_exists
     cache = Zache.new
     cache.put(:hey, 'hello', lifetime: 0.1)
     sleep 0.2
-    assert(!cache.exists?(:hey))
+    refute(cache.exists?(:hey))
   end
 
   def test_remove_key
     cache = Zache.new
-    cache.get(:hey) { Random.rand }
-    cache.get(:wey) { Random.rand }
-    assert(cache.exists?(:hey) == true)
-    assert(cache.exists?(:wey) == true)
+    cache.get(:hey) { rand }
+    cache.get(:wey) { rand }
+    assert(cache.exists?(:hey))
+    assert(cache.exists?(:wey))
     cache.remove(:hey)
-    assert(cache.exists?(:hey) == false)
-    assert(cache.exists?(:wey) == true)
+    refute(cache.exists?(:hey))
+    assert(cache.exists?(:wey))
   end
 
   def test_remove_by_block
     cache = Zache.new
-    cache.get('first') { Random.rand }
-    cache.get('second') { Random.rand }
+    cache.get('first') { rand }
+    cache.get('second') { rand }
     cache.remove_by { |k| k == 'first' }
-    assert(cache.exists?('first') == false)
-    assert(cache.exists?('second') == true)
+    refute(cache.exists?('first'))
+    assert(cache.exists?('second'))
   end
 
   def test_remove_key_with_sync_false
     cache = Zache.new(sync: false)
-    cache.get(:hey) { Random.rand }
-    cache.get(:wey) { Random.rand }
-    assert(cache.exists?(:hey) == true)
-    assert(cache.exists?(:wey) == true)
+    cache.get(:hey) { rand }
+    cache.get(:wey) { rand }
+    assert(cache.exists?(:hey))
+    assert(cache.exists?(:wey))
     cache.remove(:hey)
-    assert(cache.exists?(:hey) == false)
-    assert(cache.exists?(:wey) == true)
+    refute(cache.exists?(:hey))
+    assert(cache.exists?(:wey))
   end
 
   def test_clean_with_threads
     cache = Zache.new
     Threads.new(300).assert(3000) do
-      cache.get(:hey) { Random.rand }
-      cache.get(:bye, lifetime: 0.01) { Random.rand }
+      cache.get(:hey) { rand }
+      cache.get(:bye, lifetime: 0.01) { rand }
       sleep 0.1
       cache.clean
     end
-    assert(cache.exists?(:hey) == true)
-    assert(cache.exists?(:bye) == false)
+    assert(cache.exists?(:hey))
+    refute(cache.exists?(:bye))
   end
 
   def test_clean
     cache = Zache.new
-    cache.get(:hey) { Random.rand }
-    cache.get(:bye, lifetime: 0.01) { Random.rand }
+    cache.get(:hey) { rand }
+    cache.get(:bye, lifetime: 0.01) { rand }
     sleep 0.1
     cache.clean
-    assert(cache.exists?(:hey) == true)
-    assert(cache.exists?(:bye) == false)
+    assert(cache.exists?(:hey))
+    refute(cache.exists?(:bye))
   end
 
   def test_clean_size
     cache = Zache.new
-    cache.get(:hey, lifetime: 0.01) { Random.rand }
+    cache.get(:hey, lifetime: 0.01) { rand }
     sleep 0.1
     cache.clean
-    assert(cache.empty?)
+    assert_empty(cache)
   end
 
   def test_clean_with_sync_false
     cache = Zache.new(sync: false)
-    cache.get(:hey) { Random.rand }
-    cache.get(:bye, lifetime: 0.01) { Random.rand }
+    cache.get(:hey) { rand }
+    cache.get(:bye, lifetime: 0.01) { rand }
     sleep 0.1
     cache.clean
-    assert(cache.exists?(:hey) == true)
-    assert(cache.exists?(:bye) == false)
+    assert(cache.exists?(:hey))
+    refute(cache.exists?(:bye))
   end
 
   def test_remove_absent_key
@@ -159,43 +142,43 @@ class ZacheTest < Minitest::Test
 
   def test_check_and_remove
     cache = Zache.new
-    cache.get(:hey, lifetime: 0) { Random.rand }
-    assert(!cache.exists?(:hey))
+    cache.get(:hey, lifetime: 0) { rand }
+    refute(cache.exists?(:hey))
   end
 
   def test_remove_all_with_threads
     cache = Zache.new
     Threads.new(10).assert(100) do |i|
-      cache.get(:"hey#{i}") { Random.rand }
-      assert(cache.exists?(:"hey#{i}") == true)
+      cache.get(:"hey#{i}") { rand }
+      assert(cache.exists?(:"hey#{i}"))
       cache.remove_all
     end
     10.times do |i|
-      assert(cache.exists?(:"hey#{i}") == false)
+      refute(cache.exists?(:"hey#{i}"))
     end
   end
 
   def test_remove_all_with_sync
     cache = Zache.new
-    cache.get(:hey) { Random.rand }
-    cache.get(:bye) { Random.rand }
+    cache.get(:hey) { rand }
+    cache.get(:bye) { rand }
     cache.remove_all
-    assert(cache.exists?(:hey) == false)
-    assert(cache.exists?(:bye) == false)
+    refute(cache.exists?(:hey))
+    refute(cache.exists?(:bye))
   end
 
   def test_remove_all_without_sync
     cache = Zache.new(sync: false)
-    cache.get(:hey) { Random.rand }
-    cache.get(:bye) { Random.rand }
+    cache.get(:hey) { rand }
+    cache.get(:bye) { rand }
     cache.remove_all
-    assert(cache.exists?(:hey) == false)
-    assert(cache.exists?(:bye) == false)
+    refute(cache.exists?(:hey))
+    refute(cache.exists?(:bye))
   end
 
   def test_puts_something_in
     cache = Zache.new(sync: false)
-    cache.get(:hey) { Random.rand }
+    cache.get(:hey) { rand }
     cache.put(:hey, 123)
     assert_equal(123, cache.get(:hey))
   end
@@ -216,19 +199,19 @@ class ZacheTest < Minitest::Test
       end
     end
     sleep 0.1
-    assert(cache.locked?)
+    assert_predicate(cache, :locked?)
     cache.get(:x) { 'second' }
-    assert(!cache.locked?)
+    refute_predicate(cache, :locked?)
     long.kill
   end
 
   def test_checks_locked_status_from_inside
     cache = Zache.new
     cache.get(:x) do
-      assert(cache.locked?)
+      assert_predicate(cache, :locked?)
       'done'
     end
-    assert(!cache.locked?)
+    refute_predicate(cache, :locked?)
   end
 
   def test_returns_dirty_result
@@ -293,4 +276,22 @@ class ZacheTest < Minitest::Test
       cache.get(:hey) { raise 'intentional' }
     end
   end
+
+  def test_returns_placeholder_in_eager_mode
+    cache = Zache.new
+    a = cache.get(:me, placeholder: 42, eager: true) do
+      sleep 0.1
+      43
+    end
+    assert_equal(42, a)
+    sleep 0.2
+    b = cache.get(:me)
+    assert_equal(43, b)
+  end
+
+  private
+
+  def rand
+    SecureRandom.uuid
+  end
 end