zache 0.13.2 → 0.15.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,61 @@
 # {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
 
-    def locked?
+    # Always returns false.
+    # @param [Object] key Ignored
+    # @return [Boolean] Always returns false
+    def locked?(_key)
       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,15 +80,22 @@ 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
     @dirty = dirty
     @mutex = Mutex.new
+    @locks = {}
   end
 
   # Total number of keys currently in cache.
+  #
+  # @return [Integer] Number of keys in the cache
   def size
     @hash.size
   end
@@ -90,17 +104,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) }
+      return @hash[key][:value] if (dirty || @dirty) && locked?(key) && expired?(key) && @hash.key?(key)
+      if eager
+        return @hash[key][:value] if @hash.key?(key)
+        put(key, placeholder, lifetime: 0)
+        Thread.new do
+          synchronize_one(key) do
+            calc(key, lifetime, &block)
+          end
+        end
+        placeholder
+      else
+        synchronize_one(key) do
+          calc(key, lifetime, &block)
+        end
+      end
     else
       rec = @hash[key]
       if expired?(key)
@@ -114,8 +150,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 +167,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,19 +177,30 @@ 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?
-  def locked?
-    @mutex.locked?
+  # Is key currently locked doing something?
+  #
+  # @param [Object] key The key to check
+  # @return [Boolean] True if the cache is locked
+  def locked?(key)
+    @locks[key]&.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
+    synchronize_one(key) do
       @hash[key] = {
         value: value,
         start: Time.now,
@@ -157,35 +211,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? } }
+    synchronize_one(key) { @hash.delete(key) { yield if block_given? } }
   end
 
   # Remove all keys from the cache.
+  #
+  # @return [Hash] Empty hash
   def remove_all
-    synchronized { @hash = {} }
+    synchronize_all { @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
+    synchronize_all 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) } }
+    synchronize_all 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 +283,25 @@ class Zache
     @hash[key][:value]
   end
 
-  def synchronized(&block)
-    if @sync
-      @mutex.synchronize(&block)
-    else
-      block.call
+  # 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 synchronize_all(&block)
+    return yield unless @sync
+    @mutex.synchronize(&block)
+  end
+
+  # Executes a block within a synchronized context if sync is enabled.
+  # @param key [Object] The object to sync
+  # @param block [Proc] The block to execute
+  # @yield The block to execute in a synchronized context
+  # @return [Object] The result of the block
+  def synchronize_one(key, &block)
+    return yield unless @sync
+    @mutex.synchronize do
+      @locks[key] ||= Mutex.new
     end
+    @locks[key].synchronize(&block)
   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]