andrewaylett · andrewaylett · May 29, 2025 · May 19, 2025 · Copilot · May 29, 2025
diff --git a/gradle/gradle-daemon-jvm.properties b/gradle/gradle-daemon-jvm.properties
@@ -0,0 +1,12 @@
+#This file is generated by updateDaemonJvm
+toolchainUrl.FREE_BSD.AARCH64=https\://api.foojay.io/disco/v3.0/ids/44715d7d372da8362a7c7e78c011e897/redirect
+toolchainUrl.FREE_BSD.X86_64=https\://api.foojay.io/disco/v3.0/ids/ce3ff383a4a3e769ac7d9ca5903aa698/redirect
+toolchainUrl.LINUX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/44715d7d372da8362a7c7e78c011e897/redirect
+toolchainUrl.LINUX.X86_64=https\://api.foojay.io/disco/v3.0/ids/ce3ff383a4a3e769ac7d9ca5903aa698/redirect
+toolchainUrl.MAC_OS.AARCH64=https\://api.foojay.io/disco/v3.0/ids/5956054eea3fda78f9a8d1b47e24e080/redirect
+toolchainUrl.MAC_OS.X86_64=https\://api.foojay.io/disco/v3.0/ids/d73443cae2d063f4bc06ff437f9a3e6b/redirect
+toolchainUrl.UNIX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/44715d7d372da8362a7c7e78c011e897/redirect
+toolchainUrl.UNIX.X86_64=https\://api.foojay.io/disco/v3.0/ids/ce3ff383a4a3e769ac7d9ca5903aa698/redirect
+toolchainUrl.WINDOWS.AARCH64=https\://api.foojay.io/disco/v3.0/ids/7fe1613e82362b3e87de352406cbc016/redirect
+toolchainUrl.WINDOWS.X86_64=https\://api.foojay.io/disco/v3.0/ids/747369971f89e1f6bc182b737d168306/redirect
+toolchainVersion=24
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -3,9 +3,11 @@ arcmutate = "1.2.2"
 checkerframework = "3.49.3"
 checkstyle = "10.24.0"
 hamcrest = "3.0"
+jetbrains = "26.0.2"
 jspecify = "1.0.0"
 junit = "5.12.2"
 logback = "1.5.18"
+mockito = "5.17.0"
 pitest = "1.19.4"
 pitest-accelerator-junit5 = "1.0.6"
 pitest-git-plugin = "1.1.4"
