image_pack 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 606688569aac1fa1515edefe270b18a04e5b0042de602b18663964726d8fbb34
-  data.tar.gz: 9092fcf9fa3c061edc87ce2a22544acfe52dfa6ce4fe39961c95a1d17220a6b0
+  metadata.gz: 124f64ccca4910cee483d3c63a189f6de7d7ea72e8f4a8b88d538fe503cf0673
+  data.tar.gz: d51e698fdad475590f685ddd6097f9bf8486dcb154ce37716e60fac256949c6c
 SHA512:
-  metadata.gz: ad6b0db99c56d69c99d9216559e3c114a2079941a4f879e69508126bbf12b070844dc53e806b3da7637783a205528c10136c3cd3bac8f60b5fd6ee2ddcad01eb
-  data.tar.gz: f1acfa9f5a7154d1ea201ae66658da704a5ee5d207886b096d284b7b69eca175d668993dba127b0a609d6fb5b68492196edb8d3bb70d12575f129c095c6b7704
+  metadata.gz: 6ed979776d78d8e1d64e01ec46499d2453d13483495688cc79b71e0fc84b542d68e2a076015d480aaac812c90ef1dea49952f40b156d11d2b4dd95ace73a7688
+  data.tar.gz: 233229ccf2b0daa138dc6bd664ce14c8ddf770aaa232d42efc33d43419a3c7f0f5b673daf985e6745e49fcf8ceeac9503d84910319cb8a7d269178e08cd657eb

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
+## 0.2.4
+
+- libjpeg/MozJPEG diagnostics are no longer written to `stderr`; instead decode warnings (e.g. "Premature end of JPEG file") are counted and the first message is captured, so a damaged or truncated input is observable rather than silently degraded.
+- Added `strict:` to `compress`, `compress_pixels`, and `optimize_jpeg`. With `strict: true` the first libjpeg warning is promoted to `ImagePack::InvalidImageError` instead of producing a degraded JPEG; default is `false`.
+- Added `report:` to `compress` and `compress_pixels`. With `report: true` the call returns a Hash `{ output:, quality:, ssim:, algo:, bytesize:, input_bytesize:, warning_count:, warning: }`, exposing the SSIM-selected quality, achieved luma SSIM, and decode warning information; `report: false` (default) keeps the previous return value (binary `String` or `true`).
+- Made the no-GVL and offload execution paths interruptible regardless of `cancellable:`. Decode/encode/SSIM checkpoints now always observe the unblock signal, and a pending Ruby interrupt (signal, `Thread#raise`, `Thread#kill`, scheduler) is delivered via `rb_thread_check_ints` after the native section, so the raised exception propagates instead of being masked. Cancellation is expressed by raising on the worker thread; `ImagePack::CancelledError` is the idiomatic choice.
+- Added the `IMAGE_PACK_DISABLE_OFFLOAD=1` runtime opt-out. The vendored MozJPEG SIMD thread-local storage is only an idempotent CPU-feature cache, so offload remains safe with SIMD enabled, but the environment variable forces `offload_safe?` to `false` and prevents `:auto`/`:offload` from offloading.
+- `NATIVE_MOZJPEG_VERSION` is now derived from a dedicated `IMAGE_PACK_MOZJPEG_VERSION` compile define instead of relying on the libjpeg `VERSION` macro being in scope.
+- Removed the unused `IMAGE_PACK_RUBY34_ONLY` compile define.
+- Removed a stale `v0.2.2` reference from the `output:` argument error message.
+- Added tests covering `report:`, `strict:`, warning collection, the cancellation contract, offload availability, and version hygiene.
+- Documentation and message version references updated to 0.2.4.
+
+## 0.2.3
+
 - Lowered the runtime floor to Ruby >= 3.1.0 while keeping `execution: :offload` Ruby >= 3.4-only and explicitly unsupported on older Rubies.
+
 ## 0.2.2
 
 - Fixed native cleanup safety: native contexts are now released through `rb_ensure`, including Ruby exception paths from argument coercion, config reads, native status errors, output `String` allocation, and file-output failures.

data/README.md

@@ -1,199 +1,169 @@
 # image_pack
 
-`image_pack` is a Ruby-native JPEG compressor prototype for Ruby `>= 3.1.0`.
+Ruby-native JPEG compression and optimization backed by vendored pure-C MozJPEG/libjpeg.
 
-Current version: `0.2.2`.
-
-This pure-C variant intentionally removes Jpegli and any C++ toolchain requirement.
-The native layer is written in C and links against vendored MozJPEG, which is libjpeg-compatible and based on libjpeg-turbo.
-
-## Backends / modes
+No system `libjpeg`, `mozjpeg`, `git`, or `CMake` is required for gem users.
 
 ```ruby
-ImagePack.compress(input, algo: :jpeg_turbo)
-ImagePack.compress(input, algo: :mozjpeg)
+gem "image_pack"
 ```
 
