Comment upon our choice for annotations for forEach*.

jspecify · Oct 7, 2024 · 5a220a3 · 5a220a3
1 parent c845d13
commit 5a220a3
Showing 1 changed file with 8 additions and 0 deletions.
diff --git a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
@@ -3742,6 +3742,11 @@ public void forEach(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: We could instead use `<U extends @Nullable Object>` along with `@NonNull U`.
+    // Advantages to our current approach include:
+    // - calls out the null support in an otherwise null-hostile class
+    // - is consistent with the declarations for `search` and `reduce`
+    // - saves the user from a decision: https://github.com/jspecify/jspecify/issues/525
     public <U> void forEach(long parallelismThreshold,
                             BiFunction<? super K, ? super V, ? extends @Nullable U> transformer,
                             Consumer<? super U> action) {
@@ -3909,6 +3914,7 @@ public void forEachKey(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachKey(long parallelismThreshold,
                                Function<? super K, ? extends @Nullable U> transformer,
                                Consumer<? super U> action) {
@@ -4096,6 +4102,7 @@ public void forEachValue(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachValue(long parallelismThreshold,
                                  Function<? super V, ? extends @Nullable U> transformer,
                                  Consumer<? super U> action) {
@@ -4280,6 +4287,7 @@ public void forEachEntry(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachEntry(long parallelismThreshold,
                                  Function<Map.Entry<K,V>, ? extends @Nullable U> transformer,
                                  Consumer<? super U> action) {