zache 0.15.0 → 0.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2c6bee2ddda59d3ddba9115b7f1eaf2037fe28cc217bec57aa1bc2dfb91b660
-  data.tar.gz: 3b1fafcbe3afd075992c0a36df45ca5b51228bd4d1d9c5e086c7523b462ef343
+  metadata.gz: e9cc0b6c8fece285753b4a7bc12bc296f9cab08b7adacee09dd888f556263e4c
+  data.tar.gz: 722f973b74565b70225b44f1de8f6c63ddccf18bbb534ba31a9b1c4c24bbb60d
 SHA512:
-  metadata.gz: 24f22827fe4b5ea546ea2e121b8aaf35c2646ecbcc4ec7134b0d27693bfa4345d29829d29db1d417ab7759c556f3c21c8cea151f267fdaa282d45d69b8e53a57
-  data.tar.gz: 2a8a4c661c2424a126c8b309825d8d558206db695359793191caf5c1b3e348a147381149258418e7e7469a3e9bfdab30f0164eedfe59383012ed8173fae5fbdf
+  metadata.gz: 9ff5b92b44b011b8cb689538e7d4eade3d7d216a89a94b0b85da769bece6610ba9aa27e143f766bbac0b736de65bd7d7faba803b1af4c93876e02913843b819a
+  data.tar.gz: dfb50539962ba04cf80db2ceff76dc01abfa3596fd3dc46a21e7d23cc03219e52098a2c77525d0e1ed35b4ea6b31fed6a5f548c228f1105639d66852c4594ac8

data/Gemfile

@@ -12,11 +12,12 @@ gem 'minitest-reporters', '~>1.7', require: false
 gem 'os', '>0', require: false
 gem 'qbash', '>0', require: false
 gem 'rake', '~>13.2', require: false
+gem 'rdoc', '~>6.15', require: false
 gem 'rubocop', '~>1.75', require: false
-gem 'rubocop-minitest', '>0', require: false
-gem 'rubocop-performance', '>0', require: false
-gem 'rubocop-rake', '>0', require: false
+gem 'rubocop-minitest', '~>0.38', require: false
+gem 'rubocop-performance', '~>1.25', require: false
+gem 'rubocop-rake', '~>0.7', require: false
 gem 'simplecov', '~>0.22', require: false
-gem 'simplecov-cobertura', '~>2.1', require: false
+gem 'simplecov-cobertura', '~>3.0', require: false
 gem 'threads', '~>0.4', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -8,40 +8,51 @@ GEM
   specs:
     ansi (1.5.0)
     ast (2.4.3)
-    backtrace (0.4.0)
+    backtrace (0.4.1)
     builder (3.3.0)
     concurrent-ruby (1.3.5)
+    date (3.5.0)
     docile (1.4.1)
-    elapsed (0.0.1)
-      loog (> 0)
-      tago (> 0)
-    json (2.10.2)
-    language_server-protocol (3.17.0.4)
+    elapsed (0.2.0)
+      loog (~> 0.6)
+      tago (~> 0.1)
+    erb (6.0.0)
+    json (2.16.0)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    loog (0.6.0)
-    minitest (5.25.5)
+    logger (1.7.0)
+    loog (0.6.1)
+      logger (~> 1.0)
+    minitest (5.26.2)
     minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
     os (1.1.4)
-    parallel (1.26.3)
-    parser (3.3.7.4)
+    parallel (1.27.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
-    qbash (0.4.0)
+    prism (1.6.0)
+    psych (5.2.6)
+      date
+      stringio
+    qbash (0.4.8)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)
       tago (> 0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.10.0)
