mize 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9907846af04f5b779a69892b22ffc90f80172a4c0949a28b2b20c8c5d505f3a5
-  data.tar.gz: f18d5f411c014669d5b3a7b7d46a127f0f03522aff97b79cf916b3ee67e58563
+  metadata.gz: '04349dcaaaec8f657183fc213be81b6c49f182d0687441b7cdd004e561a008a4'
+  data.tar.gz: 89f29be0ec81a2d25c4418d818e89afa40e4699529f4d04feccffabb4a0225dc
 SHA512:
-  metadata.gz: 2445bf1bc36b723724285132a8ff5f2bb656e80baaf4e3dc2f6813f89d54f11a683526c1425b351d626a24506694060e0cbd7d311cc20fa8e5e3052a2f0f952d
-  data.tar.gz: 1f3873dd7ccee1ee81e7af7a593b0ab3b068b51f3140c08e80454878e4b83e3e9a5086632405af0975f900c24b9e668fce35f70f672fa1f98ecdd6ed30affd41
+  metadata.gz: 6e4ea031b167f232db72a768d892884ea6516b4d1f68603b2e992c95bfed16509838e7df6fc64142944cc5009fff8472a08ede1f88b4767e25e1df9fa2cc980b
+  data.tar.gz: a0790fa35f0ac32bd68679670cbdb45efb4173ef1140865ac64f2e891edc8ca49ad6ceb502dedebe87b7897eb64606cbfd7817eebe6f6033f56b693338d27564

data/.all_images.yml

@@ -1,27 +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 install --full-index
+  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

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

@@ -1,5 +1,67 @@
 # 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:

data/README.md

@@ -1,39 +1,31 @@
 # Mize
 
+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.
 
-## Introduction
-
-Memoization is a powerful technique for improving the performance of
-computationally expensive functions or methods by caching and reusing
-previously computed results. However, implementing memoization correctly can be
-tricky, especially when dealing with complex data structures or scenarios where
-cache invalidation is critical.
-
-## Description
-
-The `mize` library provides a simple and flexible way to memoize methods and
-functions in Ruby, making it easier for developers to write high-performance
-code without the need for manual caching implementations. In this README.md,
-we'll explore how `mize` can help you optimize your Ruby projects using
-memoization techniques.
+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
 
@@ -45,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
 
@@ -69,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
 ```
 
-## Download
+## 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
+```
+
+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
 
@@ -90,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,7 +28,6 @@ GemHadar do
     '.AppleDouble', 'tags', '.byebug_history', '.yard*', 'yard', 'doc',
     'errors.lst'
 
-
   development_dependency 'rake'
   development_dependency 'simplecov'
   development_dependency 'rspec'

data/VERSION

@@ -1 +1 @@
-0.6.1
+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

data/lib/mize/configure.rb

@@ -1,13 +1,40 @@
+# Configuration helpers mixed in / extended onto the top-level +Mize+ object.
+#
+# Provides the block-based +Mize.configure+ DSL and the +default_cache+
+# accessor so users can swap the global cache backend.
 module Mize::Configure
+  # The global default cache backend.
+  #
+  # Every memoized object that has not been given an explicit cache
+  # instantiates a fresh copy (via +prototype+ / "dup") of this backend.
+  # Reassign it to route all new memoized calls through a different store
+  # (Redis, Memcached, ...).
+  #
+  # @return [Mize::CacheProtocol] The current global default cache backend.
   attr_accessor :default_cache
 
   # Set the default cache object to +cache+.
+  #
+  # Intended for use inside a +Mize.configure {}+ block.
+  #
+  # @param cache [Mize::CacheProtocol] The backend to install as the default.
+  # @return [Mize::CacheProtocol] The backend now installed.
   def cache(cache)
     self.default_cache = cache
   end
 
