OPENNLP-1883: Add CachingStemmer: per-thread LRU memoization of word-to-stem mappings

Natural text is Zipf-distributed, so the same words are stemmed
constantly. CachingStemmer wraps a StemmerFactory with a bounded
per-thread LRU (default 1024 entries) following the same
OwnerOrPerThreadState pattern as the *ME components: no cross-thread
sharing, thread-safe regardless of the delegate. On the JMH zipf
workload the cache is a ~34x throughput multiplier; on a cache-hostile
uniform workload over 8x the cache capacity it still breaks even.
Results and a corrected JMH invocation are documented in BENCHMARKS.md.

Author: krickert

opennlp-core/opennlp-runtime/BENCHMARKS.md

@@ -14,6 +14,7 @@ variance reporting.
 | `SentenceDetectorMEBenchmark` | SentenceDetectorME | 3 approaches |
 | `POSTaggerMEBenchmark` | POSTaggerME | 3 approaches x 2 cache configs |
 | `SnowballStemmerBenchmark` | SnowballStemmer | 3 approaches (incl. pre-patch baseline) |
+| `CachingStemmerBenchmark` | CachingStemmer | cached vs uncached x 2 workloads |
 
 ### Approaches measured
 
@@ -31,17 +32,19 @@ mvn test-compile -Pjmh \
     -pl opennlp-core/opennlp-runtime -am \
     -Dforbiddenapis.skip=true -Dcheckstyle.skip=true
 
+# Materialize the test classpath once (JMH's forked JVMs inherit
+# java.class.path, which mvn exec:java does not populate — running
+# through exec:java fails with ClassNotFoundException: ForkedMain)
+mvn dependency:build-classpath -pl opennlp-core/opennlp-runtime \
+    -Pjmh -DincludeScope=test -Dmdep.outputFile=/tmp/cp.txt
+
+CP="opennlp-core/opennlp-runtime/target/classes:opennlp-core/opennlp-runtime/target/test-classes:$(cat /tmp/cp.txt)"
+
 # Run all ME benchmarks
-mvn exec:java -pl opennlp-core/opennlp-runtime \
-    -Pjmh -Dexec.classpathScope=test \
-    -Dexec.mainClass=org.openjdk.jmh.Main \
-    -Dexec.args="opennlp.tools.*.ME*"
+java -cp "$CP" org.openjdk.jmh.Main 'opennlp.tools.*.ME*'
 
 # Run POSTagger only (includes cacheSize param)
