Light, fluffy, and always free - The AWS Local Emulator alternative
refactor(concurrency): add bounded work queues and versioned signals (#6547)
Andre Kurait615e12dcff05
diff --git a/docs/concurrency.md b/docs/concurrency.mdnew file mode 100644index 0000000000..a310043d8d--- /dev/null+++ b/docs/concurrency.md@@ -0,0 +1,45 @@+# Local concurrency primitives++These internal primitives coordinate work owned by one Floci process. They do not+store authoritative service state or replace resource ownership and readiness checks.++## Bounded keyed work++`KeyedWorkQueue<K>` treats a key as a request to read current authoritative state.+It runs at most the configured number of virtual-thread workers, retains at most+the configured number of distinct keys, and permits only one active worker per key.+Repeated notifications coalesce. A notification during a pass schedules another+pass; dirty keys return at the tail so one busy resource does not monopolize work.++Submission never runs the action on the caller's thread. A duplicate can be accepted+when the queue is full; a new key is rejected. Callers must retain authoritative+state and a fair periodic recovery path for rejected or externally missed changes.+Worker failures release admission and are logged; they do not cause immediate+error-retry loops. A snapshot exposes retained keys, active workers, completed+passes, coalescing, rejection and failure counts.++Close rejects new work, discards queued notifications and interrupts admitted work.+The owning service still implements its resource-drain and cancellation contract.+Callbacks must establish account/region context explicitly and validate resource+identity before committing effects. A completed Docker start or HTTP connection+is not proof of service readiness.++## Versioned state notifications++`VersionedSignal` closes the gap between reading state and waiting for a change:++1. Read the signal version.+2. Read the authoritative predicate under its normal ownership rules.+3. If the predicate is false, wait only while that version is unchanged.+4. Recheck the predicate after notification, timeout or a spurious wakeup.++Publish a signal after the state mutation succeeds. The signal monitor is short-lived;+never wait while holding the authoritative-state lock. Waiting uses a monotonic+deadline and propagates interruption. Resource closure must also signal waiters.+The signal does not own an executor or retain a list of listeners.++## Distributed ownership++These are local scheduling tools. Cross-process coordination would additionally+need explicit ownership, fencing, durable publication/replay, failure recovery and+idempotent effects. Adding an external watch alone does not supply those contracts.diff --git a/mkdocs.yml b/mkdocs.ymlindex 15607f3225..872dfd948c 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -233,4 +233,6 @@ nav:- Python: testcontainers/python.md- .NET: testcontainers/dotnet.md- Go: testcontainers/go.md- - Contributing: contributing.md+ - Development:+ - Contributing: contributing.md+ - Local concurrency primitives: concurrency.mddiff --git a/src/main/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueue.java b/src/main/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueue.javanew file mode 100644index 0000000000..ce19670736--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueue.java@@ -0,0 +1,138 @@+package io.github.hectorvent.floci.core.common.concurrent;++import org.jboss.logging.Logger;++import java.util.LinkedHashMap;+import java.util.Map;+import java.util.Objects;+import java.util.concurrent.ExecutorService;+import java.util.concurrent.Executors;+import java.util.concurrent.RejectedExecutionException;+import java.util.function.Consumer;++/**+ * Bounded, level-triggered work: a key means "read its current state", not an event to replay.+ * One worker owns a key at a time. A notification during that work guarantees another pass.+ * Callers retain a periodic repair path for notifications rejected at capacity.+ */+public final class KeyedWorkQueue<K> implements AutoCloseable {+ private static final Logger LOG = Logger.getLogger(KeyedWorkQueue.class);++ private final Map<K, Work> pending = new LinkedHashMap<>();+ private final ExecutorService workers;+ private final Consumer<K> action;+ private final int concurrency;+ private final int capacity;+ private int active;+ private long completed;+ private long coalesced;+ private long rejected;+ private long failures;+ private boolean closed;++ private static final class Work {+ boolean running;+ boolean dirty = true;+ }++ public record Snapshot(int keys, int active, long completed, long coalesced,+ long rejected, long failures, boolean closed) {}++ public KeyedWorkQueue(String name, int concurrency, int capacity, Consumer<K> action) {+ if (concurrency < 1 || capacity < concurrency) {+ throw new IllegalArgumentException("Capacity must be at least the positive concurrency");+ }+ this.concurrency = concurrency;+ this.capacity = capacity;+ this.action = Objects.requireNonNull(action);+ this.workers = Executors.newThreadPerTaskExecutor(Thread.ofVirtual().name(name + "-", 0).factory());+ }++ /**+ * Never runs work on the notifying thread. Duplicate notifications occupy no extra capacity.+ * False means closed or full; authoritative state must remain available to periodic repair.+ */+ public synchronized boolean submit(K key) {+ Objects.requireNonNull(key);+ if (closed) {+ return false;+ }+ Work work = pending.get(key);+ if (work != null) {+ work.dirty = true;+ coalesced++;+ return true;+ }+ if (pending.size() >= capacity) {+ rejected++;+ return false;+ }+ pending.put(key, new Work());+ dispatch();+ return true;+ }++ private void dispatch() {+ for (Map.Entry<K, Work> entry : pending.entrySet()) {+ if (active >= concurrency || closed) {+ return;+ }+ Work work = entry.getValue();+ if (work.running) {+ continue;+ }+ work.running = true;+ work.dirty = false;+ active++;+ K key = entry.getKey();+ try {+ workers.execute(() -> run(key, work));+ } catch (RejectedExecutionException failure) {+ active--;+ work.running = false;+ work.dirty = true;+ throw failure;+ }+ }+ }++ private void run(K key, Work work) {+ try {+ synchronized (this) {+ if (closed) {+ return;+ }+ }+ action.accept(key);+ } catch (RuntimeException failure) {+ synchronized (this) {+ failures++;+ }+ LOG.warnv(failure, "Background reconciliation failed for {0}; periodic repair can retry", key);+ } finally {+ synchronized (this) {+ active--;+ completed++;+ pending.remove(key);+ if (!closed && work.dirty) {+ // Reinsert at the tail so a hot key cannot starve other resources.+ work.running = false;+ pending.put(key, work);+ }+ dispatch();+ }+ }+ }++ public synchronized Snapshot snapshot() {+ return new Snapshot(pending.size(), active, completed, coalesced, rejected, failures, closed);+ }++ /** Discards queued notifications and interrupts admitted work; callers own resource draining. */+ @Override+ public synchronized void close() {+ closed = true;+ pending.clear();+ workers.shutdownNow();+ }+}diff --git a/src/main/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignal.java b/src/main/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignal.javanew file mode 100644index 0000000000..61364ac5d9--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignal.java@@ -0,0 +1,32 @@+package io.github.hectorvent.floci.core.common.concurrent;++import java.util.concurrent.TimeUnit;++/**+ * A notification that cannot be lost between reading authoritative state and parking.+ * Observe the version before reading state, then await a change only if the predicate is false.+ * Never hold an authoritative-state lock while awaiting this signal.+ */+public final class VersionedSignal {+ private long version;++ public synchronized long version() {+ return version;+ }++ public synchronized void signal() {+ version++;+ notifyAll();+ }++ /** Returns true on a version change, false on timeout. Interruption belongs to the caller. */+ public synchronized boolean awaitChange(long observed, long timeoutNanos) throws InterruptedException {+ long deadline = System.nanoTime() + timeoutNanos;+ long remaining = timeoutNanos;+ while (version == observed && remaining > 0) {+ TimeUnit.NANOSECONDS.timedWait(this, remaining);+ remaining = deadline - System.nanoTime();+ }+ return version != observed;+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueueTest.java b/src/test/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueueTest.javanew file mode 100644index 0000000000..269904e5fa--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/core/common/concurrent/KeyedWorkQueueTest.java@@ -0,0 +1,190 @@+package io.github.hectorvent.floci.core.common.concurrent;++import org.junit.jupiter.api.Test;++import java.time.Duration;+import java.util.ArrayList;+import java.util.List;+import java.util.concurrent.CopyOnWriteArrayList;+import java.util.concurrent.CountDownLatch;+import java.util.concurrent.ExecutorService;+import java.util.concurrent.Executors;+import java.util.concurrent.Future;+import java.util.concurrent.TimeUnit;+import java.util.concurrent.atomic.AtomicInteger;+import java.util.concurrent.atomic.AtomicIntegerArray;++import static org.awaitility.Awaitility.await;+import static org.junit.jupiter.api.Assertions.*;++class KeyedWorkQueueTest {+ @Test+ void concurrentProducersConvergeToEveryLatestValueWithoutOverlappingAKey() throws Exception {+ AtomicIntegerArray versions = new AtomicIntegerArray(32);+ AtomicIntegerArray observed = new AtomicIntegerArray(32);+ AtomicIntegerArray active = new AtomicIntegerArray(32);+ AtomicInteger overlaps = new AtomicInteger();+ try (KeyedWorkQueue<Integer> queue = new KeyedWorkQueue<>("stress-test", 4, 32, key -> {+ if (active.incrementAndGet(key) != 1) {+ overlaps.incrementAndGet();+ }+ observed.set(key, versions.get(key));+ active.decrementAndGet(key);+ })) {+ try (ExecutorService producers = Executors.newVirtualThreadPerTaskExecutor()) {+ List<Future<?>> submissions = new ArrayList<>();+ for (int producer = 0; producer < 8; producer++) {+ submissions.add(producers.submit(() -> {+ for (int i = 0; i < 2000; i++) {+ int key = i % 32;+ versions.incrementAndGet(key);+ queue.submit(key);+ }+ }));+ }+ for (Future<?> submission : submissions) {+ submission.get();+ }+ }+ await().atMost(Duration.ofSeconds(5)).until(() -> queue.snapshot().keys() == 0);+ assertEquals(0, overlaps.get());+ assertEquals(0, queue.snapshot().rejected());+ for (int key = 0; key < 32; key++) {+ assertEquals(versions.get(key), observed.get(key), "Lost update for key " + key);+ }+ }+ }++ @Test+ void notificationDuringWorkIsCoalescedWithoutLosingTheNextPass() throws Exception {+ CountDownLatch entered = new CountDownLatch(1);+ CountDownLatch release = new CountDownLatch(1);+ AtomicInteger runs = new AtomicInteger();+ try (KeyedWorkQueue<String> queue = new KeyedWorkQueue<>("wake-test", 2, 4, key -> {+ if (runs.incrementAndGet() == 1) {+ entered.countDown();+ awaitLatch(release);+ }+ })) {+ assertTrue(queue.submit("a"));+ assertTrue(entered.await(2, TimeUnit.SECONDS));+ for (int i = 0; i < 10_000; i++) {+ assertTrue(queue.submit("a"));+ }+ assertEquals(1, runs.get());+ assertEquals(1, queue.snapshot().keys());+ release.countDown();+ await().atMost(Duration.ofSeconds(2)).until(() -> queue.snapshot().keys() == 0);+ assertEquals(2, runs.get());+ assertEquals(10_000, queue.snapshot().coalesced());+ } finally {+ release.countDown();+ }+ }++ @Test+ void blockedKeyDoesNotBlockAnotherKeyAndCapacityIsBounded() throws Exception {+ CountDownLatch entered = new CountDownLatch(2);+ CountDownLatch release = new CountDownLatch(1);+ List<String> runs = new CopyOnWriteArrayList<>();+ try (KeyedWorkQueue<String> queue = new KeyedWorkQueue<>("bounded-test", 2, 3, key -> {+ runs.add(key);+ entered.countDown();+ awaitLatch(release);+ })) {+ assertTrue(queue.submit("a"));+ assertTrue(queue.submit("b"));+ assertTrue(entered.await(2, TimeUnit.SECONDS));+ assertTrue(queue.submit("c"));+ assertFalse(queue.submit("d"));+ assertEquals(2, queue.snapshot().active());+ assertEquals(3, queue.snapshot().keys());+ release.countDown();+ await().atMost(Duration.ofSeconds(2)).until(() -> queue.snapshot().keys() == 0);+ assertEquals(3, runs.size());+ // A later authoritative repair pass can retry the rejected key.+ assertTrue(queue.submit("d"));+ await().atMost(Duration.ofSeconds(2)).until(() -> runs.contains("d"));+ } finally {+ release.countDown();+ }+ }++ @Test+ void hotKeyYieldsToQueuedKeys() throws Exception {+ CountDownLatch entered = new CountDownLatch(1);+ CountDownLatch release = new CountDownLatch(1);+ List<String> runs = new CopyOnWriteArrayList<>();+ try (KeyedWorkQueue<String> queue = new KeyedWorkQueue<>("fair-test", 1, 3, key -> {+ runs.add(key);+ if (runs.size() == 1) {+ entered.countDown();+ awaitLatch(release);+ }+ })) {+ queue.submit("hot");+ assertTrue(entered.await(2, TimeUnit.SECONDS));+ queue.submit("hot");+ queue.submit("cold");+ release.countDown();+ await().atMost(Duration.ofSeconds(2)).until(() -> queue.snapshot().completed() == 3);+ assertEquals(List.of("hot", "cold", "hot"), runs);+ } finally {+ release.countDown();+ }+ }++ @Test+ void failureDoesNotStrandTheQueue() {+ AtomicInteger runs = new AtomicInteger();+ try (KeyedWorkQueue<String> queue = new KeyedWorkQueue<>("failure-test", 1, 2, key -> {+ if (runs.incrementAndGet() == 1) {+ throw new IllegalStateException("expected failure");+ }+ })) {+ queue.submit("first");+ queue.submit("second");+ await().atMost(Duration.ofSeconds(2)).until(() -> queue.snapshot().completed() == 2);+ assertEquals(1, queue.snapshot().failures());+ assertEquals(0, queue.snapshot().keys());+ }+ }++ @Test+ void closeInterruptsActiveWorkAndDiscardsQueuedWork() throws Exception {+ CountDownLatch entered = new CountDownLatch(1);+ CountDownLatch interrupted = new CountDownLatch(1);+ AtomicInteger runs = new AtomicInteger();+ KeyedWorkQueue<String> queue = new KeyedWorkQueue<>("close-test", 1, 2, key -> {+ runs.incrementAndGet();+ entered.countDown();+ try {+ new CountDownLatch(1).await();+ } catch (InterruptedException expected) {+ interrupted.countDown();+ Thread.currentThread().interrupt();+ }+ });+ try {+ queue.submit("active");+ assertTrue(entered.await(2, TimeUnit.SECONDS));+ queue.submit("queued");+ queue.close();+ assertTrue(interrupted.await(2, TimeUnit.SECONDS));+ assertFalse(queue.submit("late"));+ await().atMost(Duration.ofSeconds(2)).until(() -> queue.snapshot().active() == 0);+ assertEquals(1, runs.get());+ assertEquals(0, queue.snapshot().keys());+ } finally {+ queue.close();+ }+ }++ private static void awaitLatch(CountDownLatch latch) {+ try {+ assertTrue(latch.await(5, TimeUnit.SECONDS));+ } catch (InterruptedException interrupted) {+ Thread.currentThread().interrupt();+ }+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignalTest.java b/src/test/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignalTest.javanew file mode 100644index 0000000000..e0766c4598--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/core/common/concurrent/VersionedSignalTest.java@@ -0,0 +1,80 @@+package io.github.hectorvent.floci.core.common.concurrent;++import org.junit.jupiter.api.Test;++import java.time.Duration;+import java.util.ArrayList;+import java.util.List;+import java.util.concurrent.CountDownLatch;+import java.util.concurrent.ExecutorService;+import java.util.concurrent.Executors;+import java.util.concurrent.Future;+import java.util.concurrent.TimeUnit;++import static org.junit.jupiter.api.Assertions.*;++class VersionedSignalTest {+ @Test+ void notificationBetweenReadingStateAndParkingIsRetained() throws Exception {+ VersionedSignal signal = new VersionedSignal();+ long observed = signal.version();+ signal.signal();+ try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {+ Future<Boolean> wait = executor.submit(() -> signal.awaitChange(observed, TimeUnit.SECONDS.toNanos(20)));+ assertTrue(wait.get(1, TimeUnit.SECONDS));+ }+ }++ @Test+ void aChangeReleasesEveryWaiterIncludingLateRegistrations() throws Exception {+ VersionedSignal signal = new VersionedSignal();+ long observed = signal.version();+ CountDownLatch entering = new CountDownLatch(16);+ try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {+ List<Future<Boolean>> waiters = new ArrayList<>();+ for (int i = 0; i < 16; i++) {+ waiters.add(executor.submit(() -> {+ entering.countDown();+ return signal.awaitChange(observed, TimeUnit.SECONDS.toNanos(20));+ }));+ }+ assertTrue(entering.await(2, TimeUnit.SECONDS));+ signal.signal();+ for (Future<Boolean> waiter : waiters) {+ assertTrue(waiter.get(2, TimeUnit.SECONDS));+ }+ }+ }++ @Test+ void anUnchangedVersionWaitsForItsDeadline() throws Exception {+ VersionedSignal signal = new VersionedSignal();+ long started = System.nanoTime();+ assertFalse(signal.awaitChange(signal.version(), Duration.ofMillis(30).toNanos()));+ assertTrue(System.nanoTime() - started >= Duration.ofMillis(30).toNanos());+ }++ @Test+ void interruptionReleasesTheWaiterWithoutPublishingAChange() throws Exception {+ VersionedSignal signal = new VersionedSignal();+ CountDownLatch entering = new CountDownLatch(1);+ CountDownLatch interrupted = new CountDownLatch(1);+ Thread waiter = Thread.ofVirtual().start(() -> {+ entering.countDown();+ try {+ signal.awaitChange(signal.version(), TimeUnit.SECONDS.toNanos(20));+ } catch (InterruptedException expected) {+ interrupted.countDown();+ }+ });+ try {+ assertTrue(entering.await(2, TimeUnit.SECONDS));+ waiter.interrupt();+ assertTrue(interrupted.await(2, TimeUnit.SECONDS));+ assertEquals(0, signal.version());+ } finally {+ waiter.interrupt();+ waiter.join(2000);+ }+ }+}