-  # Configures Mize by executing a block of code and executing it in
-  # configuration context/passing the configuration into it.
+  # Configure Mize by evaluating +block+ in the context of the +Mize+ object.
+  #
+  # Inside the block, +cache+ (and the +default_cache+ accessor) are called
+  # directly on +Mize+, so no receiver is required.
+  #
+  # @example
+  #   Mize.configure do
+  #     cache MyRedisCache.new
+  #   end
+  #
+  # @yield The configuration block, evaluated via +instance_eval+.
+  # @return [Object] The return value of +block+.
   def configure(&block)
     instance_eval(&block)
   end
@@ -17,4 +44,5 @@ module Mize
   extend Mize::Configure
 end
 
+# Install the built-in in-memory backend as the global default.
 Mize.default_cache = Mize::DefaultCache.new

data/lib/mize/default_cache.rb

@@ -1,14 +1,30 @@
-require 'monitor'
-
+# The default in-memory cache backend.
+#
+# A plain +Hash+ wrapper that implements just enough of the Mize cache
+# protocol to back memoization out of the box: +read+ / +write+ /
+# +exist?+ / +delete+ / +clear+ / +each_name+.
+#
+# Individual operations are atomic under the GVL. For multi-step
+# atomicity (e.g. check→compute→write), wrap the call in
+# +Mize.synchronize+.
+#
+# Because it is backed by a plain +Hash+, entries are never evicted until you
+# clear the cache explicitly (or the object is garbage-collected). For
+# persistent or evicting behaviour, swap in a different
+# +Mize::CacheProtocol+ implementation via +Mize.configure+.
 class Mize::DefaultCache
   include Mize::CacheProtocol
-  include MonitorMixin
 
+  # Create an empty cache.
+  #
+  # @return [Mize::DefaultCache] A new, empty cache instance.
   def initialize
     @data = {}
   end
 
-  # Clear the cache by removing all entries from the cache
+  # Clear the cache by removing all entries from the cache.
+  #
+  # @return [self] The receiver, for chaining.
   def clear(options = nil)
     @data.clear
     self
@@ -17,16 +33,18 @@ class Mize::DefaultCache
   # Determine whether a cache entry exists in this cache.
   #
   # @param name [String] The name of the cache entry to check.
+  # @param options [Hash, nil] Optional backend-specific options (ignored).
   # @return [Boolean] Whether or not the cache entry exists.
   def exist?(name, options = nil)
     @data.key?(name)
   end
 
   # Read a value from the cache by name. If the entry does not exist in the
-  # cache, it will return nil.
+  # cache, it will return +nil+.
   #
   # @param name [String] The name of the cache entry to read.
-  # @return [Object] The value stored in the cache for the given name.
+  # @param options [Hash, nil] Optional backend-specific options (ignored).
+  # @return [Object, nil] The value stored in the cache for +name+, or +nil+.
   def read(name, options = nil)
     @data.fetch(name, nil)
   end
@@ -35,34 +53,49 @@ class Mize::DefaultCache
   # exists in the cache, it will be overwritten.
   #
   # @param name [String] The name of the cache entry to write.
-  # @param value [Object] The value to store in the cache for the given name.
-  # @return [Object] The value stored in the chache.
+  # @param value [Object] The value to store in the cache for +name+.
+  # @param options [Hash, nil] Optional backend-specific options (ignored).
+  # @return [Object] The value now stored in the cache.
   def write(name, value, options = nil)
     @data.store(name, value)
   end
 
-  # Delete a cache entry by name. If the entry does not exist in the cache, it
+  # Delete a cache entry by name. If an entry does not exist in the cache, it
   # will do nothing.
   #
   # @param name [String] The name of the cache entry to delete.
-  # @return [Object] The value stored in the chache before deletion.
+  # @param options [Hash, nil] Optional backend-specific options (ignored).
+  # @return [Object, nil] The value stored in the cache before deletion, or
+  #   +nil+ if the entry was absent.
   def delete(name, options = nil)
     @data.delete(name)
   end
 
   # Each name of the cache is yielded to the block.
-  # @return [self]
+  #
+  # @yieldparam name [String] Each cache entry name, in turn.
+  # @return [self] The receiver, for chaining.
   def each_name(&block)
     @data.each_key(&block)
     self
   end
 
   # Initialize a duplicate of this cache.
