add unit tests for multi-threaded execution

Author: luka-leko

README.md

@@ -46,7 +46,7 @@ implementation "com.dynatrace.vectorscan4j:vectorscan4j:0.1.0"
 
 ### Requirements
 
-- **Java 25+** (uses the [Foreign Function & Memory API](https://docs.oracle.com/en/java/javase/25/core/foreign-function-and-memory-api.html))
+- **Java 22+** (uses the [Foreign Function & Memory API](https://docs.oracle.com/en/java/javase/25/core/foreign-function-and-memory-api.html))
 - **Linux** (x86-64 or aarch64) — native vectorscan binaries are bundled in the JAR
 
 ## Usage
@@ -138,7 +138,7 @@ vectorscan4j provides utility methods for serializing and deserializing a Databa
             // ... save dbBytes to file, or send over network ...
 
 
-            // ... after loading dbBytes from a file ...
+            // load dbBytes from a file, then deserialize
             Database roundTripDb = Database.deserialize(dbBytes);
             roundTripDb.close();
         }
@@ -147,11 +147,11 @@ vectorscan4j provides utility methods for serializing and deserializing a Databa
 
 ## Incorrect Usage Patterns
 
-There is a number of things to watch out for in terms of how to use the wrapper which can lead to memory leaks, undefined behavior, or break the JVM.
+There is a small number of niche things to watch out for in terms of how to use the wrapper which can lead to undefined behavior, or break the JVM.
 
 ### 1. Not closing Database / Scanner objects
 
-Database- and Scanner objects both hold native memory. Calling close() on those objects will clean the native memory 
+Database- and Scanner objects both hold native memory, i.e. memory that is not managed by the JVM Runtime. Calling close() on those objects will clean the native memory 
 that they are holding. This memory will *also* be freed if one doesn't call the close() explicitly. However, in 
 that case it will only happen when the Database- or Scanner object gets garbage collected (which might be far in
 the future).
@@ -165,9 +165,8 @@ the future).
         // -> Its native memory gets freed, but not immediately.
     }
 ```
-This might still be a problem, as the garbage collector might not get called for a long time (because the bulk of the 
-data was lying off-heap, so the JVM doesn't see any memory issues).
-Thus, the easiest and safest usage pattern to ensure that memory doesn't accumulate is through a try-with-resources-block:
+For more optimal memory usage, either manually close Database and/or Scanner objects by calling the close() method,
+ or initialize them with a try-with-resources-block:
 ``` java
     // This function is safe to call
     void createDbSafe() {
@@ -223,8 +222,8 @@ This is due to how the Foreign Function & Memory API handles exceptions thrown d
 
 ### 4. Using the same Scanner concurrently in multiple threads
 
-A Scanner object maintains an internal scratch space, which is not safe to use in multiple threads. 
-Using the same Scanner concurrently leads to undefined behavior.
+A Scanner object maintains an internal scratch space, which is not safe to use from multiple threads. 
+Using the same Scanner from multiple threads will throw a VectorscanException.
 
 ## Limitations
 

src/main/java/com/dynatrace/vectorscan4j/Scanner.java

@@ -39,7 +39,7 @@ abstract class Scanner implements AutoCloseable {
     protected final MemorySegment scratch;
     private final CallHandlerOnMatch callHandler = new CallHandlerOnMatch();
     protected MemorySegment funcPtr = VectorscanMatchEventHandler.allocate(callHandler, arena);
-    ;
+
     protected final CleanupState cleanupState;
     private final Cleaner.Cleanable cleanable;
 
@@ -89,8 +89,6 @@ protected void setHandler(OnMatchEventHandler handler) {
     }
 
     protected Scanner(Database database) {
-        CallHandlerOnMatch callHandler = new CallHandlerOnMatch();
-
         this.database = database;
 
         // allocate scratch space

src/test/java/com/dynatrace/vectorscan4j/BlockScannerTests.java

@@ -30,9 +30,7 @@
 import java.nio.ByteBuffer;
 import java.nio.charset.StandardCharsets;
 import java.util.*;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
-import java.util.concurrent.Future;
+import java.util.concurrent.*;
 import org.junit.jupiter.api.Test;
 
 public class BlockScannerTests {
@@ -58,8 +56,7 @@ void defaultScan() {
             String input = "I am searching for pattern1, has anyone seen pattern1?";
             List<Integer> matchedIds = new ArrayList<>();
 
-            scanner.scan(input, (id, from, to, _) -> {
-                IO.println(String.format("Match pattern with id %d, from %d to %d", id, from, to));
+            scanner.scan(input, (id, _, _, _) -> {
                 matchedIds.add(id);
                 return true;
             });
@@ -262,12 +259,8 @@ void countLiteralPatternOccurrences() {
                 return true;
             });
         }
-        for (int i = 0; i < exprs.size(); i++) {
-            IO.println(String.format("%s -> matched %d times.", exprs.get(i).pattern(), countsById[i]));
-        }
-        // foo -> matched 3 times.
-        // bar -> matched 2 times.
-        // qux -> matched 0 times.
+        int[] a = {3, 2, 0};
+        assertArrayEquals(a, countsById);
     }
 
     @Test
@@ -443,4 +436,31 @@ void scannerKeepsDatabaseAlive() throws InterruptedException {
         assertNull(dbRef.get(), "Database did not get freed.");
         assertNull(scannerRef.get(), "Scanner did not get freed.");
     }
+
+    @Test
+    void usingScannerFromMultipleThreadsThrowsVectorscanException() throws Exception {
+        Database db = new Database(expressions, BLOCK_MODE);
+        BlockScanner scanner = new BlockScanner(db);
+
+        ExecutorService service = Executors.newFixedThreadPool(2);
+        try {
+            CountDownLatch stop = new CountDownLatch(1);
+            CountDownLatch scannerInUse = new CountDownLatch(1);
+            OnMatchEventHandler handler = (_, _, _, _) -> {
+                try {
+                    scannerInUse.countDown();
+                    stop.await();
+                } catch (InterruptedException _) {
+                }
+                return true;
+            };
+            service.submit(() -> scanner.scan("pattern1 ", handler));
+            scannerInUse.await(); // wait until the scanner has found a match, meaning it is currently in use.
+            assertThrows(VectorscanException.class, () -> scanner.scan("pattern1 ", doNothing));
+            stop.countDown();
+        } finally {
+            service.shutdown();
+            assertTrue(service.awaitTermination(1L, TimeUnit.SECONDS));
+        }
+    }
 }

src/test/java/com/dynatrace/vectorscan4j/DatabaseTests.java

@@ -30,6 +30,8 @@
 import java.util.Arrays;
 import java.util.EnumSet;
 import java.util.List;
+import java.util.concurrent.*;
+import java.util.stream.Stream;
 import org.junit.jupiter.api.Test;
 
 public class DatabaseTests {
@@ -87,9 +89,7 @@ void modifyExpressions() {
                 new Expression("pat1", EnumSet.noneOf(Flags.class)),
                 new Expression("pat2", EnumSet.noneOf(Flags.class)));
         try (Database database = new Database(expr, ExecutionMode.BLOCK_MODE)) {
-            IO.println(database.getExpression(0));
             expr.set(0, new Expression("pat3", EnumSet.noneOf(Flags.class)));
-            IO.println(database.getExpression(0));
         }
     }
 
@@ -267,6 +267,8 @@ void expressionsAreDefensivelyCopied() {
         List<Expression> mutable = new ArrayList<>(List.of(new Expression("pat1"), new Expression("pat2")));
 
         try (Database db = new Database(mutable, BLOCK_MODE)) {
+            BlockScanner scannerBefore = new BlockScanner(db);
+
             // Mutate the original list after database creation
             mutable.set(0, new Expression("REPLACED"));
             mutable.add(new Expression("pat3"));
@@ -275,6 +277,29 @@ void expressionsAreDefensivelyCopied() {
             assertEquals(2, db.getNumExpressions());
             assertEquals("pat1", db.getExpression(0).pattern());
             assertEquals("pat2", db.getExpression(1).pattern());
+
+            // Scanners created before and after mutations should find the same patterns
+            BlockScanner scannerAfter = new BlockScanner(db);
+            String input = "We have pat1 and pat2 in this string";
+
+            List<Integer> beforeMatches = new ArrayList<>();
+            scannerBefore.scan(input, (id, _, _, _) -> {
+                beforeMatches.add(id);
+                return true;
+            });
+
+            List<Integer> afterMatches = new ArrayList<>();
+            scannerAfter.scan(input, (id, _, _, _) -> {
+                afterMatches.add(id);
+                return true;
+            });
+
+            // Both scanners should find pat1 (id=0) and pat2 (id=1) once
+            assertEquals(List.of(0, 1), beforeMatches);
+            assertEquals(List.of(0, 1), afterMatches);
+
+            scannerBefore.close();
+            scannerAfter.close();
         }
     }
 
@@ -310,4 +335,54 @@ void notClosingStillFreesMemory() throws InterruptedException {
         Thread.sleep(100);
         assertNull(dbRef.get(), "Database did not get freed.");
     }
+
+    @Test
+    void useDatabaseFromMultipleThreads() throws Exception {
+        List<Expression> exprs = List.of(new Expression("pat1"), new Expression("pat2"));
+        String input = "pat1 xx pat1 yy pat1";
+
+        int nThreads = 256;
+        Database db = new Database(exprs, BLOCK_MODE);
+        List<BlockScanner> scanners =
+                Stream.generate(() -> new BlockScanner(db)).limit(nThreads).toList();
+        CyclicBarrier allMatched = new CyclicBarrier(nThreads);
+        ExecutorService pool = Executors.newFixedThreadPool(nThreads);
+        try {
+            List<Future<List<Integer>>> futures = new ArrayList<>();
+            for (int i = 0; i < nThreads; i++) {
+                int finalI = i;
+                Future<List<Integer>> f = pool.submit(() -> {
+                    List<Integer> matchedIds = new ArrayList<>();
+                    scanners.get(finalI).scan(input, (id, _, _, _) -> {
+                        try {
+                            allMatched.await(); // all scanners wait for each other to find a match until they continue.
+                            matchedIds.add(id);
+                        } catch (Exception _) {
+                        }
+                        return true;
+                    });
+                    return matchedIds;
+                });
+                futures.add(f);
+            }
+
+            List<List<Integer>> allMatches = new ArrayList<>();
+            for (Future<List<Integer>> f : futures) {
+                allMatches.add(f.get());
+            }
+
+            // Every scanner scanned the same input, so each should have found the same match IDs.
+            List<Integer> expected = List.of(0, 0, 0);
+            for (List<Integer> matches : allMatches) {
+                assertEquals(expected, matches);
+            }
+        } finally {
+            pool.shutdownNow();
+        }
+
+        db.close();
+        for (var scanner : scanners) {
+            scanner.close();
+        }
+    }
 }