rmagick_tidy 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f147dcd4088210662a53b4a66911e721b5b5a506ff4b1bead65db5a94ac873b
-  data.tar.gz: c80d6229d5ef1e1272097f3d30b939629c04ddb29bed8f185c2a01dc4f7f4d05
+  metadata.gz: d63fdf8da8e0b7479b85be728d7e00e3e7821a042fbaacb730d6c6a3d783d337
+  data.tar.gz: 52d88eedea15175cd1b35fd8046f4127ccc73cc3b98511bf7c5afcc02a258ded
 SHA512:
-  metadata.gz: e60b3a6a5812a68936e71e73f073ce9f1d1f57032df67ff05c99c5279acba8fc7f935f8435c263388f95a31ac784ba09caa7e10d63954810f155ef3fadf5f592
-  data.tar.gz: 63f5780ab884f412049b3fc7290e3f0a050ce8859a66fd87952417156e978ec6f0623efbadb2b98d88711289158e03130efecce5adedea1aa92351bda61b3d73
+  metadata.gz: 2087aa6871347fede9c6fa3022dad2aeb425a0b2e46cb181071fe623156ae1c0fb21e1ec0152ee8d84663b9e74695cd0e9097a219ce2194b3cceacec4df172ce
+  data.tar.gz: 44a0ea74486054b2b9ee69052540c2a6018a707d864ac21dab7ae7a8656e3c278886244553690f445938f6c55509e5e936d4f6e50f513ced5c62d75dc9633d86

data/CHANGELOG.md

@@ -1,11 +1,10 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+Release notes for versions after 0.1.0 are published on
+[GitHub Releases](https://github.com/jksy/rmagick_tidy/releases), generated
+from merged pull requests. This file is kept for the history below.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.1.0] - 2026-05-21
 

data/README.ja.md

@@ -95,6 +95,64 @@ end
 
 `to_blob` は `String` を返すのでスコープの解放対象になりません。Image オブジェクトのみがクリーンアップされます。
 
+## Rails 以外・ジョブで使う
+
+gem 自体が組み込むのは Rails のコントローラだけです。それ以外の場所では、処理の単位を自分で `RmagickTidy.scope` で包んでください。数行で書けます。アプリ側に置いておけば、各ライブラリのバージョンアップにも自分のペースで合わせられます。
+
+### Rack ミドルウェア（Sinatra / Hanami / 素の Rack など）
+
+```ruby
+class RmagickTidyMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    RmagickTidy.scope { @app.call(env) }
+  end
+end
+
+use RmagickTidyMiddleware
+```
+
+スコープはアプリから戻った時点で終わります。サーバがボディを送るより前です。`String` の `Array` や Rails・Sinatra の通常のレスポンスのように、中身ができあがっているボディなら問題ありません。streaming body や `Enumerator` のように送信中に画像を作ったり使ったりする場合は、その画像処理をボディの中に書き、ボディの中で `RmagickTidy.scope` を張ってください。アプリ側で作ってボディが後から使う画像は、その時点で解放済みです。
+
+### ActiveJob
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  around_perform do |_job, block|
+    RmagickTidy.scope do
+      block.call
+      nil
+    end
+  end
+end
+```
+
+`nil` を返すのは、`perform` の戻り値を keep しないためです。`perform` の最後が `img.write(path)` だと戻り値は `img` 自身になり、そのままだと GC まで残ってしまいます。
+
+### Sidekiq
+
+```ruby
+class RmagickTidySidekiqMiddleware
+  def call(_job, _payload, _queue)
+    RmagickTidy.scope do
+      yield
+      nil
+    end
+  end
+end
+
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add RmagickTidySidekiqMiddleware
+  end
+end
+```
+
+Sidekiq 上で動かす ActiveJob のジョブでは、上の `around_perform` とこのミドルウェアのどちらか一方で足ります。両方入れてもスコープが入れ子になるだけです。
+
 ## strict モード
 
 開発・テスト環境で「スコープ外で作られた Image」を検知したいときに使います。
@@ -106,23 +164,44 @@ end
 ```
 
 - `:off` — 何もしない（本番デフォルト）
