zache 0.13.1 → 0.14.0

data/README.md

@@ -1,66 +1,95 @@
-<img src="/logo.svg" width="64px" height="64px"/>
+# In Memory Cache for Ruby
 
 [![EO principles respected here](https://www.elegantobjects.org/badge.svg)](https://www.elegantobjects.org)
-[![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/zache)](http://www.rultor.com/p/yegor256/zache)
+[![DevOps By Rultor.com](https://www.rultor.com/b/yegor256/zache)](https://www.rultor.com/p/yegor256/zache)
 [![We recommend RubyMine](https://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
 
 [![rake](https://github.com/yegor256/zache/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/zache/actions/workflows/rake.yml)
-[![Gem Version](https://badge.fury.io/rb/zache.svg)](http://badge.fury.io/rb/zache)
+[![Gem Version](https://badge.fury.io/rb/zache.svg)](https://badge.fury.io/rb/zache)
 [![Maintainability](https://api.codeclimate.com/v1/badges/c136afe340fa94f14696/maintainability)](https://codeclimate.com/github/yegor256/zache/maintainability)
-[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/yegor256/zache/master/frames)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/yegor256/zache/master/frames)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/zache/blob/master/LICENSE.txt)
 [![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/zache.svg)](https://codecov.io/github/yegor256/zache?branch=master)
 [![Hits-of-Code](https://hitsofcode.com/github/yegor256/zache)](https://hitsofcode.com/view/github/yegor256/zache)
 
-It's a simple Ruby gem for in-memory cache.
+This is a simple Ruby gem for in-memory caching.
 Read [this blog post](https://www.yegor256.com/2019/02/05/zache.html)
-to understand what Zache is for.
+to understand what Zache is designed for.
 
 First, install it:
 
 ```bash
-$ gem install zache
+gem install zache
 ```
 
-Then, use it like this
+Then, use it like this:
 
 ```ruby
 require 'zache'
 zache = Zache.new
 # Expires in 5 minutes
-v = zache.get(:count, lifetime: 5 * 60) { expensive() }
+v = zache.get(:count, lifetime: 5 * 60) { expensive_calculation() }
 ```
 
+If you omit the `lifetime` parameter, the key will never expire.
+
 By default `Zache` is thread-safe. It locks the entire cache on each
-`get` call. You turn that off by using `sync` argument:
+`get` call. You can turn that off by using the `sync` argument:
 
 ```ruby
 zache = Zache.new(sync: false)
-v = zache.get(:count) { expensive() }
+v = zache.get(:count) { expensive_calculation() }
 ```
 
-You may use "dirty" mode, which will return you an expired value, while
-calculation is waiting. Say, you have something in the cache, but it's
-expired. Then, you call `get` with a long running block. The thread waits,
-while another one calls `get` again. That second thread won't wait, but will
-receive what's left in the cache. This is a very convenient mode for situations
-when you don't really care about data accuracy, but performance is an issue.
+You may use "dirty" mode, which will return an expired value while
+calculation is in progress. For example, if you have a value in the cache that's
+expired, and you call `get` with a long-running block, the thread waits.
+If another thread calls `get` again, that second thread won't wait, but will
+receive the expired value from the cache. This is a very convenient mode for situations
+where absolute data accuracy is less important than performance:
+
+```ruby
+zache = Zache.new(dirty: true)
+# Or enable dirty mode for a specific get call
+value = zache.get(:key, dirty: true) { expensive_calculation() }
+```
+
+The entire API is documented
+[here](https://www.rubydoc.info/github/yegor256/zache/master/Zache).
+Here are some additional useful methods:
+
+```ruby
+# Check if a key exists
+zache.exists?(:key)
 
-The entire API is documented [here](https://www.rubydoc.info/github/yegor256/zache/master/Zache)
-(there are many other convenient methods).
+# Remove a key
+zache.remove(:key)
 
-That's it.
+# Remove all keys
+zache.remove_all
+
+# Remove keys that match a condition
+zache.remove_by { |key| key.to_s.start_with?('temp_') }
+
+# Clean up expired keys
+zache.clean
+
+# Check if cache is empty
+zache.empty?
+```
 
 ## How to contribute
 
-Read [these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
-Make sure you build is green before you contribute
-your pull request. You will need to have [Ruby](https://www.ruby-lang.org/en/) 2.3+ and
+Read
+[these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
+Make sure your build is green before you contribute
+your pull request. You will need to have
+[Ruby](https://www.ruby-lang.org/en/) 2.3+ and
 [Bundler](https://bundler.io/) installed. Then:
 
-```
-$ bundle update
-$ bundle exec rake
+```bash
+bundle update
+bundle exec rake
 ```
 
 If it's clean and you don't see any error messages, submit your pull request.

data/REUSE.toml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+version = 1
+[[annotations]]
+path = [
+    "**/*.csv",
+    "**/*.jpg",
+    "**/*.json",
+    "**/*.md",
+    "**/*.pdf",
+    "**/*.png",
+    "**/*.svg",
+    "**/*.txt",
+    "**/*.vm",
+    "**/.DS_Store",
+    "**/.gitignore",
+    "**/.pdd",
+    "**/CNAME",
+    "**/Gemfile.lock",
+    ".DS_Store",
+    ".gitattributes",
+    ".gitignore",
+    ".pdd",
+    "Gemfile.lock",
+    "README.md",
+    "renovate.json",
+]
+precedence = "override"
+SPDX-FileCopyrightText = "Copyright (c) 2018-2025 Yegor Bugayenko"
+SPDX-License-Identifier = "MIT"

data/Rakefile

@@ -1,25 +1,10 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2023 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 'os'
+require 'qbash'
 require 'rubygems'
 require 'rake'
 require 'rake/clean'
@@ -34,7 +19,7 @@ def version
   Gem::Specification.load(Dir['*.gemspec'].first).version
 end
 
-task default: %i[clean test rubocop copyright]
+task default: %i[clean test picks rubocop yard]
 
 require 'rake/testtask'
 desc 'Run all unit tests'
@@ -44,24 +29,24 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = false
 end
 
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
-  rdoc.main = 'README.md'
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+desc 'Run them via Ruby, one by one'
+task :picks do
+  next if OS.windows?
+  %w[test lib].each do |d|
+    Dir["#{d}/**/*.rb"].each do |f|
+      qbash("bundle exec ruby #{Shellwords.escape(f)}", log: $stdout, env: { 'PICKS' => 'yes' })
+    end
+  end
+end
+
+require 'yard'
+desc 'Build Yard documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
 end
 
 require 'rubocop/rake_task'
 desc 'Run RuboCop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.fail_on_error = true
-  task.requires << 'rubocop-rspec'
-end
-
-task :copyright do
-  sh "grep -q -r '2018-#{Date.today.strftime('%Y')}' \
-    --include '*.rb' \
-    --include '*.txt' \
-    --include 'Rakefile' \
-    ."
 end

data/lib/zache.rb

@@ -1,26 +1,7 @@
 # frozen_string_literal: true
 
-# (The MIT License)
-#
-# Copyright (c) 2018-2023 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-2023 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] = {
@@ -155,33 +206,67 @@ class Zache
     end
   end
 
-  # Removes the value from the hash, by the provied key. If the key is absent
+  # 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?(value) } }
+    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)
@@ -195,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-2023 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]