Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.yml
index 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.md
diff --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.java
new file mode 100644
index 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.java
new file mode 100644
index 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.java
new file mode 100644
index 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.java
new file mode 100644
index 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);
+ }
+ }
+}