-- `:warn` — `warn` で標準エラー出力に通知
+- `:warn` — `warn` で標準エラー出力に通知（`logger` 設定時はそちらへ出力）
 - `:raise` — `RmagickTidy::OutOfScopeError` を発生
 
-> **Configuration はスレッドセーフではありません。** `strict_mode`（および将来追加されるオプション）は **起動時に 1 回だけ**設定してください（例: Rails の initializer）。ワーカースレッドが `Magick::Image` を使い始めたあとに別スレッドから書き換える挙動は未定義です。
+`:warn` の出力先を標準エラー出力以外にしたい場合は、`warn(message)` に応答するオブジェクト（例: `Rails.logger`）を `logger` に設定します。`logger` が `nil`（デフォルト）のときは従来通り `Kernel#warn` にフォールバックします。Railtie は自動では設定しないため、Rails アプリでは initializer で明示的に指定してください。
+
+```ruby
+RmagickTidy.configure do |c|
+  c.strict_mode = :warn
+  c.logger = Rails.logger
+end
+```
+
+> **Configuration はスレッドセーフではありません。** `strict_mode`・`logger`（および将来追加されるオプション）は **起動時に 1 回だけ**設定してください（例: Rails の initializer）。ワーカースレッドが `Magick::Image` を使い始めたあとに別スレッドから書き換える挙動は未定義です。
+
+## メモリ使用量のベンチマーク
+
+[`benchmark/memory.rb`](benchmark/memory.rb) は、生成した画像の read / resize をループで繰り返し、`RmagickTidy.scope` なし・ありの 2 パターンでプロセスの RSS を記録します。
+
+```bash
+bundle exec ruby benchmark/memory.rb
+ITERATIONS=100 SIZE=4000 bundle exec ruby benchmark/memory.rb
+```
+
+デフォルト設定（50 回、3000x3000 の画像。Linux 上の Ruby 3.4 / RMagick 7.2 / ImageMagick 7.1 Q16-HDRI）では、scope なしで RSS が約 340 MB まで増え、scope ありでは約 57 MB で安定しました。具体的な数値は環境や ImageMagick のビルドによって変わります。
 
 ## 仕組み
 
 - `Magick::Image` / `Magick::ImageList` に対し、`Module#prepend` で全ての public instance method（および `new`, `read`, `from_blob`, ...のクラスメソッド）をラップ
 - **戻り値の型をチェック**して `Magick::Image` であれば現在のスコープに登録（ホワイトリストを持たないので RMagick のバージョン差異を吸収）
-- 戻り値が `self` と `equal?` なら bang メソッドとみなして登録しない
+- 戻り値が `self` と `equal?` なら bang メソッドとみなして登録しない。同様に、Image を登録するのは初めて見たときだけ（`ObjectSpace::WeakMap` で同一性を記録）。`ImageList#[]`・`#first`・`#pop`・`#delete` が返す要素や、浅いコピーである `ImageList#dup` の中身は再登録しないので、スコープ外で作ったリストを操作しても元の画像は破棄されない
+- `dup` / `clone` もラップする。`Magick::Image#dup` / `#clone` は新しい画像を確保するので、他のメソッドと同様に登録される
 - スコープスタックは `Thread.current` 配下なのでマルチスレッド環境でも安全
 - 二重 `destroy!` は `destroyed?` 判定 + rescue で防止
 
 ## 対応バージョン
 
-- Ruby 3.2 以上
-- RMagick 2.x 〜 6.x（戻り値チェック方式のため幅広く動作）
+- Ruby 3.3 以上
+- RMagick 5.x 〜 7.x（CI では 6.x / 7.x でテスト）
 
 ## ライセンス
 

data/README.md

@@ -95,6 +95,64 @@ end
 
 `to_blob` returns a `String`, so it is never treated as a cleanup target — only the image objects are released.
 