-- `:jpeg_turbo` / `:fast` — fast libjpeg-compatible mode with MozJPEG-specific size optimizations disabled.
-- `:mozjpeg` / `:size` — size-oriented mode using optimized Huffman coding and optional progressive output through the MozJPEG/libjpeg API.
-
-Both modes produce ordinary `.jpg` files.
-
-Important implementation note: this prototype uses one pure-C vendored codec family to avoid static-link symbol conflicts between separate libjpeg-compatible libraries. If later we need exact latest `libjpeg-turbo` and exact MozJPEG in one gem, the correct next step is linker isolation / separate native extensions with hidden symbols.
-
-
-## Native extension layout
-
-For the first prototype the native layer intentionally lives in one file:
-
-```text
-ext/image_pack/
-├── extconf.rb
-└── image_pack.c
+```ruby
+require "image_pack"
 ```
 
-This mirrors the early `multi_compress` style: one translation unit is easier to expand, debug and refactor while the API and codec boundaries are still moving. The code can be split into modules later, after the first working version is stable.
-
-## API
+## Quick use
 
 ```ruby
-require "image_pack"
-
 jpeg = File.binread("photo.jpg")
 
-ImagePack.compress(jpeg, algo: :jpeg_turbo, quality: 82)
-ImagePack.compress(jpeg, algo: :mozjpeg, quality: 82)
-
-# SSIM-guarded compression: choose the smallest acceptable JPEG quality
-# while keeping decoded visual similarity >= 0.985.
-ImagePack.compress(jpeg, algo: :mozjpeg, min_ssim: 0.985)
+small = ImagePack.compress_bytes(jpeg, quality: 82)
+File.binwrite("photo.small.jpg", small)
 
-# Start at quality 75, but raise quality if needed to satisfy min_ssim.
-ImagePack.compress(jpeg, algo: :mozjpeg, quality: 75, min_ssim: 0.985)
+ImagePack.compress_file("photo.jpg", output: "photo.small.jpg")
+ImagePack.optimize_file("photo.jpg", output: "photo.optimized.jpg")
+```
 
-ImagePack.compress("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
-ImagePack.compress_file("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
-ImagePack.compress_bytes(jpeg, algo: :fast, quality: 82)
+Prefer explicit helpers:
 
-# Lossless coefficient-level JPEG optimization/transcode.
-# This rewrites JPEG coefficients without decoding/re-encoding pixels.
-ImagePack.optimize_jpeg(jpeg, progressive: true, strip_metadata: false)
-ImagePack.optimize_file("photo.jpg", output: "photo.lossless.jpg")
+```ruby
+ImagePack.compress_bytes(jpeg)
+ImagePack.compress_file("photo.jpg", output: "out.jpg")
 ImagePack.optimize_bytes(jpeg)
