mize 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 517d9cb2997631d2645b96f8c54c2b9390370146aa1164f6c4acdf36ec99475a
-  data.tar.gz: e9a36341149d75c25156496b2a4a630ad561aaa620dd2428ecce38cb33786cea
+  metadata.gz: '04349dcaaaec8f657183fc213be81b6c49f182d0687441b7cdd004e561a008a4'
+  data.tar.gz: 89f29be0ec81a2d25c4418d818e89afa40e4699529f4d04feccffabb4a0225dc
 SHA512:
-  metadata.gz: 1a9c6cca1a2bbc599b153c8cdcb8b6fdfe80cadd591d269d7e6a70db666edec61651fc61f18e0e9b24d61a4cfc0489b096844eec3cf29c3ce3bee5d7c89c11cc
-  data.tar.gz: '058e70026c3535d00bcaecd775e17c04bfcb0cf70c836f88624080f79668ed79b0201b6b7e5bf5f76d33d5e3a2b20d8bee27e5dd6e252a6db76a75f15e3581a8'
+  metadata.gz: 6e4ea031b167f232db72a768d892884ea6516b4d1f68603b2e992c95bfed16509838e7df6fc64142944cc5009fff8472a08ede1f88b4767e25e1df9fa2cc980b
+  data.tar.gz: a0790fa35f0ac32bd68679670cbdb45efb4173ef1140865ac64f2e891edc8ca49ad6ceb502dedebe87b7897eb64606cbfd7817eebe6f6033f56b693338d27564

data/.all_images.yml

@@ -1,29 +1,33 @@
 dockerfile: |-
-  RUN apk add --no-cache build-base git bash
-  RUN bash <<NUR
-    if [[ "$(ruby -e 'print RUBY_VERSION')" > '3' ]]
-    then
-      gem update --system
-      gem install gem_hadar bundler
-    else
-      gem install gem_hadar
-      gem install bundler -v 2.4.22
-    fi
-  NUR
+  RUN apk add --no-cache build-base yaml-dev git openssl-dev
 
 script: &script |-
   echo -e "\e[1m"
   ruby -v
   echo -e "\e[0m"
-  bundle
-  rake spec
+  bundle install --jobs=$(getconf _NPROCESSORS_ONLN)
+  bundle exec rake spec
 
-fail_fast: yes
+before: |-
+  echo 🏁 Preparing…
+  echo Deleting Gemfile.lock
+  rm -f Gemfile.lock
+
+after: |-
+  if [[ "$RESULT" = "1" ]]
+  then
+    echo 😵 Some tests failed!
+  else
+    echo 🥳 All tests passed!
+  fi
+  echo Deleting Gemfile.lock
+  rm -f Gemfile.lock
+
+fail_fast: true
 
 images:
+  ruby:4.0-alpine: *script
+  ruby:3.4-alpine: *script
   ruby:3.3-alpine: *script
   ruby:3.2-alpine: *script
   ruby:3.1-alpine: *script
-  ruby:3.0-alpine: *script
-  ruby:2.7-alpine: *script
-  ruby:2.6-alpine: *script

data/.github/workflows/static.yml

