Native Resource Lifecycle

libvips images are not ordinary garbage-collected values. Each VipsImage owns native state and implements AutoCloseable.

Scope every derived image

Loading, resizing, cropping, and other operations can each produce a new native image. Close the source and every result:

runtime.load(path).use { source ->
    source.resize(640, 480).use { resized ->
        resized.writeTo(output)
    }
}

Do not return a VipsImage from a scope that already closed it. For application APIs, prefer returning encoded bytes, a file result, or a caller-owned closeable with explicit ownership.

Initialize once, shut down last

Initialize either JVipsRuntime or FfmVipsRuntime during application startup. Shutdown is process-wide: no request, worker, or writer may still use libvips afterward. Framework destruction order must stop traffic and workers before shutting down the runtime.

Isolate native tests

The release config runs JNI and FFM tests with one test class per fork and one parallel fork. Preserve this isolation when adding CI jobs. Native failure can poison process state, and two backends can compete for the same global library.

Cancellation and partial output

Coroutine cancellation does not remove the need for use. Close in structured scopes and write final output atomically when partial files are unsafe. Bound input bytes and pixels before entering native decode.

Sources

• VipsImage contract
• Java 21 native test isolation
• Java 25 native test isolation