-
-ImagePack.compress_pixels(rgb_buffer,
-  width: 1920,
-  height: 1080,
-  channels: 3,
-  algo: :mozjpeg
-)
-
-ImagePack.inspect_image(jpeg)
-# => { format: :jpeg, width: 1920, height: 1080, channels: 3, bit_depth: 8, decoded_bytes: 6220800 }
+ImagePack.optimize_file("photo.jpg", output: "out.jpg")
 ```
 
-## Input / output policy
+## Compression
 
-`compress(input, ...)` accepts JPEG input only:
-
-- binary `String` (`ASCII-8BIT`) — JPEG bytes;
-- non-binary `String` that points to an existing file — file path;
-- `Pathname` — file path;
-- `IO::Buffer` — JPEG bytes, copied before native no-GVL execution for safety.
-
-For non-ambiguous call sites prefer `compress_bytes(bytes, ...)` or `compress_file(path, ...)`.
+```ruby
+ImagePack.compress_bytes(jpeg,
+  algo: :size,
+  quality: 82,
+  strip_metadata: true
+)
+```
 
-`compress_pixels(buffer, ...)` accepts raw pixels as binary `String` or `IO::Buffer`.
-`channels` must be `1`, `3`, or `4`. Alpha in RGBA input is dropped in v0.2.2; pass `drop_alpha: true` to make that explicit, or `drop_alpha: false` to reject it.
+Algorithms:
 
-`output: nil` returns binary JPEG bytes. `output: String/Pathname` writes through a temporary file and renames it into place.
-Streaming output is intentionally not supported in v0.2.2.
+- `:size` / `:mozjpeg` — smaller files, default
+- `:fast` / `:jpeg_turbo` — faster mode
 
-## Lossless JPEG optimize
+Common options:
 
-`optimize_jpeg`, `optimize_bytes`, and `optimize_file` are coefficient-level JPEG transcode helpers. They use `jpeg_read_coefficients` / `jpeg_write_coefficients`, so pixels are not decoded and re-encoded. This is the preferred path when you only want to rewrite an existing JPEG with optimized Huffman tables and optional progressive scans.
+```ruby
+ImagePack.compress_bytes(jpeg, min_ssim: 0.985)
+ImagePack.compress_bytes(jpeg, progressive: true)
+ImagePack.compress_bytes(jpeg, strict: true)
+ImagePack.compress_bytes(jpeg, report: true)
+```
 
-Defaults are intentionally conservative:
+`min_ssim:` searches for the lowest acceptable quality using a fast native luma SSIM guard.
 
-- `progressive: true` creates a progressive optimized JPEG;
-- `strip_metadata: false` preserves APP/COM metadata by default because this path is meant to be visually/losslessly safe.
+`strict: true` raises `ImagePack::InvalidImageError` on damaged/truncated JPEG warnings.
 
-If `strip_metadata: true` is requested and the source JPEG has EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently removing the orientation tag and changing how viewers display the image. Use `strip_metadata: false` for coefficient-level optimization, or `compress(..., strip_metadata: true)` if you want pixel-level orientation normalization.
+`report: true` returns a Hash:
 
-## SSIM guard
+```ruby
+{
+  output: "\xFF\xD8...",
+  quality: 84,
+  ssim: 0.9861,
+  algo: :mozjpeg,
+  bytesize: 50122,
+  input_bytesize: 81344,
+  warning_count: 0,
+  warning: nil
+}
+```
 
-`compress` and `compress_pixels` accept `min_ssim:`. This enables a native guarded path:
+With `output: "file.jpg"`, `output` is `true`.
 
-1. decode the original JPEG to reference pixels;
-2. encode trial JPEG candidates with the existing MozJPEG/libjpeg backend;
-3. decode each candidate;
-4. compute a native luma SSIM score;
-5. return the smallest quality that satisfies `SSIM >= min_ssim`.
+## Lossless optimize
 
-If only `min_ssim:` is provided, the search starts at quality `1`. If both `quality:`
-and `min_ssim:` are provided, `quality:` is treated as the lower starting point and
-the encoder raises quality only if the candidate violates the SSIM floor.
+```ruby
+ImagePack.optimize_bytes(jpeg)
+ImagePack.optimize_file("photo.jpg", output: "photo.optimized.jpg")
+```
 
-If no quality can satisfy the requested floor, `ImagePack::QualityConstraintError`
-is raised. With `execution: :auto`, guarded compression uses the no-GVL/offload
-path instead of the small-image direct path because it may encode/decode several
-candidates. For `compress_pixels`, the reference is the raw pixel buffer itself, not a seed JPEG. RGBA + `min_ssim` is rejected because JPEG cannot represent alpha.
+This rewrites JPEG coefficients without decoding and re-encoding pixels. It is the right path for existing JPEGs when you only want optimized Huffman tables and optional progressive scans.
 
-The metric is a fast native luma SSIM-like guard based on 8x8 blocks, not a full Wang-style Gaussian-window reference implementation. It is intended as a compression guard, not as a general-purpose image quality benchmark.
+Defaults: `progressive: true`, `strip_metadata: false`.
 
-## Execution modes
+If `strip_metadata: true` would remove EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently changing visual orientation.
 
-### Ruby compatibility for offload
+## Raw pixels
 
-ImagePack supports Ruby `>= 3.1.0`. Ruby `>= 3.4.0` is required only for the scheduler-aware `execution: :offload` path.
+```ruby
+ImagePack.compress_pixels(rgb,
+  width: 1920,
+  height: 1080,
+  channels: 3,
+  output: "frame.jpg"
+)
+```
 
-On Ruby 3.1–3.3:
+`channels` must be `1`, `3`, or `4`. JPEG cannot store alpha, so RGBA input needs explicit opt-in:
 
-- `execution: :direct` works.
-- `execution: :nogvl` works.
-- `execution: :auto` works, but never selects `:offload`.
-- explicit `execution: :offload` raises `ImagePack::UnsupportedError`.
+```ruby
+ImagePack.compress_pixels(rgba, width: 100, height: 100, channels: 4, drop_alpha: true)
+```
 
-On Ruby 3.4+:
+## Inspect
 
-- `execution: :offload` is available.
-- `execution: :auto` may select `:offload` when a Fiber scheduler is active.
+```ruby
+ImagePack.inspect_image(jpeg)
+# => { format: :jpeg, width: 1920, height: 1080, channels: 3, bit_depth: 8, decoded_bytes: 6220800 }
+```
 
-Use `ImagePack.offload_safe?` or `ImagePack.build_info[:offload_safe]` to check the native capability at runtime.
+## Execution
 
+Default mode is `:auto`.
 
 ```ruby
-ImagePack.compress(jpeg, execution: :direct)
-ImagePack.compress(jpeg, execution: :nogvl)
-ImagePack.compress(jpeg, execution: :offload)
-ImagePack.compress(jpeg, execution: :auto)
+ImagePack.compress_bytes(jpeg, execution: :auto)
+ImagePack.compress_bytes(jpeg, execution: :direct)
+ImagePack.compress_bytes(jpeg, execution: :nogvl)
+ImagePack.compress_bytes(jpeg, execution: :offload) # Ruby >= 3.4 only
 ```
 
-- `:direct` — executes under GVL, intended for small images.
-- `:nogvl` — uses `rb_nogvl(..., flags: 0)`.
-- `:offload` — uses `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` on Ruby 3.4+; raises `ImagePack::UnsupportedError` on Ruby 3.1–3.3.
-- `:auto` — header-first policy chooses direct/nogvl/offload; on Ruby 3.1–3.3 it never selects offload.
+Use `ImagePack.offload_safe?` or `ImagePack.build_info` to inspect runtime support.
 
-## Cancellation
+Set `IMAGE_PACK_DISABLE_OFFLOAD=1` before loading the gem to disable offload.
 
-`cancellable: true` is supported for `execution: :nogvl`, `:offload`, or `:auto`.
-Cancellation is cooperative at decode, encode, and SSIM-search checkpoints, not instant.
+Long no-GVL/offload calls can be interrupted by raising into the worker thread:
 
-## Metadata / EXIF orientation
-
-`strip_metadata: true` removes metadata. If the source JPEG contains EXIF Orientation, `image_pack` applies that orientation to decoded pixels before stripping metadata, so the visual orientation is preserved. With `strip_metadata: false`, APP/COM markers are preserved across both fast and size-oriented paths.
+```ruby
+worker = Thread.new { ImagePack.compress_bytes(jpeg, execution: :nogvl, cancellable: true) }
+worker.raise(ImagePack::CancelledError, "cancelled")
+worker.join
+```
 
-## Build info
+## Configuration
 
 ```ruby
