Add operationalisation section to README, guidance on jemalloc

Author: james-bench

CONTRIBUTING.md

@@ -15,6 +15,9 @@ library is already used by some larger businesses (which is cool!), and I care a
 Please discuss any bigger changes with me **before** submitting a Pull Request - I can help you refine your idea better
 that way, and I don't want to waste anybody's time: [Discussions](https://github.com/lopcode/vips-ffm/discussions).
 
+As part of a pull request I will probably edit commits on the branch, and will squash them down, but will be careful to
+retain your contributor metadata so you're named appropriately as a contributor on GitHub.
+
 I haven't currently defined a code of conduct for this project specifically, but please refer to the CoC [in libvips](https://github.com/libvips/libvips/blob/master/CODE_OF_CONDUCT.md)
 for guidance on expected behaviour.
 

README.md

@@ -193,6 +193,43 @@ like Android where it's hard to set the system library path), you can do so usin
 * glib: `vipsffm.libpath.glib.override`
 * gobject: `vipsffm.libpath.gobject.override`
 
+## Operationalisation
+
+libvips maintain [a checklist](https://www.libvips.org/API/8.17/developer-checklist.html#linux-memory-allocator) of
+things to be aware of when using the library. Of particular note for vips-ffm is memory usage - especially if the library
+is used for long-running application (like a server).
+
+#### Operation Cache
+
+At the time of writing, libvips maintains a cache of the 100 most recent operations ([see docs](https://www.libvips.org/API/8.17/how-it-works.html#operation-cache)).
+If running an image proxy, or something that processes lots of different images, you won't see any benefit, and can disable it:
+
+```java
+Vips.init();
+Vips.disableOperationCache();
+```
+
+### Memory Allocation
+
+On glibc-based Linux systems (e.g. Debian, Red Hat), the default memory allocator performs poorly for long-running,
+multithreaded processes with frequent small allocations. Using an alternative allocator like jemalloc can reduce the
+off-heap footprint of the JVM when using libvips.
+
+Note that the jemalloc project is going through [some turbulence](https://jasone.github.io/2025/06/12/jemalloc-postmortem/)
+at the moment. Facebook have [forked it](https://github.com/facebook/jemalloc), though its maintenance status is
+currently unknown.
+
+An example of using jemalloc on Ubuntu:
+1. Install jemalloc
+   ```sh
+   apt install jemalloc-dev
+   ```
+2. Set the `LD_PRELOAD` environment variable before running your application.
+   ```sh
+   export LD_PRELOAD=/usr/local/lib/libjemalloc.so
+   java -jar ...
+   ```
+
 ## Project goals
 
 Ideas and suggestions are welcome, but please make sure they fit in to these goals, or you have a good argument about
@@ -224,4 +261,4 @@ Thank you for being enthusiastic about the project!
   * And only after a GitHub Release is made
   * Run `./publish_release_to_maven_central.sh <version matching github release version, including v prefix>` 
 
-[1]: https://docs.oracle.com/en/java/javase/23/core/memory-segments-and-arenas.html
+[1]: https://docs.oracle.com/en/java/javase/23/core/memory-segments-and-arenas.html

core/src/main/java/app/photofox/vipsffm/Vips.java

@@ -17,6 +17,9 @@ public static void init(boolean allowUntrusted, boolean detectLeaks) {
         VipsHelper.leak_set(detectLeaks);
     }
 
+    ///  Provides a scoped arena to provide a memory boundary for running libvips operations
+    ///
+    /// After the scope has ended, any memory allocated whilst using libvips within it will be freed
     public static void run(VipsRunnable runnable) {
         try (var arena = Arena.ofConfined()) {
             runnable.run(arena);
@@ -26,4 +29,22 @@ public static void run(VipsRunnable runnable) {
     public static void shutdown() {
         VipsHelper.shutdown();
     }
+
+    /// Permits untrusted operations, such as loading PDFs
+    ///
+    /// vips-ffm blocks these by default - see the [libvips docs](https://www.libvips.org/API/8.17/func.block_untrusted_set.html)
+    /// for guidance
+    public static void allowUntrustedOperations() {
+        VipsHelper.block_untrusted_set(false);
+    }
+
+    /// Disables the libvips operations cache
+    ///
+    /// At the time of writing libvips caches 100 operations by default, which might not be useful in long-running
+    /// applications (like servers).
+    ///
+    /// See also: [libvips docs](https://www.libvips.org/API/8.17/how-it-works.html#operation-cache)
+    public static void disableOperationCache() {
+        VipsHelper.cache_set_max(0);
+    }
 }

docker_tests/ubuntu-2404-jemalloc/Dockerfile

@@ -0,0 +1,13 @@
+FROM ubuntu:24.04
+ENV JAVA_HOME=/opt/java/openjdk
+COPY --from=eclipse-temurin:23 $JAVA_HOME $JAVA_HOME
+ENV PATH="${JAVA_HOME}/bin:${PATH}"
+
+COPY sample /opt/sample
+COPY run_samples.sh /opt/run_samples.sh
+
+RUN apt update && apt install libvips-dev jemalloc-dev -y
+RUN vips --version
+
+WORKDIR /opt
+CMD ./run_samples.sh

run_docker_tests.sh

@@ -7,7 +7,7 @@ echo "building samples..."
 echo "running docker tests..."
 WORKSPACE_DIR="$PWD"
 
-docker_tests=("debian-12" "ubuntu-2404")
+docker_tests=("debian-12" "ubuntu-2404" "ubuntu-2404-jemalloc")
 for docker_test in "${docker_tests[@]}"; do
   echo "testing \"$docker_test\""
   pushd "docker_tests/$docker_test"

run_samples.sh

@@ -15,6 +15,11 @@ if [[ "$OSTYPE" == "darwin"* ]]; then
   export JAVA_PATH_OPTS="-Dvipsffm.libpath.vips.override=/opt/homebrew/lib/libvips.dylib"
 fi
 
+if test -f /usr/local/lib/libjemalloc.so; then
+  echo "found jemalloc - using it"
+  export LD_PRELOAD=$LD_PRELOAD;/usr/local/lib/libjemalloc.so
+fi
+
 echo "running samples..."
 java $JAVA_PATH_OPTS -jar sample/build/libs/sample-all.jar 2>&1 | tee sample_output.log