-    rexml (3.4.1)
-    rubocop (1.75.2)
+    rake (13.3.1)
+    rdoc (6.16.1)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.81.7)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -49,20 +60,20 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-minitest (0.38.0)
+    rubocop-minitest (0.38.2)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-performance (1.25.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
@@ -71,18 +82,20 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (2.1.0)
+    simplecov-cobertura (3.1.0)
       rexml
       simplecov (~> 0.19)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    tago (0.1.0)
-    threads (0.4.1)
+    stringio (3.1.8)
+    tago (0.4.0)
+    threads (0.5.0)
       backtrace (~> 0)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
     yard (0.9.37)
 
 PLATFORMS
@@ -101,12 +114,13 @@ DEPENDENCIES
   os (> 0)
   qbash (> 0)
   rake (~> 13.2)
+  rdoc (~> 6.15)
   rubocop (~> 1.75)
-  rubocop-minitest (> 0)
-  rubocop-performance (> 0)
-  rubocop-rake (> 0)
+  rubocop-minitest (~> 0.38)
+  rubocop-performance (~> 1.25)
+  rubocop-rake (~> 0.7)
   simplecov (~> 0.22)
-  simplecov-cobertura (~> 2.1)
+  simplecov-cobertura (~> 3.0)
   threads (~> 0.4)
   yard (~> 0.9)
   zache!

data/README.md

@@ -13,8 +13,7 @@
 [![Hits-of-Code](https://hitsofcode.com/github/yegor256/zache)](https://hitsofcode.com/view/github/yegor256/zache)
 
 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 designed for.
+Read this [blog post] to understand what Zache is designed for.
 
 First, install it:
 
@@ -31,22 +30,26 @@ zache = Zache.new
 v = zache.get(:count, lifetime: 5 * 60) { expensive_calculation() }
 ```
 
-If you omit the `lifetime` parameter, the key will never expire.
+If you omit the `lifetime` parameter or set it to `nil`,
+  the key will never expire.
 
-By default `Zache` is thread-safe. It locks the entire cache on each
-`get` call. You can turn that off by using the `sync` argument:
+By default `Zache` is thread-safe.
+It locks the entire cache on each `get` call.
+You can turn that off by using the `sync` argument:
 
 ```ruby
 zache = Zache.new(sync: false)
 v = zache.get(:count) { expensive_calculation() }
 ```
 
-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:
+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)
@@ -54,8 +57,19 @@ zache = Zache.new(dirty: true)
 value = zache.get(:key, dirty: true) { expensive_calculation() }
 ```
 
-The entire API is documented
-[here](https://www.rubydoc.info/github/yegor256/zache/master/Zache).
+You may use "eager" mode with a placeholder value to return immediately
+  while the calculation happens in the background.
+The cache returns the placeholder instantly and spawns
+  a thread to calculate the actual value.
+This is useful when you need to avoid blocking
+  while expensive operations complete:
+
+```ruby
+# Returns 0 immediately, calculates in background
+value = zache.get(:key, eager: true, placeholder: 0) { expensive_calculation() }
+```
+
+The entire API is [documented][rubydoc].
 Here are some additional useful methods:
 
 ```ruby
@@ -80,12 +94,11 @@ zache.empty?
 
 ## How to contribute
 
-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:
+Read these [guidelines].
+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:
 
 ```bash
 bundle update
@@ -93,3 +106,7 @@ bundle exec rake
 ```
 
 If it's clean and you don't see any error messages, submit your pull request.
+
+[blog post]: https://www.yegor256.com/2019/02/05/zache.html
+[rubydoc]: https://www.rubydoc.info/github/yegor256/zache/master/Zache
+[guidelines]: https://www.yegor256.com/2014/04/15/github-guidelines.html

data/REUSE.toml

@@ -4,6 +4,18 @@
 version = 1
 [[annotations]]
 path = [
+    ".DS_Store",
+    ".gitattributes",
+    ".gitignore",
+    ".pdd",
+    "**.json",
+    "**.md",
+    "**.png",
+    "**.svg",
+    "**.txt",
+    "**/.DS_Store",
+    "**/.gitignore",
+    "**/.pdd",
     "**/*.csv",
     "**/*.jpg",
     "**/*.json",
@@ -13,15 +25,8 @@ path = [
     "**/*.svg",
     "**/*.txt",
     "**/*.vm",
-    "**/.DS_Store",
-    "**/.gitignore",
-    "**/.pdd",
     "**/CNAME",
     "**/Gemfile.lock",
-    ".DS_Store",
-    ".gitattributes",
-    ".gitignore",
-    ".pdd",
     "Gemfile.lock",
     "README.md",
     "renovate.json",

data/Rakefile

@@ -8,8 +8,9 @@ require 'qbash'
 require 'rubygems'
 require 'rake'
 require 'rake/clean'
+require 'shellwords'
 
-CLEAN = FileList['coverage']
+CLEAN.include('coverage')
 
 def name
   @name ||= File.basename(Dir['*.gemspec'].first, '.*')
@@ -27,6 +28,9 @@ Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/test_*.rb'
   test.verbose = false
+  test.options = '--verbose' if ENV['VERBOSE']
+  # Disable minitest plugins on Windows to avoid gem conflicts
+  ENV['MT_NO_PLUGINS'] = '1' if OS.windows?
 end
 
 desc 'Run them via Ruby, one by one'
@@ -43,6 +47,7 @@ require 'yard'
 desc 'Build Yard documentation'
 YARD::Rake::YardocTask.new do |t|
   t.files = ['lib/**/*.rb']
+  t.options = ['--fail-on-warning']
 end
 
 require 'rubocop/rake_task'

data/lib/zache.rb

@@ -29,8 +29,6 @@ class Zache
     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(*)
@@ -38,24 +36,19 @@ class Zache
     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.
-    # @param [Object] key Ignored
+    # @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
 
@@ -97,7 +90,7 @@ class Zache
   #
   # @return [Integer] Number of keys in the cache
   def size
-    @hash.size
+    synchronize_all { @hash.size }
   end
 
   # Gets the value from the cache by the provided key.
@@ -122,30 +115,11 @@ class Zache
   # @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?(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
+      return get_dirty_value(key) if should_return_dirty?(key, dirty)
+      return get_eager(key, lifetime, placeholder, &block) if eager
+      synchronize_one(key) { calc(key, lifetime, &block) }
     else
-      rec = @hash[key]
-      if expired?(key)
-        return rec[:value] if dirty || @dirty
-        @hash.delete(key)
-        rec = nil
-      end
-      raise 'The key is absent in the cache' if rec.nil?
-      rec[:value]
+      get_without_block(key, dirty)
     end
   end
 
@@ -157,12 +131,14 @@ class Zache
   # @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
-      @hash.delete(key)
-      rec = nil
+    synchronize_all do
+      rec = @hash[key]
+      if expired_unsafe?(key) && !dirty && !@dirty
+        @hash.delete(key)
+        rec = nil
+      end
+      !rec.nil?
     end
-    !rec.nil?
   end
 
   # Checks whether the key exists in the cache and is expired. If the
@@ -171,8 +147,7 @@ class Zache
   # @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]
+    synchronize_all { expired_unsafe?(key) }
   end
 
   # Returns the modification time of the key, if it exists.
@@ -181,8 +156,10 @@ class Zache
   # @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]
+    synchronize_all do
+      rec = @hash[key]
+      rec.nil? ? Time.now : rec[:start]
+    end
   end
 
   # Is key currently locked doing something?
@@ -190,7 +167,7 @@ class Zache
   # @param [Object] key The key to check
   # @return [Boolean] True if the cache is locked
   def locked?(key)
-    @locks[key]&.locked?
+    synchronize_all { @locks[key]&.locked? }
   end
 
   # Put a value into the cache.
@@ -216,14 +193,19 @@ class Zache
   # @yield Block to call if the key is not found
   # @return [Object] The removed value or the result of the block
   def remove(key)
-    synchronize_one(key) { @hash.delete(key) { yield if block_given? } }
+    result = synchronize_one(key) { @hash.delete(key) { yield if block_given? } }
+    synchronize_all { @locks.delete(key) }
+    result
   end
 
   # Remove all keys from the cache.
   #
   # @return [Hash] Empty hash
   def remove_all
-    synchronize_all { @hash = {} }
+    synchronize_all do
+      @hash = {}
+      @locks = {}
+    end
   end
 
   # Remove all keys that match the block.
@@ -235,10 +217,10 @@ class Zache
     synchronize_all do
       count = 0
       @hash.each_key do |k|
-        if yield(k)
-          @hash.delete(k)
-          count += 1
-        end
+        next unless yield(k)
+        @hash.delete(k)
+        @locks.delete(k)
+        count += 1
       end
       count
     end
@@ -251,7 +233,11 @@ class Zache
   def clean
     synchronize_all do
       size_before = @hash.size
-      @hash.delete_if { |key, _value| expired?(key) }
+      @hash.delete_if do |key, _value|
+        expired = expired_unsafe?(key)
+        @locks.delete(key) if expired
+        expired
+      end
       size_before - @hash.size
     end
   end
@@ -260,11 +246,89 @@ class Zache
   #
   # @return [Boolean] True if the cache is empty
   def empty?
-    @hash.empty?
+    synchronize_all { @hash.empty? }
   end
 
   private
 
+  # Checks if dirty value should be returned for a locked key
+  # @param key [Object] The key to check
+  # @param dirty [Boolean] Whether dirty reads are allowed
+  # @return [Boolean] True if dirty value should be returned
+  def should_return_dirty?(key, dirty)
+    (dirty || @dirty) && locked?(key) && expired_value?(key)
+  end
+
+  # Checks if key has an expired value in cache
+  # @param key [Object] The key to check
+  # @return [Boolean] True if key exists and is expired
+  def expired_value?(key)
+    synchronize_all do
+      rec = @hash[key]
+      !rec.nil? && expired_unsafe?(key)
+    end
+  end
+
+  # Gets the dirty cached value without recalculation
+  # @param key [Object] The key to retrieve
+  # @return [Object] The cached value
+  def get_dirty_value(key)
+    synchronize_all { @hash[key][:value] }
+  end
+
+  # Handles eager mode get operation
+  # @param key [Object] The key to retrieve
+  # @param lifetime [Integer] Time in seconds until the key expires
+  # @param placeholder [Object] The placeholder to return immediately
+  # @yield Block that provides the value
+  # @return [Object] The placeholder value
+  def get_eager(key, lifetime, placeholder, &block)
+    return synchronize_all { @hash[key][:value] } if synchronize_all { @hash.key?(key) }
+
+    put(key, placeholder, lifetime: 0)
+    spawn_calculation_thread(key, lifetime, &block)
+    placeholder
+  end
+
+  # Spawns a background thread to calculate the value
+  # @param key [Object] The key to calculate for
+  # @param lifetime [Integer] Time in seconds until the key expires
+  # @yield Block that provides the value
+  def spawn_calculation_thread(key, lifetime, &block)
+    Thread.new do
+      synchronize_one(key) { calc(key, lifetime, &block) }
+    rescue StandardError => e
+      cleanup_failed_key(key)
+      raise e
+    end
+  end
+
+  # Cleans up a key after calculation failure
+  # @param key [Object] The key to clean up
+  def cleanup_failed_key(key)
+    synchronize_all do
+      @hash.delete(key)
+      @locks.delete(key)
+    end
+  end
+
+  # Gets value without a block (retrieval only mode)
+  # @param key [Object] The key to retrieve
+  # @param dirty [Boolean] Whether to return expired values
+  # @return [Object] The cached value
+  def get_without_block(key, dirty)
+    synchronize_all do
+      rec = @hash[key]
+      if expired_unsafe?(key)
+        return rec[:value] if dirty || @dirty
+        @hash.delete(key)
+        rec = nil
+      end
+      raise 'The key is absent in the cache' if rec.nil?
+      rec[:value]
+    end
+  end
+
   # 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
@@ -272,15 +336,25 @@ class Zache
   # @return [Object] The cached or newly calculated value
   def calc(key, lifetime)
     rec = @hash[key]
-    rec = nil if expired?(key)
+    rec = nil if expired_unsafe?(key)
     if rec.nil?
-      @hash[key] = {
+      rec = {
         value: yield,
         start: Time.now,
         lifetime: lifetime
       }
+      @hash[key] = rec
     end
-    @hash[key][:value]
+    rec[:value]
+  end
+
+  # Internal method that checks if a key is expired without acquiring locks.
+  # This should only be called from within a synchronized block.
+  # @param key [Object] The key to check in the cache
+  # @return [Boolean] True if the key exists and is expired
+  def expired_unsafe?(key)
+    rec = @hash[key]
+    !rec.nil? && rec[:lifetime] && rec[:start] < Time.now - rec[:lifetime]
   end
 
   # Executes a block within a synchronized context if sync is enabled.
@@ -299,9 +373,9 @@ class Zache
   # @return [Object] The result of the block
   def synchronize_one(key, &block)
     return yield unless @sync
-    @mutex.synchronize do
+    mtx = @mutex.synchronize do
       @locks[key] ||= Mutex.new
     end
-    @locks[key].synchronize(&block)
+    mtx.synchronize(&block)
   end
 end

data/zache.gemspec

@@ -8,14 +8,14 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.required_ruby_version = '>= 2.5'
   s.name = 'zache'
-  s.version = '0.15.0' # Version should be updated before release
+  s.version = '0.15.2' # Version should be updated before release
   s.license = 'MIT'
   s.summary = 'In-memory Cache'
   s.description = 'Zero-footprint in-memory thread-safe cache'
   s.authors = ['Yegor Bugayenko']
   s.email = 'yegor256@gmail.com'
   s.homepage = 'https://github.com/yegor256/zache'
-  s.files = `git ls-files`.split($RS)
+  s.files = `git ls-files | grep -v -E '^(test/|\\.|renovate)'`.split($RS)
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md']
   s.metadata['rubygems_mfa_required'] = 'true'