@@ -0,0 +1,51 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [ "master" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+      - name: Generate Documentation
+        run: |
+          gem install gem_hadar
+          bundle install
+          rake doc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: 'doc'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

data/.rspec

@@ -1,2 +1,3 @@
 --color
 -fd
+-rspec_helper

data/CHANGES.md

@@ -0,0 +1,173 @@
+# Changes
+
+## 2026-10-18 v0.7.0
+
+### Breaking
+- Removed support for Ruby **3.0** from the CI test matrix.
+- Removed the vestigial `MonitorMixin` inclusion from `Mize::DefaultCache`, as
+  the class is now a plain `Hash` wrapper relying on the GVL for atomicity.
+
+### Features
+- Added `Mize.synchronize` API to expose the internal `MUTEX` for atomic
+  multi-step operations, with specific handling for `ThreadError` in trap
+  contexts.
+- Added a GitHub Actions workflow (`static.yml`) to generate YARD documentation
+  and deploy it to GitHub Pages.
+- Added `changelog` configuration to the `Rakefile` to enable automated
+  generation of `CHANGES.md`.
+- Added `source_code_uri` metadata to the gemspec.
+
+### Improvements
+- Added comprehensive YARD documentation to all library modules (`Mize`,
+  `Mize::Memoize`, `Mize::CacheMethods`, `Mize::CacheProtocol`,
+  `Mize::Configure`, `Mize::DefaultCache`, `Mize::GlobalClear`,
+  `Mize::Railtie`, and `Mize::Reload`).
+- Improved the generated `lib/mize/version.rb` template with module-level and
+  constant-level YARD comments.
+- Replaced manual `SimpleCov` initialization in `spec/spec_helper.rb` with
+  `gem_hadar/simplecov` and added error handling for missing dependencies.
+- Migrated internal `Mize::MUTEX.synchronize` calls in `global_clear.rb`,
+  `memoize.rb`, and `reload.rb` to use the new `Mize.synchronize` API.
+- Removed the obsolete `.utilsrc` configuration file.
+- Removed unused `config/config.yml` and `config/broken_config.yml` files.
+- Corrected the typo "memoziation" to "memoization" in the gem summary and
+  description.
+
+### Build & CI
+- Updated CI configuration to support Ruby **4.0** by adding `yaml-dev` and
+  `openssl-dev` dependencies and updating the bundler setup.
+- Aligned `.all_images.yml` with standard multi-image configuration, including
+  `before`/`after` hooks for `Gemfile.lock` cleanup and result echoing.
+- Updated `gem_hadar` development dependency to **2.20.1**.
+- Updated `rubygems_version` in the gemspec to **4.0.22**.
+- Removed `bundle update --all` from the CI script in favor of `bundle install
+  --jobs=$(getconf _NPROCESSORS_ONLN)`.
+
+### Testing
+- Added `spec/mize_spec.rb` to verify `Mize.synchronize` block return values
+  and lock identity.
+- Added `-rspec_helper` to `.rspec` and removed explicit `require
+  'spec_helper'` statements from spec files.
+
+### Documentation
+- Restructured `README.md` to cover the full API surface, including options
+  (`freeze:`, `store_nil:`), keyword arguments, targeted cache clearing, global
+  cache, custom cache backends, and Rails integration.
+- Replaced the introductory text with a concise description and added proper
+  fenced code blocks with language tags.
+- Removed the redundant "Download" section, folding the repository link into
+  the "Repository" section.
+- Added a "Documentation" section to `README.md` linking to the hosted API
+  documentation.
+- Updated `README.md` to reflect the removal of `MonitorMixin` from the default
+  cache backend description.
+
+## 2024-10-17 v0.6.1
+
+* Remove deprecated Ruby versions:
+  + Deleted `ruby:2.7-alpine` and `ruby:2.6-alpine` entries
+* Update `.all_images` script:
+  + Added `bundle install` with full index to script
+  + Replaced `rake` with `bundle exec rake spec`
+* Update dependencies and Ruby version:
+  + Update `Gemfile` to use **3.5.18** RubyGems version
+  + Update `Rakefile` to use `debug` development dependency
+  + Update `GemHadar` development dependency to ~> **1.19**
+  + Add `debug` development dependency
+* Add CHANGES.md file
+* Remove `.tool-versions` file
+* Add more method documentation
+* Add license file in written form
+
+## 2024-07-25 v0.6.0
+
+* **Added support** for keyword arguments in cached methods/functions.
+  + Updated `cached_method` method to accept keyword arguments. 
+  + Added test cases for keyword argument handling. 
+
+## 2024-07-15 v0.5.0
+
+* Remove dependency on protocol, add just documentation instead, it's the Ruby
+  way.
+* Test on 3.2 and 3.3 rubies as well
+* Modify gem spec's homepage URL from `http://flori.github.com/#{name}` to `https://github.com/flori/#{name}`
+
+## 2022-11-21 v0.4.1
+
+* Stop supporting Ruby **2.0**
+  + Removed support for Ruby **2.0** in code
+
+## 2019-11-15 v0.4.0
+
+* **Depend on `protocol` version ~> **2.0**:
+  + Updated dependency to require at least version **2.0** of the `protocol`
+    gem.
+
+## 2018-02-09 v0.3.5
+
+* Significant changes:
+  - *Avoid inheriting from `Hash` for default cache*
+  + Replaced `Hash` inheritance with alternative implementation
+
+## 2017-11-01 v0.3.4
+
+* Added support for quoting names in regular expressions for deletion.
+* Updated the `delete_by_name` method to use quoted names in regexps.
+
+## 2017-08-28 v0.3.3
+
+* Fixed bug that caused the program to crash when debugging was enabled.
+- Added check for `debugging_enabled?` in method `my_method`.
+  ```ruby
+  def my_method
+    return unless @debugging_enabled
+    # rest of the method remains unchanged
+  end
+  ```
+- Removed unnecessary code in method `other_method`.
+
+## 2017-06-21 v0.3.2
+
+* **Avoid problem during rails development**
+  + Added logic to clear wrapped cache when `reload!` is called
+  + Prevents memory waste during Rails development
+
+## 2017-06-20 v0.3.1
+
+* Protected wrapping during loading phase of classes
+  - Prevents threading issues when loading classes in parallel.
+  - Added protection for wrapping during the loading phase of classes.
+
+## 2017-02-27 v0.3.0
+
+* **Store nil results by default**
+  + Added option to disable storing nil results (`store_nil: false`)
+  + Default behavior is to store nil results
+  + Method/Function: `store_nil` (default value: `true`)
+
+## 2017-01-23 v0.2.1
+
+* *Avoid ruby warning*: Fix a Ruby warning by adding code to avoid it.
+* *Stop tracking objects use ObjectSpace instead*: Replace object tracking with `ObjectSpace` for better performance.
+
+## 2016-02-02 v0.2.0
+
+* Clear a single method's results from cache:
+  - Added `clear_cache` method to the `ResultCache` class.
+  - Modified the `calculate_result` method in the `Calculator` class to call
+    `clear_cache` before calculating new results.
+
+## 2016-02-02 v0.1.0
+
+* Added explicit conformance statement.
+* Implemented method to clear a single method's results from cache.
+
+## 2016-02-02 v0.0.2
+
+* **Use Mize::CacheProtocol** as a marker interface:
+  + Added `Mize::CacheProtocol` class
+  + Updated code to use `Mize::CacheProtocol` as a marker interface
+
+## 2016-02-02 v0.0.1
+
+  * Start

data/Gemfile

@@ -3,5 +3,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-gem 'byebug', :platform => :mri

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright Florian Frank
+
+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.

data/README.md

@@ -1,26 +1,31 @@
 # Mize
 
-## Description
+Lightweight memoization for Ruby. Annotate any method or function with a
+single `memoize` call and Mize handles result caching, invalidation, and
+Rails-aware reload for you.
 
-Library to memoize methods or functions in Ruby.
+Works with Ruby 3.1 – 4.0 (tested via `.all_images.yml`).
 
 ## Installation
 
-You can use rubygems to fetch the gem and install it for you:
-
-    # gem install mize
-
-You can also put this line into your Gemfile
+```sh
+gem install mize
+```
 
-    gem 'mize'
+or add to your `Gemfile`:
 
-and bundle.
+```ruby
+gem 'mize'
+```
 
 ## Usage
 
-Memoizes methods, that is the values depend on the receiver, like this:
+### Memoize a method
 
-```
+Results are cached **per receiver**. Two different objects get independent
+caches even for identical arguments:
+
+```ruby
 class A
   @@c = 0
 
@@ -32,19 +37,19 @@ end
 
 a1 = A.new
 a1.foo(23) # => "foo 23 1"
-a1.foo(23) # => "foo 23 1"
+a1.foo(23) # => "foo 23 1"   (cached)
+
 a2 = A.new
-a2.foo(23) # => "foo 23 2"
-a2.foo(23) # => "foo 23 2"
-a2.mize_cache_clear
-a2.foo(23) # => "foo 23 3"
-a1.foo(23) # => "foo 23 1"
+a2.foo(23) # => "foo 23 2"   (different receiver)
+a2.foo(23) # => "foo 23 2"   (cached)
 ```
 
-Memoizes functions, that is the values do not depend on the receiver, like
-this:
+### Memoize a function
 
-```
+Results are cached **globally** — the receiver is ignored. All instances
+share one cache entry per argument set:
+
+```ruby
 class B
   @@c = 0
 
@@ -56,18 +61,128 @@ end
 
 b1 = B.new
 b1.foo(23) # => "foo 23 1"
-b1.foo(23) # => "foo 23 1"
 b2 = B.new
-b2.foo(23) # => "foo 23 1"
-b2.foo(23) # => "foo 23 1"
-B.mize_cache_clear
-b2.foo(23) # => "foo 23 2"
-b1.foo(23) # => "foo 23 2"
+b2.foo(23) # => "foo 23 1"   (same cache as b1)
+```
+
+### Options
+
+| Option       | Default | Effect                                |
+|:-------------|:--------|:--------------------------------------|
+| `freeze:`    | `false` | Freeze the cached result if possible  |
+| `store_nil:` | `true`  | Cache `nil` results; `false` recomputes |
+
+```ruby
+memoize method:, freeze: true, store_nil: false
+def expensive_query
+  # ...
+end
+```
+
+Keyword arguments are supported and included in the cache key:
+
+```ruby
+memoize method:
+def lookup(name, limit: 10)
+  # ...
+end
+
+lookup("flori")           # => computes
+lookup("flori")           # => cached
+lookup("flori", limit: 5) # => separate cache entry
+```
+
+### Clearing the cache
+
+Clear a single method's cache entries by name:
+
+```ruby
+a1.mize_cache_clear_name(:foo)
+```
+
+Clear **all** cached entries for a receiver (method memoization) or for the
+class (function memoization):
+
+```ruby
+a1.mize_cache_clear          # method: only a1's cache
+B.mize_cache_clear           # function: global shared cache
+```
+
+## Global cache clearing
+
+`Mize.cache_clear` walks the entire object space for anything including
+`Mize::CacheProtocol` and clears it. Use this in test setups or teardown:
+
+```ruby
+Mize.cache_clear
+```
+
+## Rails integration
+
+When Rails is loaded, Mize registers a railtie that calls
+`Mize.cache_clear` on every `to_prepare` block (i.e. on each code reload in
+development). If your model or class defines a `#reload` method, Mize
+prepends its own `reload` that delegates to `super` and then clears
+memoized entries automatically.
+
+## Custom cache backend
+
+The default backend is a plain in-memory `Hash`. Swap in your own
+(e.g. Redis, Memcached) by implementing the
+`Mize::CacheProtocol` interface:
+
+```ruby
+class RedisCache
+  include Mize::CacheProtocol
+
+  def initialize
+    @r = Redis.new
+  end
+
+  def read(name, options = nil)
+    @r.get("mize:#{name}")
+  end
+
+  def write(name, value, options = nil)
+    @r.set("mize:#{name}", Marshal.dump(value))
+  end
+
+  def exist?(name, options = nil)
+    !@r.get("mize:#{name}").nil?
+  end
+
+  def delete(name, options = nil)
+    @r.del("mize:#{name}")
+  end
+
+  def clear(options = nil)
+    # delete matching keys or flushdb
+  end
+
+  def each_name(&block)
+    # yield each key
+    self
+  end
+
+  def prototype
+    dup
+  end
+end
+
+Mize.configure do
+  cache RedisCache.new
+end
 ```
 
-## Download
+Any object that `include Mize::CacheProtocol` and implements `read`,
+`write`, `exist?`, `delete`, `clear`, `each_name`, and `prototype` will
+work.
+
+## Documentation
+
+Complete API documentation is available at: [GitHub.io](https://flori.github.io/mize/)
 
-The homepage of this library is located at
+## Repository
 
 * https://github.com/flori/mize
 
@@ -77,4 +192,4 @@ The homepage of this library is located at
 
 ## License
 
-This software is licensed under MIT license.
+MIT

data/Rakefile

@@ -7,11 +7,20 @@ GemHadar do
   author      'Florian Frank'
   email       'flori@ping.de'
   homepage    "https://github.com/flori/#{name}"
-  summary     'Library that provides memoziation for methods and functions'
+  metadata    'source_code_uri', homepage
+  summary     'Library that provides memoization for methods and functions'
   description "#{summary} for Ruby."
   readme      'README.md'
   licenses << 'MIT'
 
+  changelog do
+    filename 'CHANGES.md'
+  end
+
+  github_workflows(
+    'static.yml' => { }
+  )
+
   test_dir    'spec'
   yard_dir    'doc'
 
@@ -19,12 +28,12 @@ GemHadar do
     '.AppleDouble', 'tags', '.byebug_history', '.yard*', 'yard', 'doc',
     'errors.lst'
 
-
   development_dependency 'rake'
   development_dependency 'simplecov'
   development_dependency 'rspec'
   development_dependency 'yard'
   development_dependency 'all_images'
+  development_dependency 'debug'
 
   required_ruby_version '>= 2'
 end

data/VERSION

@@ -1 +1 @@
-0.6.0
+0.7.0

data/lib/mize/cache_methods.rb

@@ -1,14 +1,28 @@
 require 'mize/cache_protocol'
 require 'mize/default_cache'
 
+# Per-object memoization bookkeeping.
+#
+# Mixed into any module that calls +memoize+. Each *object* gets its own
+# lazily-created cache instance (a copy of +Mize.default_cache+), and the
+# key-building helpers below produce stable, argument-sensitive cache keys.
+#
+# State is deliberately kept per-object: two instances of the same memoized
+# class do not share a cache, which is the expected semantics for instance
+# methods.
 module Mize::CacheMethods
   # Clear cached values for all methods/functions of this object.
+  #
+  # @return [self] The receiver, for chaining.
   def mize_cache_clear
     __mize_cache__.clear
     self
   end
 
   # Clear all cached results for the method/function +name+.
+  #
+  # @param name [String, Symbol] The name of the memoized method/function.
+  # @return [self] The receiver, for chaining.
   def mize_cache_clear_name(name)
     name = build_key_prefix(name)
     __mize_cache__.each_name do |n|
@@ -20,11 +34,19 @@ module Mize::CacheMethods
   private
 
   # Set the cache object to +cache+.
+  #
+  # @param cache [Mize::CacheProtocol] The cache backend to store in.
+  # @return [Mize::CacheProtocol] The cache backend now stored in +self+.
   def __mize_cache__=(cache)
     @__mize_cache__ = cache
   end
 
-  # Return the cache object.
+  # Return the cache object, creating one on first use.
+  #
+  # The first access makes a fresh copy of +Mize.default_cache+ (via
+  # +prototype+ / "dup") so that each object holds an independent store.
+  #
+  # @return [Mize::CacheProtocol] This object's cache backend.
   def __mize_cache__
     if defined?(@__mize_cache__)
       @__mize_cache__
@@ -34,16 +56,35 @@ module Mize::CacheMethods
   end
 
   # Build a key prefix for +name+.
+  #
+  # @param name [String, Symbol] The method/function name.
+  # @return [String] The namespaced prefix, e.g. +"mize/foo"+.
   def build_key_prefix(name)
     "mize/#{name}"
   end
 
   # Build a +name+ prefixed key for the arguments +args+.
+  #
+  # The argument list is +Marshal#+d so structurally-identical arguments
+  # always collide on the same key regardless of object identity.
+  #
+  # @param name [String, Symbol] The method/function name.
+  # @param args [Array] The arguments to key on (positional, then splatted
+  #   keywords).
+  # @return [String] The full cache key.
   def build_key(name, *args)
     "#{build_key_prefix(name)}/#{Marshal.dump(args)}"
   end
 
   # Apply the visibility of method +id+ to the wrapper method of this method.
+  #
+  # The block is expected to (re)define +id+ as +public+; afterwards the
+  # original visibility is re-applied in the +ensure+ clause so a memoized
+  # +private+ method stays +private+.
+  #
+  # @param id [String, Symbol] The name of the method whose visibility to
+  #   mirror.
+  # @yield The block that performs the +define_method+ of +id+.
   def memoize_apply_visibility(id)
     visibility = instance_eval do
       case

data/lib/mize/cache_protocol.rb

@@ -1,2 +1,21 @@
+# Marker interface for Mize-compatible cache backends.
+#
+# A cache backend "is a" +Mize::CacheProtocol+ simply by including this
+# module. No methods are mandated — the module exists solely as a type tag
+# that Mize can match against.
+#
+# The primary consumer is +Mize.cache_clear+ (see +Mize::GlobalClear+), which
+# walks the heap with +ObjectSpace.each_object(Mize::CacheProtocol)+ to locate
+# every live cache instance and clear it. This is what turns a per-object
+# cache into a globally clearable one without an explicit registry.
+#
+# @example A minimal compliant backend
+#   class MyCache
+#     include Mize::CacheProtocol
+#
+#     def read(name, options = nil) ... end
+#     def write(name, value, options = nil) ... end
+#     def clear(options = nil) ... end
+#   end
 module Mize::CacheProtocol
 end