-  # @param other [Mize::DefaultCache] The other cache to initialize a duplicate of.
+  #
+  # The underlying store is shallow-copied so the original and the duplicate
+  # diverge immediately (this is what +prototype+ relies on to hand each
+  # memoized object its own independent cache).
+  #
+  # @param other [Mize::DefaultCache] The cache to initialize a duplicate of.
+  # @return [Mize::DefaultCache] +self+, now a copy of +other+.
   def initialize_dup(other)
     super
     other.instance_variable_set :@data, @data.dup
   end
 
+  # Create a shallow copy of this cache; the public name for +dup+.
+  #
+  # @return [Mize::DefaultCache] A new cache with an independent copy of the
+  #   entries.
   alias prototype dup
 end

data/lib/mize/global_clear.rb

@@ -2,14 +2,28 @@ module Mize
   class << self
 
     # Clear all memoization caches at once.
+    #
+    # Walks every live +Mize::CacheProtocol+ instance in the process (see
+    # +each_cache+) and invokes +clear+ on each, inside +Mize.synchronize+ so
+    # the sweep is atomic with respect to concurrent reads/writes.
+    #
+    # @return [Mize] The +Mize+ module itself.
     def cache_clear
       each_cache(&:clear)
     end
 
     private
 
+    # Yield every live +Mize::CacheProtocol+ object to the block.
+    #
+    # The sweep runs under +Mize.synchronize+ so it cannot observe a
+    # half-cleared cache. Objects only appear here because they
+    # +include Mize::CacheProtocol+.
+    #
+    # @yield [cache] Yields each live cache backend in turn.
+    # @return [Mize] The +Mize+ module itself.
     def each_cache
-      Mize::MUTEX.synchronize do
+      Mize.synchronize do
         for cache in ObjectSpace.each_object(Mize::CacheProtocol)
           yield cache
         end

data/lib/mize/memoize.rb

@@ -2,18 +2,43 @@ require 'mize/cache_methods'
 require 'mize/reload'
 
 module Mize
+  # Memoization entry point, prepended into every +::Module+ by +mize.rb+.
+  #
+  # Including this module (or relying on the global +prepend+) exposes
+  # +memoize+, +mize_cache_clear+ and +mize_cache_clear_name+ on the
+  # receiver. The heavy lifting is delegated to +Mize::CacheMethods+ for
+  # key/state management and +Mize::Reload+ for cache invalidation.
   module Memoize
     include CacheMethods
 
-    # Memoize either a +method+ or a +function+. In the former case the
-    # memoized results do NOT ONLY depend on the arguments, but ALSO on the
-    # object the method is called on. In the latter the memoized results ONLY
-    # depend on the arguments given to the function. If the +freeze+ argument
-    # is true, the result is frozen if possible to make it immutable. If the
-    # store_nil argument is false do not store nil results and always recompute
-    # otherwise don't which is the default.
+    # Memoize either a +method+ or a +function+.
+    #
+    # In the +method+ case the memoized results do NOT ONLY depend on the
+    # arguments, but ALSO on the object the method is called on (each object
+    # keeps its own cache). In the +function+ case the memoized results ONLY
+    # depend on the arguments, and a single shared cache backs every call.
+    #
+    # You must specify exactly one of +method:+ or +function:+; passing both
+    # or neither raises +ArgumentError+.
+    #
+    # @param method [String, Symbol, nil] The instance method to wrap.
+    # @param function [String, Symbol, nil] The bare/stateless function to wrap.
+    # @param freeze [true, false] When true, successfully computed results are
+    #   frozen (if they respond to +freeze+) to make them immutable.
+    # @param store_nil [true, false] When false, +nil+ results are not stored
+    #   and are recomputed every call; defaults to +true+ (store +nil+).
+    # @raise [ArgumentError] If both or neither of +method:+/+function:+ are
+    #   given.
+    # @return [Symbol] The (stringified) symbol of the wrapped method id.
+    # @example Memoizing an instance method
+    #   class Foo
+    #     include Mize::Memoize
+    #
+    #     def expensive(x) x * 2 end
+    #     memoize method: :expensive, freeze: true
+    #   end
     def memoize(method: nil, function: nil, freeze: false, store_nil: true)