@@ -19,9 +21,11 @@ arcmutate-base = { module = "com.groupcdg.arcmutate:base", version.ref = "arcmut
 checkerframework = { module = "org.checkerframework:checker", version.ref = "checkerframework" }
 checkerframework-qual = { module = "org.checkerframework:checker-qual", version.ref = "checkerframework" }
 hamcrest = { module = "org.hamcrest:hamcrest", version.ref = "hamcrest" }
+jetbrains-annotations = { module = "org.jetbrains:annotations", version.ref = "jetbrains" }
 jspecify = { module = "org.jspecify:jspecify", version.ref = "jspecify" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
 logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
+mockito = { module = "org.mockito:mockito-core", version.ref = "mockito" }
 pitest = { module = "org.pitest:pitest", version.ref = "pitest" }
 pitest-accelerator-junit5 = { module = "com.groupcdg.pitest:pitest-accelerator-junit5", version.ref = "pitest-accelerator-junit5" }
 pitest-git-plugin = { module = "com.groupcdg:pitest-git-plugin", version.ref = "pitest-git-plugin" }

diff --git a/lib/build.gradle.kts b/lib/build.gradle.kts
@@ -30,9 +30,11 @@ val internal: Configuration by configurations.creating
 
 dependencies {
   implementation(libs.checkerframework.qual)
+  implementation(libs.jetbrains.annotations)
   implementation(libs.jspecify)
   implementation(libs.spotbugs.annotations)
   testImplementation(libs.hamcrest)
+  testImplementation(libs.mockito)
 
   checkerFramework(libs.checkerframework)
 

diff --git a/lib/src/main/java/eu/aylett/arc/Arc.java b/lib/src/main/java/eu/aylett/arc/Arc.java
@@ -35,6 +35,8 @@
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
+import static eu.aylett.arc.internal.Invariants.checkNotNull;
+
 /**
  * The Arc class provides a cache mechanism with a specified capacity. It uses a
  * loader function to load values and a ForkJoinPool for parallel processing.
@@ -126,8 +128,8 @@ public Arc(int capacity, Function<? super K, V> loader, Duration expiry, Duratio
     if (!refresh.isPositive()) {
       throw new IllegalArgumentException("Refresh must be positive");
     }
-    this.loader = loader;
-    this.pool = pool;
+    this.loader = checkNotNull(loader);
+    this.pool = checkNotNull(pool);
     elements = new ConcurrentHashMap<>();
     inner = new InnerArc(Math.max(capacity / 2, 1), new DelayManager(expiry, refresh, clock));
     unowned = inner.unowned;
@@ -165,6 +167,7 @@ public void weakExpire() {
    */
   @MayReleaseLocks
   public V get(K key) {
+    checkNotNull(key, "key cannot be null");
     while (true) {
       var ref = elements.computeIfAbsent(key, k -> {
         var element = new Element<>(k, loader, (l) -> CompletableFuture.supplyAsync(l, pool), unowned);

diff --git a/lib/src/main/java/eu/aylett/arc/internal/Element.java b/lib/src/main/java/eu/aylett/arc/internal/Element.java
@@ -103,26 +103,27 @@
     }
 
     var currentValue = this.value;
-    if (currentValue != null) {
-      if (currentValue.isDone()) {
-        var v = currentValue.join();
-        var currentWeakValue = this.weakValue;
-        if (currentWeakValue == null || !currentWeakValue.refersTo(v)) {
-          this.weakValue = new WeakReference<>(v);
+    if (currentValue == null || currentValue.isCompletedExceptionally()) {
+      var currentWeakValue = this.weakValue;
+      if (currentWeakValue != null) {
+        var v = currentWeakValue.get();
+        if (v != null) {
+          return (this.value = CompletableFuture.completedFuture(v)).copy();
+        } else {
+          this.weakValue = null;
         }
       }
-      return currentValue.copy();
+      return load().copy();
     }
-    var currentWeakValue = this.weakValue;
-    if (currentWeakValue != null) {
-      var v = currentWeakValue.get();
-      if (v != null) {
-        return (this.value = CompletableFuture.completedFuture(v));
-      } else {
-        this.weakValue = null;
+
+    if (currentValue.isDone()) {
+      var v = currentValue.join();
+      var currentWeakValue = this.weakValue;
+      if (currentWeakValue == null || !currentWeakValue.refersTo(v)) {
+        this.weakValue = new WeakReference<>(v);
       }
     }
-    return load().copy();
+    return currentValue.copy();
   }
 
   @Holding("this.lock")

diff --git a/lib/src/main/java/eu/aylett/arc/internal/Invariants.java b/lib/src/main/java/eu/aylett/arc/internal/Invariants.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 Andrew Aylett
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package eu.aylett.arc.internal;
+
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.Nullable;
+
+public final class Invariants {
+  @Contract(value = "null -> fail; !null -> param1", pure = true)
+  public static <T> T checkNotNull(@Nullable T reference) {
+    return checkNotNull(reference, "Invariant failed: value is null");
+  }
+
+  @Contract(value = "null, _ -> fail; !null, _ -> param1", pure = true)
+  public static <T> T checkNotNull(@Nullable T reference, String message) {
+    if (reference == null) {
+      throw new NullPointerException(message);
+    }
+    return reference;
+  }
+}
diff --git a/lib/src/main/java/module-info.java b/lib/src/main/java/module-info.java
@@ -18,6 +18,7 @@
   requires org.jspecify;
   requires org.checkerframework.checker.qual;
   requires com.github.spotbugs.annotations;
+  requires org.jetbrains.annotations;
 
   exports eu.aylett.arc;
 }
diff --git a/lib/src/test/java/eu/aylett/arc/ArcTest.java b/lib/src/test/java/eu/aylett/arc/ArcTest.java
@@ -22,6 +22,7 @@
 import org.checkerframework.checker.nullness.qual.PolyNull;
 import org.hamcrest.Matcher;
 import org.hamcrest.MatcherAssert;
+import org.hamcrest.Matchers;
 import org.junit.jupiter.api.Test;
 
 import java.time.Duration;
@@ -32,26 +33,31 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Random;
+import java.util.concurrent.CompletionException;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentLinkedDeque;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ForkJoinPool;
 import java.util.concurrent.ForkJoinTask;
 import java.util.concurrent.Semaphore;
 import java.util.concurrent.TimeoutException;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
 import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.hamcrest.Matchers.greaterThan;
 import static org.hamcrest.Matchers.hasItems;
+import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.lessThan;
+import static org.junit.jupiter.api.Assertions.assertThrowsExactly;
 
 import static java.util.Collections.synchronizedList;
 import static java.util.concurrent.TimeUnit.SECONDS;
 
-@SuppressWarnings({"argument", "type.argument", "method.guarantee.violated"})
+@SuppressWarnings({"argument", "type.argument", "method.guarantee.violated", "type.arguments.not.inferred", "argument",
+    "methodref.receiver", "dereference.of.nullable"})
 class ArcTest {
   public static <T> org.hamcrest.Matcher<@GuardedBy @PolyNull @Initialized T> equalTo(@GuardedBy @PolyNull T operand) {
     return org.hamcrest.core.IsEqual.equalTo(operand);
@@ -80,6 +86,7 @@ void testEviction() {
 
     assertThat(arc.get(1), equalTo("1"));
     assertThat(arc.get(2), equalTo("2"));
+    arc.checkSafety();
     arc.weakExpire();
     assertThat(arc.get(2), equalTo("2"));
     assertThat(arc.get(1), equalTo("1")); // This should reload "1" as it was evicted
@@ -269,7 +276,7 @@ record = recordedValues.stream().collect(Collectors.groupingBy((v) -> v, Collect
           .forEach(adjacentPair -> {
             var start = adjacentPair.getFirst();
             var end = adjacentPair.getLast();
-            assertThat(end.toEpochMilli(), lessThan(start.plusSeconds(35).toEpochMilli()));
+            assertThat(end.toEpochMilli(), lessThan(start.plusSeconds(55).toEpochMilli()));
             assertThat(end.toEpochMilli(), greaterThan(start.plusSeconds(29).toEpochMilli()));
           });
     }
@@ -296,4 +303,133 @@ public Instant instant() {
       return Instant.ofEpochMilli(value.get() * 100);
     }
   }
+
+  @Test
+  void testNullKeyHandling() {
+    var arc = new Arc<@NonNull Integer, String>(10, Object::toString, ForkJoinPool.commonPool());
+    @SuppressWarnings("DataFlowIssue")
+    var e = assertThrowsExactly(NullPointerException.class, () -> arc.get(null));
+    assertThat(e.getMessage(), equalTo("key cannot be null"));
+  }
+
+  @Test
+  void testLargeCapacity() {
+    var arc = new Arc<Integer, String>(100_000, Object::toString, ForkJoinPool.commonPool());
+    for (var i = 0; i < 100_000; i++) {
+      assertThat(arc.get(i), equalTo(String.valueOf(i)));
+    }
+  }
+
+  @Test
+  void testWeakExpireWithNoGC() {
+    var arc = new Arc<Integer, String>(10, Object::toString, ForkJoinPool.commonPool());
+    arc.get(1);
+    arc.get(2);
+    arc.weakExpire();
+    assertThat(arc.get(1), equalTo("1"));
+    assertThat(arc.get(2), equalTo("2"));
+  }
+
+  @Test
+  void testWeakExpireWithGC() {
+    var arc = new Arc<Integer, String>(10, Object::toString, ForkJoinPool.commonPool());
+    arc.get(1);
+    arc.get(2);
+    System.gc(); // Suggest garbage collection
+    arc.weakExpire();
+    assertThat(arc.get(1), equalTo("1")); // Should reload
+    assertThat(arc.get(2), equalTo("2")); // Should reload
+  }
+
+  @Test
+  void testLoaderExceptionHandling() {
+    var loaderFailed = new UnsupportedOperationException("Loader failed");
+
+    var arc = new Arc<Integer, String>(10, i -> {
+      if (i == 1) {
+        throw loaderFailed;
+      }
+      return i.toString();
+    }, ForkJoinPool.commonPool());
+
+    var ex = assertThrowsExactly(CompletionException.class, () -> arc.get(1));
+    assertThat(ex.getCause(), is(loaderFailed));
+
+    assertThat(arc.get(2), equalTo("2"));
+  }
+
+  @Test
+  void testLoaderRetriesAfterException() {
+    var shouldThrow = new AtomicBoolean(true);
+
+    var arc = new Arc<Integer, String>(10, i -> {
+      if (i == 1 && shouldThrow.getAndSet(false)) {
+        throw new UnsupportedOperationException("Loader failed");
+      }
+      return i.toString();
+    }, ForkJoinPool.commonPool());
+
+    var ex = assertThrowsExactly(CompletionException.class, () -> arc.get(1));
+    var cause = ex.getCause();
+    assertThat(cause.getMessage(), Matchers.equalTo("Loader failed"));
+
+    assertThat(arc.get(2), equalTo("2"));
+    assertThat(arc.get(1), equalTo("1"));
+  }
+
+  @Test
+  void testConcurrentAccessWithSameKey() throws InterruptedException {
+    var pool = ForkJoinPool.commonPool();
+    var arc = new Arc<Integer, String>(10, i -> {
+      try {
+        Thread.sleep(100); // Simulate delay in loading
+      } catch (InterruptedException e) {
+        throw new RuntimeException(e);
+      }
+      return i.toString();
+    }, pool);
+
+    var tasks = new ArrayList<ForkJoinTask<String>>();
+    for (var i = 0; i < 10; i++) {
+      tasks.add(pool.submit(() -> arc.get(1)));
+    }
+
+    tasks.forEach(ForkJoinTask::join);
+    assertThat(arc.get(1), equalTo("1"));
+  }
+
+  @Test
+  void testEvictionWithHighTurnover() {
+    var arc = new Arc<Integer, String>(5, Object::toString, ForkJoinPool.commonPool());
+    for (var i = 0; i < 20; i++) {
+      arc.get(i);
+    }
+    arc.weakExpire();
+    assertThat(arc.get(19), equalTo("19"));
+    assertThat(arc.get(0), equalTo("0")); // Should reload
+  }
+
+  @Test
+  void testCustomForkJoinPool() {
+    var customPool = new ForkJoinPool(2);
+    var arc = new Arc<Integer, String>(10, Object::toString, customPool);
+
+    var tasks = new ArrayList<ForkJoinTask<String>>();
+    for (var i = 0; i < 10; i++) {
+      var finalI = i;
+      tasks.add(customPool.submit(() -> arc.get(finalI)));
+    }
+
+    tasks.forEach(ForkJoinTask::join);
+    for (var i = 0; i < 10; i++) {
+      assertThat(arc.get(i), equalTo(String.valueOf(i)));
+    }
+  }
+
+  @Test
+  void testLoaderWithComplexValues() {
+    var arc = new Arc<Integer, List<Integer>>(10, i -> List.of(i, i * 2, i * 3), ForkJoinPool.commonPool());
+    assertThat(arc.get(2), equalTo(List.of(2, 4, 6)));
+    assertThat(arc.get(3), equalTo(List.of(3, 6, 9)));
+  }
 }
diff --git a/lib/src/test/resources/junit-platform.properties b/lib/src/test/resources/junit-platform.properties
@@ -0,0 +1,2 @@
+junit.jupiter.execution.parallel.enabled = true
+junit.jupiter.execution.parallel.mode.default = concurrent
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		junit.jupiter.execution.parallel.enabled = true
		junit.jupiter.execution.parallel.mode.default = concurrent