+## Other frameworks and job queues
+
+The gem itself only hooks into Rails controllers. Anywhere else, wrap the unit of work in `RmagickTidy.scope` yourself. It only takes a few lines, and keeping them in your app means you control them when those libraries change.
+
+### Rack middleware (Sinatra, Hanami, plain Rack, ...)
+
+```ruby
+class RmagickTidyMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    RmagickTidy.scope { @app.call(env) }
+  end
+end
+
+use RmagickTidyMiddleware
+```
+
+The scope ends when the app returns, before the server sends the body. That is fine for bodies whose content is already built (an `Array` of strings, a Rails or Sinatra response). If a streaming body or an `Enumerator` creates or uses images while it is being sent, do that image work inside the body, in its own `RmagickTidy.scope`; images created by the app and used later by the body are already released by then.
+
+### ActiveJob
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  around_perform do |_job, block|
+    RmagickTidy.scope do
+      block.call
+      nil
+    end
+  end
+end
+```
+
+The `nil` stops the scope from keeping what `perform` returns. A `perform` that ends with `img.write(path)` returns `img` itself, which would otherwise stay alive until GC.
+
+### Sidekiq
+
+```ruby
+class RmagickTidySidekiqMiddleware
+  def call(_job, _payload, _queue)
+    RmagickTidy.scope do
+      yield
+      nil
+    end
+  end
+end
+
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add RmagickTidySidekiqMiddleware
+  end
+end
+```
+
+For ActiveJob jobs running on Sidekiq, either the `around_perform` above or this middleware is enough; using both just nests the scopes.
+
 ## Strict mode
 
 Use strict mode in development or test environments to catch images created outside of a scope.
@@ -106,26 +164,50 @@ end
 ```
 
 - `:off` — do nothing (the production default)
-- `:warn` — print a warning to stderr
+- `:warn` — print a warning to stderr (or to `logger`, if set)
 - `:raise` — raise `RmagickTidy::OutOfScopeError`
 
-> **Configuration is not thread-safe.** Set `strict_mode` (and any future
-> options) **once at boot** — for example from a Rails initializer — before any
-> worker thread starts using `Magick::Image`. Reading and writing the value
+To send `:warn` messages to a logger instead of stderr, set `logger` to any
+object that responds to `warn(message)` (e.g. `Rails.logger`). When `logger`
+is `nil` (the default), the warning falls back to `Kernel#warn`. The Railtie
+does not set it for you, so Rails apps opt in from an initializer:
+
+```ruby
+RmagickTidy.configure do |c|
+  c.strict_mode = :warn
+  c.logger = Rails.logger
+end
+```
+
+> **Configuration is not thread-safe.** Set `strict_mode` and `logger` (and
+> any future options) **once at boot** — for example from a Rails initializer —
+> before any worker thread starts using `Magick::Image`. Reading and writing the value
 > from multiple threads concurrently is undefined.
 
+## Memory benchmark
+
+[`benchmark/memory.rb`](benchmark/memory.rb) reads and resizes a generated image in a loop, once without `RmagickTidy.scope` and once with it, and prints the process RSS as it goes:
+
+```bash
+bundle exec ruby benchmark/memory.rb
+ITERATIONS=100 SIZE=4000 bundle exec ruby benchmark/memory.rb
+```
+
+With the defaults (50 iterations, 3000x3000 source; Ruby 3.4, RMagick 7.2, ImageMagick 7.1 Q16-HDRI on Linux), RSS climbed to about 340 MB without the scope and stayed at about 57 MB with it. Exact numbers depend on your platform and ImageMagick build.
+
 ## How it works
 
 - `Magick::Image` and `Magick::ImageList` are hooked with `Module#prepend`, wrapping every public instance method as well as class methods such as `new`, `read`, and `from_blob`.
 - Each wrapped method **inspects its return value**: if it is a `Magick::Image`, the image is registered with the current scope. Because the gem keeps no method whitelist, it works across a wide range of RMagick versions.
-- If the return value is `equal?` to `self`, it is treated as a bang method and not registered.
+- If the return value is `equal?` to `self`, it is treated as a bang method and not registered. Likewise, an image is registered only the first time it is seen (tracked by identity in an `ObjectSpace::WeakMap`): images handed back from a list, such as by `ImageList#[]`, `#first`, `#pop`, `#delete`, or the shallow copy from `ImageList#dup`, are not registered again, so working with a list created outside the scope does not destroy its images.
+- `dup` / `clone` are wrapped too: `Magick::Image#dup` and `#clone` allocate a new image, which is tracked like any other.
 - The scope stack lives in `Thread.current`, so it is safe to use under multi-threaded servers such as Puma.
 - Calling `destroy!` twice is guarded against with a `destroyed?` check and a defensive `rescue`.
 
 ## Compatibility
 