-      Mize::MUTEX.synchronize do
+      Mize.synchronize do
         if method && function
           raise ArgumentError, 'memoize a method xor a function'
         elsif method
@@ -31,6 +56,19 @@ module Mize
     class << self
       private
 
+      # Compute the real result of a memoized call.
+      #
+      # Binds +orig_method+ to +context+ and invokes it with +args+; when
+      # running under +$DEBUG+ a diagnostic line is emitted to +STDERR+.
+      #
+      # @param method_id [Symbol] The wrapped method name (diagnostics only).
+      # @param orig_method [UnboundMethod] The original, unwrapped method.
+      # @param key [String] The cache key for this call (diagnostics only).
+      # @param context [Object] The object the method is bound to.
+      # @param args [Array] The positional arguments.
+      # @param kargs [Hash] The keyword arguments.
+      # @param freeze [true, false] Whether to freeze the resulting value.
+      # @return [Object] The (possibly frozen) computed result.
       def compute_result(method_id, orig_method, key, context, args, kargs, freeze)
         result = orig_method.bind(context).call(*args)
         if $DEBUG
@@ -43,7 +81,25 @@ module Mize
       end
     end
 
-    def wrap_method(method_id, freeze: false, function: false, store_nil: true)
+      # Wrap +method_id+ with a memoizing closure.
+      #
+      # Idempotency: a +[self, method_id, function]+ target already present in
+      # +Mize.wrapped+ with identical +freeze+ / +store_nil+ options is a
+      # no-op; conflicting options raise +ArgumentError+.
+      #
+      # For instance methods (+function: false+) the receiver gets its own
+      # per-object cache via +Mize::CacheMethods+ and +Mize::Reload+ is
+      # prepended so +reload+ invalidates entries. For bare functions a single
+      # shared cache is used instead.
+      #
+      # @param method_id [String, Symbol] The name of the method to wrap.
+      # @param freeze [true, false] Forwarded to the wrapper's result handling.
+      # @param function [true, false] Whether +method_id+ is a bare function.
+      # @param store_nil [true, false] Whether +nil+ results should be cached.
+      # @raise [ArgumentError] If the target is already wrapped with different
+      #   +freeze+ / +store_nil+ options.
+      # @return [Symbol] The stringified symbol of the wrapped method id.
+      def wrap_method(method_id, freeze: false, function: false, store_nil: true)
       verbose, $VERBOSE = $VERBOSE, nil
       if already_wrapped = Mize.wrapped[ [ self, method_id, function ] ]
         if already_wrapped == [ freeze, store_nil ]

data/lib/mize/railtie.rb

@@ -1,4 +1,11 @@
 module Mize
+  # Rails integration.
+  #
+  # Hooks into the Rails preparation lifecycle so that every code reload
+  # clears all Mize caches via +Mize.cache_clear+, preventing stale memoized
+  # results from surviving a development-environment class reload.
+  #
+  # Loaded automatically by +mize.rb+ only when +Rails+ is defined.
   class Railtie < Rails::Railtie
     config.to_prepare do
       Mize.cache_clear

data/lib/mize/reload.rb

@@ -1,8 +1,21 @@
+# Reload/invalidation hook, prepended into any module that memoizes an
+# instance method.
+#
+# When a class defines (or inherits) its own +reload+, Mize wraps it so the
+# cache is guaranteed to be cleared alongside whatever the user's +reload+
+# does, keeping memoized state consistent after a full object reload.
 module Mize::Reload
-  # Reload this object if a #reload method was provided up somewhere in the
-  # inheritance tree, afterwards clear the memoization cache and return self.
+  # Run the parent +reload+ (if any), then clear Mize's bookkeeping and the
+  # object's memoization cache.
+  #
+  # The whole sequence is serialized on +Mize.synchronize+. +Mize.wrapped+ is
+  # reset so a re-memoization with different options is allowed, and
+  # +mize_cache_clear+ drops every cached value for this object.
+  #
+  # @return [Object] The result of the parent +reload+ if one was defined,
+  #   otherwise +self+.
   def reload(*)
