feat(concurrency): add a shared shutdown cleanup registry

Author: intisy

src/main/java/io/github/intisy/utils/concurrency/Cleanups.java

@@ -0,0 +1,137 @@
+package io.github.intisy.utils.concurrency;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Deque;
+import java.util.List;
+
+/**
+ * Closers that must run when the JVM stops, however it stops.
+ *
+ * <p>Register a closer when you acquire something a dying JVM would otherwise leak, and unregister
+ * it once you have released it yourself. {@link #installShutdownHook()} arms the single hook that
+ * runs whatever is still registered.
+ *
+ * @author Finn Birich
+ * @implNote a finally block covers an exception and nothing else. It does not run on Ctrl+C, and it
+ * does not run on {@code System.exit}, which a command line tool reaches on every failure path. So
+ * an interrupted run leaves its child processes alive and its remote resources allocated with
+ * nobody reading the result. A hard kill runs nothing at all, which is what a startup sweep exists
+ * for; this covers the two paths a process can still act on.
+ * @implNote one shared registry with one hook, rather than a hook per library. Several independent
+ * shutdown hooks in a JVM run in undefined order relative to each other, so a library that kills a
+ * process another library is still talking to produces failures that depend on thread scheduling.
+ */
+@SuppressWarnings("unused")
+public final class Cleanups {
+    private static final long DEFAULT_BUDGET_MS = 10_000;
+    private static final Cleanups SHARED = new Cleanups(DEFAULT_BUDGET_MS);
+
+    private static boolean hookInstalled;
+
+    /**
+     * One thing to release. {@link AutoCloseable} rather than a type of our own, because the shape
+     * is identical and callers already have methods that fit it.
+     */
+    public interface Closer extends AutoCloseable {
+        @Override
+        void close() throws Exception;
+    }
+
+    /**
+     * A registered closer, and the handle used to unregister it again.
+     */
+    public static final class Registration {
+        private final String what;
+        private final Closer closer;
+
+        Registration(String what, Closer closer) {
+            this.what = what;
+            this.closer = closer;
+        }
+
+        public String what() {
+            return what;
+        }
+
+        public Closer closer() {
+            return closer;
+        }
+    }
+
+    private final Deque<Registration> pending = new ArrayDeque<Registration>();
+    private final long budgetMs;
+
+    public Cleanups(long budgetMs) {
+        this.budgetMs = budgetMs;
+    }
+
+    public static Cleanups shared() {
+        return SHARED;
+    }
+
+    public static synchronized void installShutdownHook() {
+        if (hookInstalled) {
+            return;
+        }
+        Runtime.getRuntime().addShutdownHook(new Thread(new Runnable() {
+            @Override
+            public void run() {
+                SHARED.runAll();
+            }
+        }, "cleanups"));
+        hookInstalled = true;
+    }
+
+    public synchronized Registration register(String what, Closer closer) {
+        Registration registration = new Registration(what, closer);
+        pending.push(registration);
+        return registration;
+    }
+
+    /**
+     * @implNote every caller unregisters after cleaning up itself, so a long run does not accumulate
+     * closers for work that is already finished and the hook does not repeat it.
+     */
+    public synchronized void unregister(Registration registration) {
+        pending.remove(registration);
+    }
+
+    public synchronized int pendingCount() {
+        return pending.size();
+    }
+
+    /**
+     * @implNote reverse order of registration, guarded per closer and bounded overall. A shutdown
+     * hook that hangs prevents the JVM from exiting at all, so exhausting the budget names what was
+     * skipped rather than waiting: an operator who has to finish by hand needs to be told which
+     * things.
+     */
+    public void runAll() {
+        long deadline = System.currentTimeMillis() + budgetMs;
+        for (Registration registration = next(); registration != null; registration = next()) {
+            if (System.currentTimeMillis() >= deadline) {
+                reportSkipped(registration);
+                return;
+            }
+            try {
+                registration.closer().close();
+            } catch (Exception failure) {
+                System.err.println("cleanup '" + registration.what() + "' failed: " + failure);
+            }
+        }
+    }
+
+    private synchronized Registration next() {
+        return pending.poll();
+    }
+
+    private void reportSkipped(Registration current) {
+        List<String> skipped = new ArrayList<String>();
+        skipped.add(current.what());
+        for (Registration registration = next(); registration != null; registration = next()) {
+            skipped.add(registration.what());
+        }
+        System.err.println("cleanup budget of " + budgetMs + "ms exhausted, NOT cleaned up: " + skipped);
+    }
+}