-mvn exec:java -pl opennlp-core/opennlp-runtime \
-    -Pjmh -Dexec.classpathScope=test \
-    -Dexec.mainClass=org.openjdk.jmh.Main \
-    -Dexec.args="POSTaggerMEBenchmark"
+java -cp "$CP" org.openjdk.jmh.Main POSTaggerMEBenchmark
 ```
 
 ### Regression testing (stock vs patched)
@@ -80,6 +83,30 @@ memory-level parallelism. Real pipelines stem as one stage among many,
 so the saturated-microbenchmark gap is an upper bound, and the legacy
 strategy was not shareable across threads in the first place.
 
+### CachingStemmer results (same environment)
+
+`CachingStemmerBenchmark` compares a `CachingStemmer` (per-thread LRU,
+default 1024 entries, wrapping the English Snowball stemmer) against
+the uncached shared stemmer. One op = 16 tokens from a 64k-token
+stream. The `zipf` workload samples a 512-word vocabulary with 1/rank
+weights (real-text repetition; the cache holds the whole vocabulary);
+`diverse` samples an 8192-word vocabulary uniformly (8x cache
+capacity: mostly misses plus constant eviction).
+
+| Workload | Strategy | 8 threads | 32 threads |
+|----------|----------|----------:|-----------:|
+| `zipf` | `cachedShared` | 48.5M ± 0.7M ops/s | 95.4M ± 0.9M |
+| `zipf` | `uncachedShared` | 1.43M ± 0.13M | 2.75M ± 0.34M |
+| `diverse` | `cachedShared` | 1.81M ± 0.51M | 3.45M ± 0.18M |
+| `diverse` | `uncachedShared` | 1.08M ± 0.09M | 3.13M ± 0.12M |
+
+On the Zipf workload the cache is a ~34x throughput multiplier (raw
+stemming becomes a hash lookup for the dominant vocabulary). On the
+cache-hostile workload it still does not lose: the ~12% residual hit
+rate pays for the eviction overhead. The cache more than recovers the
+`OwnerOrPerThreadState` lookup cost observed in
+`SnowballStemmerBenchmark` at full saturation.
+
 ### POSTagger cache impact
 
 The `POSTaggerMEBenchmark` uses `@Param({"0", "3"})` for cache

opennlp-core/opennlp-runtime/src/jmh/java/opennlp/tools/stemmer/CachingStemmerBenchmark.java

@@ -0,0 +1,199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 opennlp.tools.stemmer;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Random;
+import java.util.concurrent.TimeUnit;
+
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Fork;
+import org.openjdk.jmh.annotations.Level;
+import org.openjdk.jmh.annotations.Measurement;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Param;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.Threads;
+import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.infra.Blackhole;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
+
+import opennlp.tools.stemmer.snowball.SnowballStemmer;
+import opennlp.tools.stemmer.snowball.SnowballStemmerFactory;
+
+/**
+ * JMH benchmark for {@link CachingStemmer} against an uncached shared {@link SnowballStemmer}.
+ *
+ * <p>Two workloads drive both strategies:</p>
+ * <ul>
+ *   <li>{@code zipf} — a 64k-token stream sampled with 1/rank weights from a 512-word
+ *       vocabulary. This models real text, where a small vocabulary dominates; the default
+ *       1024-entry cache holds the whole vocabulary.</li>
+ *   <li>{@code diverse} — a 64k-token stream sampled uniformly from an 8192-word vocabulary,
+ *       8x the cache capacity. This is the cache-hostile case: mostly misses plus constant
+ *       eviction, so it bounds the overhead the cache can add.</li>
+ * </ul>
+ *
+ * <p>One op stems 16 consecutive tokens from the stream; each benchmark thread walks the stream
+ * from its own cursor.</p>
+ */
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.SECONDS)
+@Warmup(iterations = 5, time = 2)
+@Measurement(iterations = 10, time = 2)
+@Fork(2)
+public class CachingStemmerBenchmark {
+
+  private static final int STREAM_LENGTH = 65536;
+  private static final int WORDS_PER_OP = 16;
+
+  private static final String[] ROOTS = {
+      "run", "walk", "talk", "develop", "nation", "connect", "form", "create",
+      "act", "direct", "govern", "manage", "operate", "organize", "present", "relate",
+      "report", "state", "structure", "test", "train", "transform", "translate", "value",
+      "view", "wonder", "yield", "zone", "note", "mark", "place", "point"
+  };
+  private static final String[] PREFIXES = {
+      "", "re", "un", "over", "under", "out", "pre", "post",
+      "non", "anti", "de", "dis", "mis", "sub", "super", "inter"
+  };
+  private static final String[] SUFFIXES = {
+      "", "s", "ed", "ing", "er", "ers", "ation", "ations",
+      "ly", "ness", "ment", "ments", "ize", "ized", "izing", "al"
+  };
+
+  @State(Scope.Benchmark)
+  public static class WorkloadState {
+
+    @Param({"zipf", "diverse"})
+    String workload;
+
+    String[] stream;
+
+    @Setup(Level.Trial)
+    public void build() {
+      Random random = new Random(42);
+      List<String> vocabulary = new ArrayList<>();
+      if ("zipf".equals(workload)) {
+        // 32 roots x 16 suffixes = 512 unique words, sampled with 1/rank weights.
+        for (String root : ROOTS) {
+          for (String suffix : SUFFIXES) {
+            vocabulary.add(root + suffix);
+          }
+        }
+        double[] cumulative = new double[vocabulary.size()];
+        double sum = 0;
+        for (int rank = 0; rank < vocabulary.size(); rank++) {
+          sum += 1.0 / (rank + 1);
+          cumulative[rank] = sum;
+        }
+        stream = new String[STREAM_LENGTH];
+        for (int i = 0; i < STREAM_LENGTH; i++) {
+          double r = random.nextDouble() * sum;
+          int idx = 0;
+          while (cumulative[idx] < r) {
+            idx++;
+          }
+          stream[i] = vocabulary.get(idx);
+        }
+      } else {
+        // 16 prefixes x 32 roots x 16 suffixes = 8192 unique words, sampled uniformly.
+        for (String prefix : PREFIXES) {
+          for (String root : ROOTS) {
+            for (String suffix : SUFFIXES) {
+              vocabulary.add(prefix + root + suffix);
+            }
+          }
+        }
+        stream = new String[STREAM_LENGTH];
+        for (int i = 0; i < STREAM_LENGTH; i++) {
+          stream[i] = vocabulary.get(random.nextInt(vocabulary.size()));
+        }
+      }
+    }
+  }
+
+  @State(Scope.Benchmark)
+  public static class UncachedState {
+    Stemmer stemmer;
+
+    @Setup(Level.Trial)
+    public void create() {
+      stemmer = new SnowballStemmer(SnowballStemmer.ALGORITHM.ENGLISH);
+    }
+  }
+
+  @State(Scope.Benchmark)
+  public static class CachedState {
+    Stemmer stemmer;
+
+    @Setup(Level.Trial)
+    public void create() {
+      stemmer = new CachingStemmer(
+          new SnowballStemmerFactory(SnowballStemmer.ALGORITHM.ENGLISH));
+    }
+  }
+
+  @State(Scope.Thread)
+  public static class Cursor {
+    int position;
+
+    @Setup(Level.Trial)
+    public void randomize() {
+      position = new Random().nextInt(STREAM_LENGTH);
+    }
+  }
+
+  @Benchmark
+  @Threads(Threads.MAX)
+  public void uncachedShared(WorkloadState w, UncachedState st, Cursor cursor, Blackhole bh) {
+    for (int i = 0; i < WORDS_PER_OP; i++) {
+      bh.consume(st.stemmer.stem(w.stream[cursor.position++ & (STREAM_LENGTH - 1)]));
+    }
+  }
+
+  @Benchmark
+  @Threads(Threads.MAX)
+  public void cachedShared(WorkloadState w, CachedState st, Cursor cursor, Blackhole bh) {
+    for (int i = 0; i < WORDS_PER_OP; i++) {
+      bh.consume(st.stemmer.stem(w.stream[cursor.position++ & (STREAM_LENGTH - 1)]));
+    }
+  }
+
+  /**
+   * Quick local iteration only: {@code forks(0)} disables JVM fork isolation
+   * (unlike {@code mvn} with the {@code jmh} profile).
+   * Use the Maven-invoked configuration for publishable numbers.
+   */
+  public static void main(String[] args) throws Exception {
+    Options opt = new OptionsBuilder()
+        .include(CachingStemmerBenchmark.class.getSimpleName())
+        .forks(0)
+        .warmupIterations(3)
+        .measurementIterations(5)
+        .build();
+    new Runner(opt).run();
+  }
+}

opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/stemmer/CachingStemmer.java

@@ -0,0 +1,119 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 opennlp.tools.stemmer;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.util.OwnerOrPerThreadState;
+
+/**
+ * A {@link Stemmer} that memoizes word-to-stem mappings in a bounded per-thread LRU cache.
+ *
+ * <p>Natural language is Zipf-distributed: a small vocabulary accounts for most tokens, so the
+ * same words are stemmed over and over. Wrapping a stemmer in a {@code CachingStemmer} turns
+ * those repeats into a hash lookup instead of a full stemming pass.</p>
+ *
+ * <p>Each thread gets its own delegate stemmer (minted from the supplied {@link StemmerFactory})
+ * and its own cache, following the {@link OwnerOrPerThreadState} pattern of the thread-safe
+ * {@code *ME} components. There is no cross-thread sharing at all, so instances are safe to share
+ * regardless of whether the factory's stemmers are. Memory is bounded by
+ * {@code capacity * averageWordLength} characters per thread that stems.</p>
+ *
+ * <p>{@link #stemAll(CharSequence)} is forwarded to the delegate uncached, so multi-output
+ * engines keep their full result list.</p>
+ */
+@ThreadSafe
+public final class CachingStemmer implements Stemmer {
+
+  /**
+   * Covers the high-frequency vocabulary of most corpora while keeping the per-thread footprint
+   * small.
+   */
+  public static final int DEFAULT_CAPACITY = 1024;
+
+  private final OwnerOrPerThreadState<ThreadState> state;
+
+  /**
+   * Creates a caching stemmer with the {@linkplain #DEFAULT_CAPACITY default capacity}.
+   *
+   * @param factory The factory that mints one delegate per thread. Must not be {@code null}.
+   * @throws IllegalArgumentException if {@code factory} is {@code null}.
+   */
+  public CachingStemmer(StemmerFactory factory) {
+    this(factory, DEFAULT_CAPACITY);
+  }
+
+  /**
+   * Creates a caching stemmer.
+   *
+   * @param factory  The factory that mints one delegate per thread. Must not be {@code null}.
+   * @param capacity The maximum number of word-to-stem entries kept per thread; must be positive.
+   * @throws IllegalArgumentException if {@code factory} is {@code null} or {@code capacity} is
+   *     not positive.
+   */
+  public CachingStemmer(StemmerFactory factory, int capacity) {
+    if (factory == null) {
+      throw new IllegalArgumentException("factory must not be null");
+    }
+    if (capacity <= 0) {
+      throw new IllegalArgumentException("capacity must be positive, got " + capacity);
+    }
+    this.state = new OwnerOrPerThreadState<>(
+        () -> new ThreadState(factory.newStemmer(), capacity),
+        threadState -> threadState.cache.clear());
+  }
+
+  @Override
+  public CharSequence stem(CharSequence word) {
+    final ThreadState ts = state.get();
+    final String key = word.toString();
+    final String cached = ts.cache.get(key);
+    if (cached != null) {
+      return cached;
+    }
+    // toString() detaches the result from any buffer the delegate may reuse internally.
+    final String stemmed = ts.delegate.stem(key).toString();
+    ts.cache.put(key, stemmed);
+    return stemmed;
+  }
+
+  @Override
+  public List<CharSequence> stemAll(CharSequence word) {
+    return state.get().delegate.stemAll(word);
+  }
+
+  private static final class ThreadState {
+
+    private final Stemmer delegate;
+    private final LinkedHashMap<String, String> cache;
+
+    private ThreadState(Stemmer delegate, int capacity) {
+      this.delegate = delegate;
+      // Access-ordered so iteration order is least-recently-used first.
+      this.cache = new LinkedHashMap<>(Math.min(capacity, 4096), 0.75f, true) {
+        @Override
+        protected boolean removeEldestEntry(Map.Entry<String, String> eldest) {
+          return size() > capacity;
+        }
+      };
+    }
+  }
+}