-    Mize::MUTEX.synchronize do
+    Mize.synchronize do
       result = self
       if defined? super
         result = super

data/lib/mize/version.rb

@@ -1,6 +1,11 @@
+# Version information for the Mize gem.
+#
+# This module is auto-generated by GemHadar and exposes the
+# current release version as a set of constants. Do not edit it
+# by hand; it is rewritten on every `rake version` invocation.
 module Mize
-  # Mize version
-  VERSION         = '0.6.1'
+  # The current version of the Mize gem as a String.
+  VERSION         = '0.7.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/mize.rb

@@ -1,10 +1,71 @@
 require 'thread'
 
+# Mize — a minimal, dependency-free memoization toolkit for Ruby.
+#
+# Mize lets you wrap any method (or a bare, stateless "function") so that its
+# result is cached and reused for identical arguments. It ships with an
+# in-memory +Mize::DefaultCache+ but accepts any object that includes
+# +Mize::CacheProtocol+, so you can plug in Redis, Memcached, and friends.
+#
+# @example Wrapping a method
+#   class Greeter
+#     include Mize::Memoize
+#
+#     def expensive(name)
+#       # ...
+#     end
+#     memoize method: :expensive
+#   end
 module Mize
+  # Process-wide lock guarding all cache and wrapping mutations.
+  #
+  # Every operation that mutates shared Mize state (+memoize+,
+  # +Mize.cache_clear+, +Mize::Reload#reload+) serialises on this mutex, so
+  # the toolkit is safe to use from multiple threads.
   MUTEX = Mutex.new
 
   class << self
+    # Bookkeeping of already-wrapped targets.
+    #
+    # Maps +[module, method_id, function]+ => +[freeze, store_nil]+ so that
+    # duplicate +memoize+ calls can be detected and conflicting options
+    # rejected. Cleared on +Mize::Reload#reload+.
     attr_accessor :wrapped
+
+    # Acquire the global Mize mutex for the duration of +block+.
+    #
+    # Exposes the internal +MUTEX+ under a stable API so callers can make
+    # a sequence of memoized calls atomic with respect to other threads:
+    #
+    # @example
+    #   Mize.synchronize do
+    #     obj.foo(42)
+    #     obj.bar(42)
+    #   end
+    #
+    # The hot path (individual memoized calls) is lock-free by design; use
+    # this when you need the check→compute→write cycle to be indivisible.
+    #
+    # MRI forbids +Mutex#synchronize+ from a trap context (signal handlers
+    # and GC finalizers), raising +ThreadError: can't be called from trap
+    # context+. This is an intentional, still-current design decision (see
+    # DevMeeting-2025-07-10 on
+    # https://bugs.ruby-lang.org/issues/19473), not a bug being patched, so
+    # this method rescues that specific error and runs +block+ without the
+    # lock rather than raising into a finalizer. Other +ThreadError+s (e.g.
+    # recursive locking) are re-raised.
+    #
+    # @yield Executes the block while holding the mutex.
+    # @return [Object] The return value of +block+.
+    def synchronize(&block)
+      MUTEX.synchronize(&block)
+    rescue ThreadError => e
+      if e.message.include?("trap context")
+        block.()
+      else
+        raise e
+      end
+    end
   end
   self.wrapped = {}
 end
@@ -15,6 +76,8 @@ require 'mize/configure'
 require 'mize/global_clear'
 require 'mize/railtie' if defined? Rails
 
+# Inject +memoize+ into every module so any class can opt in with a single
+# +include Mize::Memoize+.
 class ::Module
   prepend Mize::Memoize
 end

data/mize.gemspec

@@ -1,29 +1,30 @@
 # -*- encoding: utf-8 -*-