-ImagePack.build_info
-# => { version: "0.2.2", mozjpeg: "4.1.5", simd: true, offload_safe: true }
+ImagePack.configure do |config|
+  config.execution = :auto
+  config.max_input_size = 256 * 1024 * 1024
+  config.max_output_size = 256 * 1024 * 1024
+  config.max_pixels = 100_000_000
+end
 ```
 
-## Vendoring
-
-The gem is expected to ship vendored native sources/libs, so end users should not install system libjpeg/mozjpeg.
-For repository preparation:
+## Development
 
 ```bash
 bundle exec rake vendor
 bundle exec rake compile
+bundle exec rake test
 ```
 
 `rake vendor` pins MozJPEG `v4.1.5`.
 
-## Current limitations
-
-- Pixel-level `compress` rejects CMYK/YCCK JPEG input because it decodes to RGB/gray before re-encoding. Use `optimize_jpeg` for coefficient-level lossless optimization of existing CMYK/YCCK JPEGs.
-- Arithmetic-coded JPEG support is disabled in the vendored `jconfig.h` for v0.2.2.
-- The SSIM guard is a fast 8x8 luma block metric and still assumes quality/SSIM monotonicity during binary search.
-- `compress(input, ...)` still has a legacy path-vs-bytes heuristic for non-binary `String`; prefer `compress_bytes` / `compress_file` and `optimize_bytes` / `optimize_file` in new code.
-
-## What is intentionally not included
+## Limits
 
-- Jpegli / C++ code
-- AVIF/WebP/PNG
-- FFI
-- shell-out
-- external tempfiles for in-memory output
-- byte-size targets / max-bytes policy
+- JPEG only.
+- Ruby `>= 3.1`; `execution: :offload` requires Ruby `>= 3.4`.
+- Pixel-level `compress` rejects CMYK/YCCK JPEG input; use `optimize_jpeg` for existing CMYK/YCCK JPEGs.
+- Arithmetic-coded JPEG support is disabled in `0.2.4`.
+- Streaming output is not supported; file output uses atomic write-through-temp-file and rename.
+- `ImagePack.compress(input, ...)` keeps a legacy path-vs-bytes heuristic; prefer explicit `*_bytes` / `*_file` helpers.

data/ext/image_pack/extconf.rb

@@ -416,8 +416,8 @@ else
   $CFLAGS += " -O2"
 end
 
-$CFLAGS += " -DIMAGE_PACK_RUBY34_ONLY=1"
 $CFLAGS += build_info[:with_simd] ? " -DIMAGE_PACK_HAS_SIMD=1" : " -DIMAGE_PACK_PURE_C=1"
+$CPPFLAGS += " -DIMAGE_PACK_MOZJPEG_VERSION=\\\"#{MOZJPEG_VERSION}\\\""
 $LIBS += " -lm" unless msvc?
 
 have_header("ruby/thread.h") or abort "ruby/thread.h not found"

data/ext/image_pack/image_pack.c

@@ -40,6 +40,10 @@
 #define TRUE 1
 #endif
 
+#ifndef IMAGE_PACK_MOZJPEG_VERSION
+#define IMAGE_PACK_MOZJPEG_VERSION VERSION
+#endif
+
 #ifndef FALSE
 #define FALSE 0
 #endif
@@ -151,6 +155,9 @@ typedef struct {
 
     atomic_int cancelled;
     int cancellable_requested;
+    int strict;
+    int warning_count;
+    char first_warning[200];
 
     jmp_buf jmpbuf;
     int jmp_armed;
@@ -174,6 +181,7 @@ typedef struct {
 } ip_jpeg_error_mgr;
 
 static VALUE rb_mImagePack;
+static int ip_offload_runtime_enabled = 1;
 static VALUE rb_eImagePackError;
 static VALUE rb_eImagePackInvalidArgumentError;
 static VALUE rb_eImagePackInvalidImageError;
@@ -255,18 +263,20 @@ static int ip_run_optimize_context(ip_context_t *ctx);
 typedef struct {
     VALUE self, input, input_kind, output, output_kind, algo, quality, min_ssim;
     VALUE mozjpeg_trellis, progressive, strip_metadata, execution, cancellable, has_scheduler;
+    VALUE report, strict;
     ip_context_t *ctx;
 } ip_compress_jpeg_call_t;
 
 typedef struct {
     VALUE self, buffer, width, height, channels, output, output_kind, algo, quality, min_ssim;
     VALUE mozjpeg_trellis, progressive, exact_size, execution, cancellable, has_scheduler;
+    VALUE report, strict;
     ip_context_t *ctx;
 } ip_compress_pixels_call_t;
 
 typedef struct {
     VALUE self, input, input_kind, output, output_kind, progressive, strip_metadata;
-    VALUE execution, cancellable, has_scheduler;
+    VALUE execution, cancellable, has_scheduler, strict;
     ip_context_t *ctx;
 } ip_optimize_jpeg_call_t;
 
@@ -287,15 +297,13 @@ static VALUE ip_call_cleanup(VALUE ptr) {
 static VALUE ip_compress_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE algo, VALUE quality, VALUE min_ssim,
                                     VALUE mozjpeg_trellis, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler);
-static VALUE ip_compress_pixels_entry(VALUE self, VALUE buffer, VALUE width, VALUE height,
-                                      VALUE channels, VALUE output, VALUE output_kind, VALUE algo,
-                                      VALUE quality, VALUE min_ssim, VALUE mozjpeg_trellis,
-                                      VALUE progressive, VALUE exact_size, VALUE execution,
-                                      VALUE cancellable, VALUE has_scheduler);
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE report, VALUE strict);
+static VALUE ip_compress_pixels_entry(int argc, VALUE *argv, VALUE self);
 static VALUE ip_optimize_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler);
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE strict);
 
 static VALUE ip_status_to_exception(ip_status_t status) {
     switch (status) {
@@ -543,10 +551,43 @@ static VALUE ip_sym(const char *name) {
     return ID2SYM(rb_intern(name));
 }
 
+static void ip_jpeg_emit_message_collect(j_common_ptr cinfo, int msg_level) {
+    if (msg_level >= 0)
+        return;
+
+    ip_jpeg_error_mgr *err = (ip_jpeg_error_mgr *)cinfo->err;
+    ip_context_t *ctx = err->ctx;
+    if (!ctx)
+        return;
+
+    ctx->warning_count++;
+    if (ctx->first_warning[0] == '\0') {
+        char buffer[JMSG_LENGTH_MAX];
+        (*cinfo->err->format_message)(cinfo, buffer);
+        snprintf(ctx->first_warning, sizeof(ctx->first_warning), "%s", buffer);
+    }
+
+    if (ctx->strict) {
+        if (ctx->status == IP_OK) {
+            char buffer[JMSG_LENGTH_MAX];
+            (*cinfo->err->format_message)(cinfo, buffer);
+            ip_context_set_error(ctx, IP_ERR_INVALID_IMAGE, buffer);
+        }
+        if (ctx->jmp_armed)
+            longjmp(ctx->jmpbuf, 1);
+    }
+}
+
+static void ip_jpeg_output_message_silent(j_common_ptr cinfo) {
+    (void)cinfo;
+}
+
 static struct jpeg_error_mgr *ip_use_error(ip_jpeg_error_mgr *jerr, ip_context_t *ctx,
                                            void (*handler)(j_common_ptr)) {
     struct jpeg_error_mgr *base = jpeg_std_error(&jerr->pub);
     jerr->pub.error_exit = handler;
+    jerr->pub.emit_message = ip_jpeg_emit_message_collect;
+    jerr->pub.output_message = ip_jpeg_output_message_silent;
     jerr->ctx = ctx;
     return base;
 }
@@ -876,6 +917,23 @@ static VALUE ip_finish_output(ip_context_t *ctx, ip_output_kind_t kind) {
     return Qtrue;
 }
 
+static VALUE ip_build_report(ip_context_t *ctx, VALUE output_value) {
+    VALUE hash = rb_hash_new();
+    rb_hash_aset(hash, ip_sym("output"), output_value);
+    rb_hash_aset(hash, ip_sym("quality"), INT2NUM(ctx->selected_quality));
+    rb_hash_aset(hash, ip_sym("ssim"),
+                 ctx->ssim_guard_enabled ? DBL2NUM(ctx->measured_ssim) : Qnil);
+    rb_hash_aset(hash, ip_sym("algo"),
+                 ctx->algo == IP_ALGO_MOZJPEG ? ip_sym("mozjpeg") : ip_sym("jpeg_turbo"));
+    rb_hash_aset(hash, ip_sym("bytesize"), SIZET2NUM(ctx->output_size));
+    rb_hash_aset(hash, ip_sym("input_bytesize"),
+                 SIZET2NUM(ctx->input_size > 0 ? ctx->input_size : ctx->pixel_size));
+    rb_hash_aset(hash, ip_sym("warning_count"), INT2NUM(ctx->warning_count));
+    rb_hash_aset(hash, ip_sym("warning"),
+                 ctx->first_warning[0] ? rb_str_new_cstr(ctx->first_warning) : Qnil);
+    return hash;
+}
+
 static int ip_save_marker(ip_context_t *ctx, int marker, const unsigned char *data,
                           unsigned int len) {
     if (ctx->preserved_marker_count == ctx->preserved_marker_capacity) {
@@ -1287,7 +1345,7 @@ static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode)
         ip_write_preserved_markers(ctx, &cinfo);
 
     while (cinfo.next_scanline < cinfo.image_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG encode cancelled");
 
         JSAMPROW rows[16];
@@ -1398,7 +1456,7 @@ static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, i
         IP_FAIL_GOTO(ctx, IP_ERR_OOM, "failed to allocate decoded pixel buffer");
 
     while (cinfo.output_scanline < cinfo.output_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG decode cancelled");
 
         JSAMPROW rows[16];
@@ -1558,7 +1616,7 @@ static int ip_decode_jpeg_to_luma_buffer(ip_context_t *ctx, const unsigned char
         IP_FAIL_GOTO(ctx, IP_ERR_OOM, "failed to allocate luma buffer");
 
     while (cinfo.output_scanline < cinfo.output_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG luma decode cancelled");
 
         JSAMPROW rows[16];
@@ -1791,8 +1849,7 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
     }
 
     if (reference_channels == 4) {
-        ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "min_ssim is not supported for RGBA input in v0.2.2");
+        ip_context_set_error(ctx, IP_ERR_UNSUPPORTED, "min_ssim is not supported for RGBA input");
         return 0;
     }
 
@@ -1811,7 +1868,7 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
     int best_seen_quality = 0;
 
     while (search_low <= search_high) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled)) {
+        if (atomic_load(&ctx->cancelled)) {
             free(reference_luma);
             free(best_jpeg);
             ip_context_set_error(ctx, IP_ERR_CANCELLED, "SSIM-guarded JPEG encode cancelled");
@@ -1959,7 +2016,7 @@ static int ip_lossless_optimize_jpeg(ip_context_t *ctx) {
     jpeg_mem_src(&srcinfo, ctx->input_data, (unsigned long)ctx->input_size);
     ip_setup_marker_saving(&srcinfo, ctx->strip_metadata);
 
-    if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+    if (atomic_load(&ctx->cancelled))
         IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "lossless JPEG optimize cancelled");
 
     if (jpeg_read_header(&srcinfo, TRUE) != JPEG_HEADER_OK)
@@ -1989,7 +2046,7 @@ static int ip_lossless_optimize_jpeg(ip_context_t *ctx) {
 
     jpeg_mem_dest(&dstinfo, &ctx->transient_jpeg_buf, &jpeg_size);
 
-    if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+    if (atomic_load(&ctx->cancelled))
         IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "lossless JPEG optimize cancelled");
 
     jpeg_write_coefficients(&dstinfo, coef_arrays);
@@ -2035,7 +2092,7 @@ static int ip_mozjpeg_compress(ip_context_t *ctx) {
 
 static ip_execution_t ip_async_execution(const ip_context_t *ctx) {
 #if IMAGE_PACK_HAS_OFFLOAD_SAFE
-    return ctx->has_scheduler ? IP_EXEC_OFFLOAD : IP_EXEC_NOGVL;
+    return (ip_offload_runtime_enabled && ctx->has_scheduler) ? IP_EXEC_OFFLOAD : IP_EXEC_NOGVL;
 #else
     (void)ctx;
     return IP_EXEC_NOGVL;
@@ -2105,12 +2162,16 @@ static int ip_run_context(ip_context_t *ctx) {
         rb_nogvl(ip_run_encode_nogvl, ctx, ip_unblock_function, ctx, RB_NOGVL_OFFLOAD_SAFE);
 #else
         ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "offload execution requires Ruby >= 3.4; use :nogvl or :auto");
+                             "offload execution is unavailable in this runtime; it requires Ruby "
+                             ">= 3.4 and IMAGE_PACK_DISABLE_OFFLOAD must not be set");
 #endif
     } else {
         ip_context_set_error(ctx, IP_ERR_INVALID_ARGUMENT, "invalid resolved execution mode");
     }
 
+    if (ctx->resolved_execution != IP_EXEC_DIRECT)
+        rb_thread_check_ints();
+
     return ctx->status == IP_OK;
 }
 
@@ -2133,12 +2194,16 @@ static int ip_run_optimize_context(ip_context_t *ctx) {
         rb_nogvl(ip_run_optimize_nogvl, ctx, ip_unblock_function, ctx, RB_NOGVL_OFFLOAD_SAFE);
 #else
         ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "offload execution requires Ruby >= 3.4; use :nogvl or :auto");
+                             "offload execution is unavailable in this runtime; it requires Ruby "
+                             ">= 3.4 and IMAGE_PACK_DISABLE_OFFLOAD must not be set");
 #endif
     } else {
         ip_context_set_error(ctx, IP_ERR_INVALID_ARGUMENT, "invalid resolved execution mode");
     }
 
+    if (ctx->resolved_execution != IP_EXEC_DIRECT)
+        rb_thread_check_ints();
+
     return ctx->status == IP_OK;
 }
 
@@ -2220,6 +2285,7 @@ static VALUE ip_compress_jpeg_entry_body(VALUE ptr) {
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     apply_configuration(call->self, ctx);
 
     ip_input_kind_t in_kind = ip_parse_input_kind(call->input_kind);
@@ -2242,17 +2308,23 @@ static VALUE ip_compress_jpeg_entry_body(VALUE ptr) {
     }
 
     ip_run_context(ctx);
+    if (ip_bool_value(call->report)) {
+        VALUE output_value = ip_finish_output(ctx, out_kind);
+        return ip_build_report(ctx, output_value);
+    }
     return ip_finish_output(ctx, out_kind);
 }
 
 static VALUE ip_compress_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE algo, VALUE quality, VALUE min_ssim,
                                     VALUE mozjpeg_trellis, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler) {
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE report, VALUE strict) {
     ip_compress_jpeg_call_t call = {
         self,           input,     input_kind,  output,          output_kind,
         algo,           quality,   min_ssim,    mozjpeg_trellis, progressive,
-        strip_metadata, execution, cancellable, has_scheduler,   NULL};
+        strip_metadata, execution, cancellable, has_scheduler,   report,
+        strict,         NULL};
     return rb_ensure(ip_compress_jpeg_entry_body, (VALUE)&call, ip_call_cleanup, (VALUE)&call.ctx);
 }
 
@@ -2277,6 +2349,7 @@ static VALUE ip_compress_pixels_entry_body(VALUE ptr) {
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     apply_configuration(call->self, ctx);
 
     if (!ip_prepare_output_path(ctx, call->output, out_kind) ||
@@ -2297,18 +2370,19 @@ static VALUE ip_compress_pixels_entry_body(VALUE ptr) {
     }
 
     ip_run_context(ctx);
+    if (ip_bool_value(call->report)) {
+        VALUE output_value = ip_finish_output(ctx, out_kind);
+        return ip_build_report(ctx, output_value);
+    }
     return ip_finish_output(ctx, out_kind);
 }
 
-static VALUE ip_compress_pixels_entry(VALUE self, VALUE buffer, VALUE width, VALUE height,
-                                      VALUE channels, VALUE output, VALUE output_kind, VALUE algo,
-                                      VALUE quality, VALUE min_ssim, VALUE mozjpeg_trellis,
-                                      VALUE progressive, VALUE exact_size, VALUE execution,
-                                      VALUE cancellable, VALUE has_scheduler) {
-    ip_compress_pixels_call_t call = {
-        self,        buffer,        width,    height,          channels,    output,     output_kind,
-        algo,        quality,       min_ssim, mozjpeg_trellis, progressive, exact_size, execution,
-        cancellable, has_scheduler, NULL};
+static VALUE ip_compress_pixels_entry(int argc, VALUE *argv, VALUE self) {
+    rb_check_arity(argc, 17, 17);
+    ip_compress_pixels_call_t call = {self,     argv[0],  argv[1],  argv[2],  argv[3],
+                                      argv[4],  argv[5],  argv[6],  argv[7],  argv[8],
+                                      argv[9],  argv[10], argv[11], argv[12], argv[13],
+                                      argv[14], argv[15], argv[16], NULL};
     return rb_ensure(ip_compress_pixels_entry_body, (VALUE)&call, ip_call_cleanup,
                      (VALUE)&call.ctx);
 }
@@ -2326,6 +2400,7 @@ static VALUE ip_optimize_jpeg_entry_body(VALUE ptr) {
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     ctx->ssim_guard_enabled = 0;
     apply_configuration(call->self, ctx);
 
@@ -2354,10 +2429,11 @@ static VALUE ip_optimize_jpeg_entry_body(VALUE ptr) {
 
 static VALUE ip_optimize_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler) {
-    ip_optimize_jpeg_call_t call = {
-        self,           input,     input_kind,  output,        output_kind, progressive,
-        strip_metadata, execution, cancellable, has_scheduler, NULL};
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE strict) {
+    ip_optimize_jpeg_call_t call = {self,        input,         input_kind,     output,
+                                    output_kind, progressive,   strip_metadata, execution,
+                                    cancellable, has_scheduler, strict,         NULL};
     return rb_ensure(ip_optimize_jpeg_entry_body, (VALUE)&call, ip_call_cleanup, (VALUE)&call.ctx);
 }
 
@@ -2403,14 +2479,17 @@ IMAGE_PACK_INIT_EXPORT void Init_image_pack(void) {
     for (size_t i = 0; i < IP_ARRAY_LEN(exceptions); i++)
         *exceptions[i].slot = rb_const_get(rb_mImagePack, rb_intern(exceptions[i].name));
 
-    rb_define_const(rb_mImagePack, "NATIVE_MOZJPEG_VERSION", rb_str_new_cstr(VERSION));
+    rb_define_const(rb_mImagePack, "NATIVE_MOZJPEG_VERSION",
+                    rb_str_new_cstr(IMAGE_PACK_MOZJPEG_VERSION));
 #if defined(IMAGE_PACK_HAS_SIMD)
     rb_define_const(rb_mImagePack, "NATIVE_SIMD", Qtrue);
 #else
     rb_define_const(rb_mImagePack, "NATIVE_SIMD", Qfalse);
 #endif
+    ip_offload_runtime_enabled = (getenv("IMAGE_PACK_DISABLE_OFFLOAD") == NULL) ? 1 : 0;
 #if IMAGE_PACK_HAS_OFFLOAD_SAFE
-    rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE", Qtrue);
+    rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE",
+                    ip_offload_runtime_enabled ? Qtrue : Qfalse);
 #else
     rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE", Qfalse);
 #endif
@@ -2419,9 +2498,9 @@ IMAGE_PACK_INIT_EXPORT void Init_image_pack(void) {
         const char *name;
         VALUE (*fn)(ANYARGS);
         int arity;
-    } methods[] = {{"__compress_jpeg", (VALUE (*)(ANYARGS))ip_compress_jpeg_entry, 13},
-                   {"__compress_pixels", (VALUE (*)(ANYARGS))ip_compress_pixels_entry, 15},
-                   {"__optimize_jpeg", (VALUE (*)(ANYARGS))ip_optimize_jpeg_entry, 9},
+    } methods[] = {{"__compress_jpeg", (VALUE (*)(ANYARGS))ip_compress_jpeg_entry, 15},
+                   {"__compress_pixels", (VALUE (*)(ANYARGS))ip_compress_pixels_entry, -1},
+                   {"__optimize_jpeg", (VALUE (*)(ANYARGS))ip_optimize_jpeg_entry, 10},
                    {"__inspect_image", (VALUE (*)(ANYARGS))ip_inspect_image_entry, 2}};
     for (size_t i = 0; i < IP_ARRAY_LEN(methods); i++) {
         rb_define_singleton_method(rb_mImagePack, methods[i].name, methods[i].fn, methods[i].arity);

data/lib/image_pack/configuration.rb

@@ -42,7 +42,7 @@ module ImagePack
 
       if value == :offload && ImagePack.respond_to?(:offload_safe?) && !ImagePack.offload_safe?
         raise UnsupportedError,
-              "execution: :offload requires Ruby >= 3.4.0; use execution: :nogvl or :auto"
+              "execution: :offload is unavailable in this runtime; it requires Ruby >= 3.4.0 and IMAGE_PACK_DISABLE_OFFLOAD must not be set"
       end
 
       @execution = value

data/lib/image_pack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ImagePack
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/lib/image_pack.rb

@@ -90,10 +90,12 @@ module ImagePack
                       progressive: true,
                       strip_metadata: false,
                       execution: nil,
-                      cancellable: false)
+                      cancellable: false,
+                      strict: false)
       validate_boolean!(:progressive, progressive)
       validate_boolean!(:strip_metadata, strip_metadata)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:strict, strict)
       execution ||= configuration.execution
       validate_execution!(execution)
       validate_execution_supported!(execution)
@@ -109,7 +111,8 @@ module ImagePack
                       strip_metadata ? 1 : 0,
                       execution,
                       cancellable ? 1 : 0,
-                      has_scheduler ? 1 : 0)
+                      has_scheduler ? 1 : 0,
+                      strict ? 1 : 0)
     end
 
     def compress(input,
@@ -121,13 +124,17 @@ module ImagePack
                  progressive: false,
                  strip_metadata: true,
                  execution: nil,
-                 cancellable: false)
+                 cancellable: false,
+                 report: false,
+                 strict: false)
       validate_algo!(algo)
       validate_min_ssim!(min_ssim)
       validate_boolean!(:mozjpeg_trellis, mozjpeg_trellis)
       validate_boolean!(:progressive, progressive)
       validate_boolean!(:strip_metadata, strip_metadata)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:report, report)
+      validate_boolean!(:strict, strict)
       quality_was_given = !quality.nil?
       effective_quality = quality_was_given ? quality : DEFAULT_QUALITY
       effective_quality = 1 if min_ssim && !quality_was_given
@@ -150,7 +157,9 @@ module ImagePack
                       strip_metadata ? 1 : 0,
                       execution,
                       cancellable ? 1 : 0,
-                      has_scheduler ? 1 : 0)
+                      has_scheduler ? 1 : 0,
+                      report ? 1 : 0,
+                      strict ? 1 : 0)
     end
 
     def compress_pixels(buffer,
@@ -166,7 +175,9 @@ module ImagePack
                         drop_alpha: nil,
                         exact_size: false,
                         execution: nil,
-                        cancellable: false)
+                        cancellable: false,
+                        report: false,
+                        strict: false)
       validate_pixel_buffer!(buffer)
       validate_algo!(algo)
       validate_min_ssim!(min_ssim)
@@ -175,6 +186,8 @@ module ImagePack
       validate_drop_alpha!(drop_alpha)
       validate_boolean!(:exact_size, exact_size)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:report, report)
+      validate_boolean!(:strict, strict)
       quality_was_given = !quality.nil?
       effective_quality = quality_was_given ? quality : DEFAULT_QUALITY
       effective_quality = 1 if min_ssim && !quality_was_given
@@ -214,7 +227,9 @@ module ImagePack
                         exact_size ? 1 : 0,
                         execution,
                         cancellable ? 1 : 0,
-                        has_scheduler ? 1 : 0)
+                        has_scheduler ? 1 : 0,
+                        report ? 1 : 0,
+                        strict ? 1 : 0)
     end
 
     def inspect_image(input)
@@ -251,7 +266,7 @@ module ImagePack
       return :return_string if output.nil?
       return :path if output.is_a?(String) || output.is_a?(Pathname)
 
-      raise InvalidArgumentError, "output must be nil, String path, or Pathname in v0.2.2"
+      raise InvalidArgumentError, "output must be nil, String path, or Pathname"
     end
 
     def validate_algo!(algo)
@@ -296,7 +311,7 @@ module ImagePack
       return if offload_safe?
 
       raise UnsupportedError,
-            "execution: :offload requires Ruby >= 3.4.0; use execution: :nogvl or :auto"
+            "execution: :offload is unavailable in this runtime; it requires Ruby >= 3.4.0 and IMAGE_PACK_DISABLE_OFFLOAD must not be set"
     end
 
     def validate_dimensions!(width, height, channels)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: image_pack
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Roman Haydarov
@@ -80,9 +80,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.21'
-description: Single API, vendored pure-C MozJPEG/libjpeg codec, no tempfiles, Ruby
-  3.1+ native JPEG execution; Ruby 3.4+ enables Fiber::Scheduler-aware offload. Ships
-  vendored C sources — no system libjpeg, git, or CMake required.
+description: Single API, vendored pure-C MozJPEG/libjpeg codec, in-memory compression
+  and atomic file output, Ruby 3.1+ native JPEG execution; Ruby 3.4+ enables Fiber::Scheduler-aware
+  offload. Ships vendored C sources — no system libjpeg, git, or CMake required.
 email:
 - romnhajdarov@gmail.com
 executables: []