-- Ruby 3.2 or newer
-- RMagick 2.x through 6.x (the return-value approach keeps the gem broadly compatible)
+- Ruby 3.3 or newer
+- RMagick 5.x through 7.x (CI tests against 6.x and 7.x)
 
 ## License
 

data/lib/rmagick_tidy/configuration.rb

@@ -3,8 +3,13 @@ module RmagickTidy
     # :off (default), :warn, :raise
     attr_accessor :strict_mode
 
+    # Receives strict_mode :warn messages via #warn (e.g. Rails.logger).
+    # nil (default) falls back to Kernel#warn, i.e. stderr.
+    attr_accessor :logger
+
     def initialize
       @strict_mode = :off
+      @logger = nil
     end
   end
 

data/lib/rmagick_tidy/hook.rb

@@ -8,6 +8,11 @@ module RmagickTidy
       tainted? untrusted? object_id class itself
     ].freeze
 
+    # Copy methods inherited from Kernel, so public_instance_methods(false)
+    # misses them. Image#dup / #clone allocate a new C image; ImageList's
+    # share the receiver's images, which Tracker.track has already seen.
+    COPY_METHODS = %i[dup clone].freeze
+
     # Class-level methods on Magick::Image that produce new images.
     CLASS_METHODS = %i[new read ping from_blob read_inline capture constitute combine].freeze
 
@@ -32,7 +37,7 @@ module RmagickTidy
       mod = Module.new do
         def self.inspect = "#<RmagickTidy::InstanceHook>"
       end
-      method_names = klass.public_instance_methods(false) - SKIP_INSTANCE_METHODS
+      method_names = (klass.public_instance_methods(false) | COPY_METHODS) - SKIP_INSTANCE_METHODS
       method_names.each do |name|
         next if name.to_s.end_with?("=")
 

data/lib/rmagick_tidy/tracker.rb

@@ -1,11 +1,22 @@
 module RmagickTidy
   module Tracker
+    # Every Image that has passed through track, held weakly and compared by
+    # identity (RMagick maps one Ruby object to one C image). An image seen
+    # before is not a new allocation, whichever method hands it back:
+    # ImageList#dup, #[], #first share the list's images, and #pop, #shift,
+    # #delete return ones taken out of it. Registering those would destroy
+    # images that belong to an outer scope or to no scope at all.
+    SEEN = ObjectSpace::WeakMap.new
+
     module_function
 
     def track(result, receiver = nil)
       return result if receiver && result.equal?(receiver)
 
       each_image(result) do |img|
+        next if SEEN.key?(img)
+
+        SEEN[img] = true
         register(img)
       end
       result
@@ -50,7 +61,16 @@ module RmagickTidy
         raise OutOfScopeError,
               "Magick::Image #{img.inspect} was created outside of RmagickTidy.scope"
       when :warn
-        warn "[rmagick_tidy] Magick::Image created outside of RmagickTidy.scope (#{img.class})"
+        report("[rmagick_tidy] Magick::Image created outside of RmagickTidy.scope (#{img.class})")
+      end
+    end
+
+    def report(message)
+      logger = RmagickTidy.configuration.logger
+      if logger
+        logger.warn(message)
+      else
+        warn message
       end
     end
   end

data/lib/rmagick_tidy/version.rb

@@ -1,3 +1,3 @@
 module RmagickTidy
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rmagick_tidy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Junichiro Kasuya
 bindir: bin
 cert_chain: []
-date: 2026-05-21 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rmagick
@@ -77,14 +77,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: simplecov-lcov
   requirement: !ruby/object:Gem::Requirement
@@ -125,7 +125,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jksy/rmagick_tidy
   source_code_uri: https://github.com/jksy/rmagick_tidy/tree/main
-  changelog_uri: https://github.com/jksy/rmagick_tidy/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/jksy/rmagick_tidy/releases
   bug_tracker_uri: https://github.com/jksy/rmagick_tidy/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -135,7 +135,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="