-# stub: mize 0.6.1 ruby lib
+# stub: mize 0.7.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "mize".freeze
-  s.version = "0.6.1".freeze
+  s.version = "0.7.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.metadata = { "source_code_uri" => "https://github.com/flori/mize" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["Florian Frank".freeze]
-  s.date = "2024-10-17"
-  s.description = "Library that provides memoziation for methods and functions for Ruby.".freeze
+  s.date = "1980-01-02"
+  s.description = "Library that provides memoization for methods and functions for Ruby.".freeze
   s.email = "flori@ping.de".freeze
   s.extra_rdoc_files = ["README.md".freeze, "lib/mize.rb".freeze, "lib/mize/cache_methods.rb".freeze, "lib/mize/cache_protocol.rb".freeze, "lib/mize/configure.rb".freeze, "lib/mize/default_cache.rb".freeze, "lib/mize/global_clear.rb".freeze, "lib/mize/memoize.rb".freeze, "lib/mize/railtie.rb".freeze, "lib/mize/reload.rb".freeze, "lib/mize/version.rb".freeze]
-  s.files = [".all_images.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".travis.yml".freeze, ".utilsrc".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "config/broken_config.yml".freeze, "config/config.yml".freeze, "lib/mize.rb".freeze, "lib/mize/cache_methods.rb".freeze, "lib/mize/cache_protocol.rb".freeze, "lib/mize/configure.rb".freeze, "lib/mize/default_cache.rb".freeze, "lib/mize/global_clear.rb".freeze, "lib/mize/memoize.rb".freeze, "lib/mize/railtie.rb".freeze, "lib/mize/reload.rb".freeze, "lib/mize/version.rb".freeze, "mize.gemspec".freeze, "spec/mize/global_clear_spec.rb".freeze, "spec/mize/memoize_method_spec.rb".freeze, "spec/mize/memoize_reload_spec.rb".freeze, "spec/mize/version_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.files = [".all_images.yml".freeze, ".github/workflows/static.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".travis.yml".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "lib/mize.rb".freeze, "lib/mize/cache_methods.rb".freeze, "lib/mize/cache_protocol.rb".freeze, "lib/mize/configure.rb".freeze, "lib/mize/default_cache.rb".freeze, "lib/mize/global_clear.rb".freeze, "lib/mize/memoize.rb".freeze, "lib/mize/railtie.rb".freeze, "lib/mize/reload.rb".freeze, "lib/mize/version.rb".freeze, "mize.gemspec".freeze, "spec/mize/global_clear_spec.rb".freeze, "spec/mize/memoize_method_spec.rb".freeze, "spec/mize/memoize_reload_spec.rb".freeze, "spec/mize/version_spec.rb".freeze, "spec/mize_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "https://github.com/flori/mize".freeze
   s.licenses = ["MIT".freeze]
-  s.rdoc_options = ["--title".freeze, "Mize - Library that provides memoziation for methods and functions".freeze, "--main".freeze, "README.md".freeze]
+  s.rdoc_options = ["--title".freeze, "Mize - Library that provides memoization for methods and functions".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 2".freeze)
-  s.rubygems_version = "3.5.18".freeze
-  s.summary = "Library that provides memoziation for methods and functions".freeze
-  s.test_files = ["spec/mize/global_clear_spec.rb".freeze, "spec/mize/memoize_method_spec.rb".freeze, "spec/mize/memoize_reload_spec.rb".freeze, "spec/mize/version_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.rubygems_version = "4.0.22".freeze
+  s.summary = "Library that provides memoization for methods and functions".freeze
+  s.test_files = ["spec/mize/global_clear_spec.rb".freeze, "spec/mize/memoize_method_spec.rb".freeze, "spec/mize/memoize_reload_spec.rb".freeze, "spec/mize/version_spec.rb".freeze, "spec/mize_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.19".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.20.1".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])

data/spec/mize/global_clear_spec.rb

@@ -1,5 +1,3 @@
-require 'spec_helper'
-
 class Foo
   def self.reset
     @@foo = nil

data/spec/mize/memoize_method_spec.rb

@@ -1,5 +1,3 @@
-require 'spec_helper'
-
 class FooBar
   class << self
     def reset

data/spec/mize/memoize_reload_spec.rb

@@ -1,5 +1,3 @@
-require 'spec_helper'
-
 class Foo
   def self.reset
     @@foo = nil

data/spec/mize/version_spec.rb

@@ -1,5 +1,3 @@
-require 'spec_helper'
-
 describe 'Mize::VERSION' do
   it 'has a version' do
     expect(Mize::VERSION).to be_a String

data/spec/mize_spec.rb

@@ -0,0 +1,13 @@
+describe Mize do
+  describe '.synchronize' do
+    it 'executes the block and returns its value' do
+      expect(described_class.synchronize { 42 }).to eq(42)
+    end
+
+    it 'is the same lock object as Mize::MUTEX' do
+      expect {
+        Mize::MUTEX.synchronize { Mize.synchronize { :x } }
+      }.to raise_error(ThreadError)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,8 +1,7 @@
-if ENV['START_SIMPLECOV'].to_i == 1
-  require 'simplecov'
-  SimpleCov.start do
-    add_filter "#{File.basename(File.dirname(__FILE__))}/"
-  end
+begin
+  require 'gem_hadar/simplecov'
+  GemHadar::SimpleCov.start
+rescue LoadError
 end
 require 'rspec'
 require 'mize'

metadata

@@ -1,29 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: mize
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Florian Frank
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: 2.20.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: 2.20.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +107,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Library that provides memoziation for methods and functions for Ruby.
+description: Library that provides memoization for methods and functions for Ruby.
 email: flori@ping.de
 executables: []
 extensions: []
@@ -126,18 +125,16 @@ extra_rdoc_files:
 - lib/mize/version.rb
 files:
 - ".all_images.yml"
+- ".github/workflows/static.yml"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
-- ".utilsrc"
 - CHANGES.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - VERSION
-- config/broken_config.yml
-- config/config.yml
 - lib/mize.rb
 - lib/mize/cache_methods.rb
 - lib/mize/cache_protocol.rb
@@ -153,15 +150,16 @@ files:
 - spec/mize/memoize_method_spec.rb
 - spec/mize/memoize_reload_spec.rb
 - spec/mize/version_spec.rb
+- spec/mize_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/flori/mize
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  source_code_uri: https://github.com/flori/mize
 rdoc_options:
 - "--title"
-- Mize - Library that provides memoziation for methods and functions
+- Mize - Library that provides memoization for methods and functions
 - "--main"
 - README.md
 require_paths:
@@ -177,13 +175,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 4.0.22
 specification_version: 4
-summary: Library that provides memoziation for methods and functions
+summary: Library that provides memoization for methods and functions
 test_files:
 - spec/mize/global_clear_spec.rb
 - spec/mize/memoize_method_spec.rb
 - spec/mize/memoize_reload_spec.rb
 - spec/mize/version_spec.rb
+- spec/mize_spec.rb
 - spec/spec_helper.rb

data/.utilsrc

@@ -1,26 +0,0 @@
-# vim: set ft=ruby:
-
-search do
-  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|doc|pkg)\z/
-  skip_files /(\A\.|\.sw[pon]\z|\.(log|fnm|jpg|jpeg|png|pdf|svg)\z|tags|~\z)/i
-end
-
-discover do
-  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|doc|pkg)\z/
-  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
-  binary false
-end
-
-strip_spaces do
-  prune_dirs /\A(\..*|CVS|pkg)\z/
-  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
-end
-
-probe do
-  test_framework :rspec
-  #include_dirs 'features'
-end
-
-ssh_tunnel do
-  terminal_multiplexer :tmux
-end

data/config/broken_config.yml

@@ -1 +0,0 @@
-,kaput

data/config/config.yml

@@ -1,13 +0,0 @@
-development:
-  config:
-    foo: true
-    bar: false
-    baz: 'something'
-    pi:  <%= Math::PI %>
-
-test:
-  config:
-    foo: false
-    bar: true
-    baz: 'something else'
-    pi:  3.141