Add Maybe-returning tryGetOrCreateAsMaybe to Hashtable and FlatHashtable

Additive siblings to tryGetOrCreate on Hashtable.D1/D2 and
FlatHashtable.D1/D2, wrapping the existing @Nullable-returning method in
a Maybe rather than changing its signature. Each delegates to the
existing tryGetOrCreate as its sole Maybe#of call site, keeping the
allocation-free shape Maybe's class javadoc requires.

Validates Maybe against a real caller: the client-side-stats PR
(#12312) stacked on top of this one converts CardinalityLimitReporter
to tryGetOrCreateAsMaybe(...).update(...).

Author: dougqh

internal-api/src/main/java/datadog/trace/util/FlatHashtable.java

@@ -285,6 +285,17 @@ public TEntry tryGetOrCreate(@Nullable K key, @Nonnull CreateStrategy<TEntry, K>
       return created;
     }
 
+    /**
+     * {@link Maybe}-wrapped form of {@link #tryGetOrCreate}, delegating to it as the sole {@link
+     * Maybe#of} call site -- see {@link Maybe}'s class javadoc for why that shape is required to
+     * stay allocation-free. A growable table's {@link Maybe} is always present.
+     */
+    @Nonnull
+    public Maybe<TEntry> tryGetOrCreateAsMaybe(
+        @Nullable K key, @Nonnull CreateStrategy<TEntry, K> createStrat) {
+      return Maybe.of(tryGetOrCreate(key, createStrat));
+    }
+
     /**
      * Unconditionally adds {@code entry} ({@code true}), or {@code false} if a fixed table is full.
      * Comparison-free and caller-responsible (same contract as {@link FlatHashtable#insert}): the
@@ -476,6 +487,18 @@ public TEntry tryGetOrCreate(
       return created;
     }
 
+    /**
+     * Two-key analogue of {@link D1#tryGetOrCreateAsMaybe}: {@link Maybe}-wrapped form of {@link
+     * #tryGetOrCreate}, delegating to it as the sole {@link Maybe#of} call site.
+     */
+    @Nonnull
+    public Maybe<TEntry> tryGetOrCreateAsMaybe(
+        @Nullable K1 key1,
+        @Nullable K2 key2,
+        @Nonnull CreateStrategy2<TEntry, K1, K2> createStrat) {
+      return Maybe.of(tryGetOrCreate(key1, key2, createStrat));
+    }
+
     /**
      * Unconditionally adds {@code entry} ({@code true}), or {@code false} if a fixed table is full.
      * Comparison-free and caller-responsible: the caller must ensure {@code (key1, key2)} is

internal-api/src/main/java/datadog/trace/util/Hashtable.java

@@ -339,6 +339,23 @@ public TEntry tryGetOrCreate(
       return newEntry;
     }
 
+    /**
+     * {@link Maybe}-wrapped form of {@link #tryGetOrCreate}, for callers that want to guard the
+     * refused-create case with {@link Maybe#update} rather than a manual null check:
+     *
+     * <pre>{@code
+     * table.tryGetOrCreateAsMaybe(key, Counter::new).update(n, ADD);
+     * }</pre>
+     *
+     * <p>Exactly one {@link Maybe#of} call site, fed by delegating to {@link #tryGetOrCreate} --
+     * see {@link Maybe}'s class javadoc for why that shape is required to stay allocation-free.
+     */
+    @Nonnull
+    public Maybe<TEntry> tryGetOrCreateAsMaybe(
+        @Nullable K key, @Nonnull Function<? super K, ? extends TEntry> creator) {
+      return Maybe.of(tryGetOrCreate(key, creator));
+    }
+
     /**
      * {@link #tryGetOrCreate} followed by {@code updater}, returning whether the update happened.
      *
@@ -653,6 +670,18 @@ public TEntry tryGetOrCreate(
       return newEntry;
     }
 
+    /**
+     * Two-key analogue of {@link D1#tryGetOrCreateAsMaybe}: {@link Maybe}-wrapped form of {@link
+     * #tryGetOrCreate}, delegating to it as the sole {@link Maybe#of} call site.
+     */
+    @Nonnull
+    public Maybe<TEntry> tryGetOrCreateAsMaybe(
+        @Nullable K1 key1,
+        @Nullable K2 key2,
+        @Nonnull BiFunction<? super K1, ? super K2, ? extends TEntry> creator) {
+      return Maybe.of(tryGetOrCreate(key1, key2, creator));
+    }
+
     /**
      * Two-key analogue of {@link D1#tryGetOrUpdate(Object, Function, Consumer)}: applies {@code
      * updater} to the entry for {@code (key1, key2)}, creating one if absent, and returns whether

internal-api/src/test/java/datadog/trace/util/FlatHashtableD1Test.java

@@ -257,6 +257,27 @@ void fixedGetOrCreateCapsWhenFull() {
     assertSame(a, table.tryGetOrCreate("a", k -> new StringIntEntry(k, 99)));
   }
 
+  @Test
+  void fixedGetOrCreateAsMaybeIsAbsentWhenFullButStillReturnsHits() {
+    FlatHashtable.D1<String, StringIntEntry> table = fixed(2);
+    table.tryGetOrCreate("a", k -> new StringIntEntry(k, 1));
+    table.tryGetOrCreate("b", k -> new StringIntEntry(k, 2));
+
+    assertFalse(table.tryGetOrCreateAsMaybe("c", k -> new StringIntEntry(k, 3)).isPresent());
+
+    Maybe<StringIntEntry> hit = table.tryGetOrCreateAsMaybe("a", k -> new StringIntEntry(k, 99));
+    assertEquals(1, hit.getOrNull().value, "existing entry is still returned even at capacity");
+  }
+
+  @Test
+  void growableGetOrCreateAsMaybeIsAlwaysPresent() {
+    FlatHashtable.D1<String, StringIntEntry> table = growable(1);
+    for (int i = 0; i < 50; i++) {
+      assertTrue(table.tryGetOrCreateAsMaybe("k" + i, k -> new StringIntEntry(k, 0)).isPresent());
+    }
+    assertEquals(50, table.size());
+  }
+
   @Test
   void fixedInsertReturnsFalseWhenFull() {
     FlatHashtable.D1<String, StringIntEntry> table = fixed(2);

internal-api/src/test/java/datadog/trace/util/FlatHashtableD2Test.java

@@ -226,6 +226,31 @@ void fixedGetOrCreateCapsWhenFull() {
     assertSame(a, table.tryGetOrCreate("a", 1, (k1, k2) -> new PairEntry(k1, k2, 99)));
   }
 
+  @Test
+  void fixedGetOrCreateAsMaybeIsAbsentWhenFullButStillReturnsHits() {
+    FlatHashtable.D2<String, Integer, PairEntry> table = fixed(2);
+    table.tryGetOrCreate("a", 1, (k1, k2) -> new PairEntry(k1, k2, 1));
+    table.tryGetOrCreate("b", 2, (k1, k2) -> new PairEntry(k1, k2, 2));
+
+    assertFalse(
+        table.tryGetOrCreateAsMaybe("c", 3, (k1, k2) -> new PairEntry(k1, k2, 3)).isPresent());
+
+    Maybe<PairEntry> hit =
+        table.tryGetOrCreateAsMaybe("a", 1, (k1, k2) -> new PairEntry(k1, k2, 99));
+    assertEquals(1, hit.getOrNull().value, "existing entry is still returned even at capacity");
+  }
+
+  @Test
+  void growableGetOrCreateAsMaybeIsAlwaysPresent() {
+    FlatHashtable.D2<String, Integer, PairEntry> table = growable(1);
+    for (int i = 0; i < 50; i++) {
+      Maybe<PairEntry> maybe =
+          table.tryGetOrCreateAsMaybe("k", i, (k1, k2) -> new PairEntry(k1, k2, k2));
+      assertTrue(maybe.isPresent());
+    }
+    assertEquals(50, table.size());
+  }
+
   @Test
   void fixedInsertReturnsFalseWhenFull() {
     FlatHashtable.D2<String, Integer, PairEntry> table = fixed(2);

internal-api/src/test/java/datadog/trace/util/HashtableD1Test.java

@@ -245,6 +245,42 @@ void getOrCreateNullKeyIsPermitted() {
     assertEquals(1, table.size());
   }
 
+  @Test
+  void getOrCreateAsMaybeOnMissBuildsEntryViaCreator() {
+    Hashtable.D1<String, StringIntEntry> table = Hashtable.D1.createCapped(StringIntEntry.class, 8);
+    Maybe<StringIntEntry> maybe =
+        table.tryGetOrCreateAsMaybe("foo", k -> new StringIntEntry(k, 42));
+    assertTrue(maybe.isPresent());
+    assertEquals(42, maybe.getOrNull().value);
+    assertSame(table.get("foo"), maybe.getOrNull());
+  }
+
+  @Test
+  void getOrCreateAsMaybeReturnsAbsentOnceAtCapacityButStillReturnsHits() {
+    Hashtable.D1<String, StringIntEntry> table = Hashtable.D1.createCapped(StringIntEntry.class, 2);
+    table.insert(new StringIntEntry("a", 1));
+    table.insert(new StringIntEntry("b", 2));
+
+    assertFalse(table.tryGetOrCreateAsMaybe("c", k -> new StringIntEntry(k, 3)).isPresent());
+    assertEquals(2, table.size());
+
+    Maybe<StringIntEntry> hit = table.tryGetOrCreateAsMaybe("a", k -> new StringIntEntry(k, 999));
+    assertEquals(1, hit.getOrNull().value, "existing entry is still returned even at capacity");
+  }
+
+  @Test
+  void getOrCreateAsMaybeUpdateAppliesOnlyWhenPresent() {
+    Hashtable.D1<String, StringIntEntry> table = Hashtable.D1.createCapped(StringIntEntry.class, 1);
+    table.insert(new StringIntEntry("a", 1));
+
+    ObjLongConsumer<StringIntEntry> add = (e, n) -> e.value += n;
+    table.tryGetOrCreateAsMaybe("a", k -> new StringIntEntry(k, 0)).update(5L, add);
+    assertEquals(6, table.get("a").value);
+
+    table.tryGetOrCreateAsMaybe("b", k -> new StringIntEntry(k, 0)).update(5L, add);
+    assertNull(table.get("b"), "refused create at capacity leaves nothing to update");
+  }
+
   @Test
   void insertReturnsFalseOnceAtCapacity() {
     Hashtable.D1<String, StringIntEntry> table = Hashtable.D1.createCapped(StringIntEntry.class, 2);

internal-api/src/test/java/datadog/trace/util/HashtableD2Test.java

@@ -206,6 +206,21 @@ void getOrCreateReturnsNullOnceAtCapacityButStillReturnsHits() {
     assertEquals(100, hit.value, "existing entry is still returned even at capacity");
   }
 
+  @Test
+  void getOrCreateAsMaybeReturnsAbsentOnceAtCapacityButStillReturnsHits() {
+    Hashtable.D2<String, Integer, PairEntry> table = Hashtable.D2.createCapped(PairEntry.class, 2);
+    table.insert(new PairEntry("a", 1, 100));
+    table.insert(new PairEntry("b", 2, 200));
+
+    assertFalse(
+        table.tryGetOrCreateAsMaybe("c", 3, (k1, k2) -> new PairEntry(k1, k2, 300)).isPresent());
+    assertEquals(2, table.size());
+
+    Maybe<PairEntry> hit =
+        table.tryGetOrCreateAsMaybe("a", 1, (k1, k2) -> new PairEntry(k1, k2, 999));
+    assertEquals(100, hit.getOrNull().value, "existing entry is still returned even at capacity");
+  }
+
   @Test
   void tryInsertOrReplaceStillReplacesAtCapacityButRefusesFreshInsert() {
     Hashtable.D2<String, Integer, PairEntry> table = Hashtable.D2.createCapped(PairEntry.class, 2);