src/test/java/io/github/intisy/utils/concurrency/CleanupsTest.java

@@ -0,0 +1,129 @@
+package io.github.intisy.utils.concurrency;
+
+import org.junit.jupiter.api.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.nio.charset.Charset;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class CleanupsTest {
+
+    /**
+     * Reverse order is not decoration: a closer registered later can depend on something an earlier
+     * one releases, so running forwards would tear the dependency down first.
+     */
+    @Test
+    void runsClosersInReverseOrderOfRegistration() {
+        Cleanups cleanups = new Cleanups(10_000);
+        List<String> order = new ArrayList<String>();
+
+        cleanups.register("first", record(order, "first"));
+        cleanups.register("second", record(order, "second"));
+        cleanups.register("third", record(order, "third"));
+        cleanups.runAll();
+
+        assertEquals(Arrays.asList("third", "second", "first"), order);
+    }
+
+    @Test
+    void unregisteredCloserDoesNotRun() {
+        Cleanups cleanups = new Cleanups(10_000);
+        List<String> order = new ArrayList<String>();
+
+        Cleanups.Registration kept = cleanups.register("kept", record(order, "kept"));
+        Cleanups.Registration dropped = cleanups.register("dropped", record(order, "dropped"));
+        cleanups.unregister(dropped);
+        cleanups.runAll();
+
+        assertEquals(Collections.singletonList("kept"), order);
+        assertEquals(0, cleanups.pendingCount());
+        assertEquals("kept", kept.what());
+    }
+
+    /**
+     * A closer that throws must not strand the ones registered before it, which is why each is
+     * guarded individually rather than the loop being wrapped once.
+     */
+    @Test
+    void aFailingCloserDoesNotStopTheRest() {
+        Cleanups cleanups = new Cleanups(10_000);
+        List<String> order = new ArrayList<String>();
+
+        cleanups.register("early", record(order, "early"));
+        cleanups.register("boom", new Cleanups.Closer() {
+            @Override
+            public void close() {
+                throw new IllegalStateException("closer failed");
+            }
+        });
+        String errors = captureStderr(cleanups);
+
+        assertEquals(Collections.singletonList("early"), order);
+        assertTrue(errors.contains("boom"), "expected the failure to name the closer, got: " + errors);
+    }
+
+    /**
+     * A shutdown hook that hangs stops the JVM exiting at all, so an exhausted budget must abandon
+     * the remaining closers and say which ones it abandoned.
+     */
+    @Test
+    void anExhaustedBudgetAbandonsTheRestAndNamesThem() {
+        Cleanups cleanups = new Cleanups(0);
+        List<String> order = new ArrayList<String>();
+
+        cleanups.register("never-runs", record(order, "never-runs"));
+        String errors = captureStderr(cleanups);
+
+        assertEquals(Collections.<String>emptyList(), order);
+        assertTrue(errors.contains("budget"), "expected the budget message, got: " + errors);
+        assertTrue(errors.contains("never-runs"), "expected the skipped closer named, got: " + errors);
+        assertEquals(0, cleanups.pendingCount(), "an abandoned run must still drain the registry");
+    }
+
+    @Test
+    void pendingCountTracksRegistrationAndRun() {
+        Cleanups cleanups = new Cleanups(10_000);
+        assertEquals(0, cleanups.pendingCount());
+
+        cleanups.register("one", record(new ArrayList<String>(), "one"));
+        cleanups.register("two", record(new ArrayList<String>(), "two"));
+        assertEquals(2, cleanups.pendingCount());
+
+        cleanups.runAll();
+        assertEquals(0, cleanups.pendingCount());
+    }
+
+    @Test
+    void sharedIsOneInstanceForTheWholeJvm() {
+        assertSame(Cleanups.shared(), Cleanups.shared());
+    }
+
+    private static Cleanups.Closer record(final List<String> order, final String name) {
+        return new Cleanups.Closer() {
+            @Override
+            public void close() {
+                order.add(name);
+            }
+        };
+    }
+
+    private static String captureStderr(Cleanups cleanups) {
+        PrintStream original = System.err;
+        ByteArrayOutputStream captured = new ByteArrayOutputStream();
+        try {
+            System.setErr(new PrintStream(captured, true));
+            cleanups.runAll();
+        } finally {
+            System.setErr(original);
+        }
+        return new String(captured.toByteArray(), Charset.forName("UTF-8"));
+    }
+}