diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dbcbf5cc5..9b5b47978 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,6 +50,8 @@ jobs: run: python -c "from tools.build_mod import benchmark_workers; benchmark_workers()" - name: Measure isolated debounce queue polling run: python -c "from tools.build_mod import benchmark_debounce; benchmark_debounce()" + - name: Measure wakeable idle queue latency + run: python -c "from tools.build_mod import benchmark_idle; benchmark_idle()" - name: Measure object allocations with compact headers off and on run: python -c "from tools.build_mod import benchmark_headers; benchmark_headers()" - name: Test pack integrity and comparisons @@ -63,4 +65,5 @@ jobs: dist/horizon-lab-*.jar dist/worker-pacing-benchmark.txt dist/debounce-queue-benchmark.txt + dist/idle-queue-benchmark.txt dist/object-header-benchmark.txt diff --git a/README.md b/README.md index dfe28d336..7e254bafb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Client-first performance research for Minecraft Java **26.3**, preserving vanill ## Play on your Mac -Download **horizon-mac-starter-0.8.0.zip** from [Releases](https://github.com/ludovic111/minecraft-optimization-lab/releases), extract it and open `Mac-Start.command`. It verifies and installs official universal Prism Launcher in `~/Applications` if needed, then opens the balanced pack import. Sign into Microsoft **inside Prism yourself**. This project needs no credentials. +Download **horizon-mac-starter-0.9.0.zip** from [Releases](https://github.com/ludovic111/minecraft-optimization-lab/releases), extract it and open `Mac-Start.command`. It verifies and installs official universal Prism Launcher in `~/Applications` if needed, then opens the balanced pack import. Sign into Microsoft **inside Prism yourself**. This project needs no credentials. Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on your 16 GB M2 Pro. Prism can download Java automatically. Start at 1280×800 or 1920×1200; full Retina resolution is a larger GPU workload. [START-HERE.txt](packs/START-HERE.txt) has details. The same `.mrpack` files import into Prism on Windows and Linux. @@ -30,6 +30,10 @@ Distant LOD is simplified terrain. Nearby blocks retain full detail. Initial gen The optional `queue-wait` pack yields during pending distant-terrain debounce retries; `adaptive-queue` combines it with the existing controllers. [Queue experiment and measurement limits](docs/debounce-queue.md). +Version 0.9 also makes the queue's idle wait wakeable for incoming work, preserving +its debounce rules and bounded cache-maintenance cadence. It remains part of the +optional queue profiles, with separate wake-latency measurements. + Version 0.8 fixes a fresh-instance graphics preset that could override the selected render distance. It also records actual GC/header settings and supports an optional [compact object headers experiment](docs/compact-headers.md) for Java 25; packs diff --git a/docs/debounce-queue.md b/docs/debounce-queue.md index 29822bede..dee0e1d26 100644 --- a/docs/debounce-queue.md +++ b/docs/debounce-queue.md @@ -13,8 +13,10 @@ settings, mods and worker budgets. Its original hook performs the existing debounce reinsertion, then requests a wait of up to 1 ms, bounded by the remaining deadline, if no preprocessing work is pending. It only waits on the queue worker, never a caller such as the render thread. Incoming queued work unparks a debounce -wait; the original empty-queue sleep remains unchanged. OS scheduling determines -when the worker resumes. +wait. Starting with 0.9, incoming work can also wake an empty queue's idle wait, +which previously slept for 50 ms. The idle park ends by the next 50 ms cache +maintenance deadline; early wakeups do not trigger maintenance more often than +that cadence. OS scheduling determines when the worker resumes. The same update object, priority queue, debounce timestamp, overload policy, executor dispatch and normal simulation remain in use. Executor-unavailable and rejected-dispatch retries are outside this hook. @@ -27,12 +29,33 @@ Set `enabled=false` in `config/horizon-queue-wait.properties` and restart to disable the queue hook. It is disabled by default and requires exact DH 3.3.4. Requested waits are not hard latency bounds: operating-system timers can -overshoot, and arrival/worker scheduling affect responsiveness. Parking leaves -the interruption flag intact, so the existing shutdown loop still handles it. +overshoot, and arrival/worker scheduling affect responsiveness. Debounce parking +leaves the interruption flag intact, so the existing shutdown loop handles it. +The wakeable idle wait throws with a cleared interrupt flag, as `Thread.sleep` +did; the original catch restores the flag and exits on the next loop check. New arrival wakeups reduce the chance of delaying useful preprocessing, but real terrain completion, block-change visibility and platform behavior need evaluation alongside CPU, allocations and frame pacing. +## Idle wakeup experiment in 0.9 + +After building, run +`python -c "from tools.build_mod import benchmark_idle; benchmark_idle()"`. +An actual publisher queue starts empty; synthetic incoming work is published +about 5 ms into an idle interval. Separate upstream-sleep and wakeable-park workers +check the same update identity and empty queue after removal. Four warm-up pairs +precede 20 alternating measured pairs. Output reports actual arrival time and +publication-start-to-pop latency. Local Linux medians were 45.181 ms upstream and +0.199 ms wakeable; hosted platform results are recorded after CI finishes. + +This isolates idle wakeup, including enqueue/pop overhead. It does not simulate +the existing 250 ms debounce, preprocessing, chunk generation, meshing, network +delivery or a visible block update. Those delays remain separate. OS scheduling +can change latency; this is not an FPS measurement or a hard responsiveness bound. +Concurrency tests cover arrival before park, arrival while parked, pending +interrupts and interruption while parked. The runtime hook still requires exact +DH 3.3.4 and is enabled only with the existing queue experiment. + ## Isolated measurement Run `python -c "from tools.build_mod import benchmark_debounce; benchmark_debounce()"` diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/budget/WakeableIdleWait.java b/mods/horizon-lab/src/main/java/dev/horizonlab/budget/WakeableIdleWait.java new file mode 100644 index 000000000..13c229ccc --- /dev/null +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/budget/WakeableIdleWait.java @@ -0,0 +1,15 @@ +package dev.horizonlab.budget; + +import java.util.concurrent.locks.LockSupport; + +/** A bounded idle park, preserving Thread.sleep's InterruptedException/cleared-flag contract. */ +public final class WakeableIdleWait { + private WakeableIdleWait() { } + + public static void pause(Object blocker, long nanoseconds) throws InterruptedException { + if (nanoseconds < 0) throw new IllegalArgumentException("Negative idle wait"); + if (Thread.interrupted()) throw new InterruptedException(); + LockSupport.parkNanos(blocker, nanoseconds); + if (Thread.interrupted()) throw new InterruptedException(); + } +} diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java b/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java index 3e15482b9..cf77c88f6 100644 --- a/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java @@ -93,6 +93,7 @@ public final class HorizonClient implements ClientModInitializer { context.put("adaptive_budget_enabled", terrainBudget != null); context.put("precise_worker_pacing", dev.horizonlab.mixin.HorizonMixinPlugin.workerPacingEnabled()); context.put("debounce_queue_wait", dev.horizonlab.mixin.HorizonMixinPlugin.debounceWaitEnabled()); + context.put("wakeable_idle_wait", dev.horizonlab.mixin.HorizonMixinPlugin.debounceWaitEnabled()); context.put("adaptive_target_fps", targetFps); context.put("render_distance", client.options.renderDistance().get()); context.put("simulation_distance", client.options.simulationDistance().get()); diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhDebounceWaitMixin.java b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhDebounceWaitMixin.java index 8cf455126..6fe5b6de9 100644 --- a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhDebounceWaitMixin.java +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhDebounceWaitMixin.java @@ -5,6 +5,7 @@ import com.seibel.distanthorizons.core.api.internal.chunkUpdating.ChunkUpdateDat import com.seibel.distanthorizons.core.api.internal.chunkUpdating.ChunkUpdateQueueManager; import com.seibel.distanthorizons.core.pos.DhChunkPos; import dev.horizonlab.budget.DebounceWait; +import dev.horizonlab.budget.WakeableIdleWait; import java.util.concurrent.locks.LockSupport; import org.spongepowered.asm.mixin.Final; import org.spongepowered.asm.mixin.Mixin; @@ -21,10 +22,12 @@ import org.spongepowered.asm.mixin.injection.callback.CallbackInfo; public abstract class DhDebounceWaitMixin { @Shadow @Final public ChunkPosQueue preUpdateQueue; @Unique private volatile Thread horizonQueueWorker; + @Unique private long horizonLastIdleCleanup; @Inject(method = "runQueueingLoop", at = @At("HEAD"), remap = false) private void horizonRememberWorker(CallbackInfo callback) { horizonQueueWorker = Thread.currentThread(); + horizonLastIdleCleanup = System.nanoTime(); } @Inject(method = "runQueueingLoop", at = @At("RETURN"), remap = false) @@ -32,6 +35,28 @@ public abstract class DhDebounceWaitMixin { horizonQueueWorker = null; } + @Redirect(method = "runQueueingLoop", at = @At(value = "INVOKE", + target = "Ljava/lang/Thread;sleep(J)V"), require = 1, allow = 1, remap = false) + private void horizonWakeableIdle(long milliseconds) throws InterruptedException { + if (milliseconds != 50 || Thread.currentThread() != horizonQueueWorker) { + Thread.sleep(milliseconds); + return; + } + long remaining = 50_000_000L - (System.nanoTime() - horizonLastIdleCleanup); + WakeableIdleWait.pause(this, Math.max(0, remaining)); + } + + // Early wakeups must not turn the former 50 ms maintenance cadence into per-arrival work. + @Redirect(method = "runQueueingLoop", at = @At(value = "INVOKE", + target = "Lcom/google/common/cache/Cache;cleanUp()V"), require = 1, allow = 1, remap = false) + private void horizonBoundIdleMaintenance(com.google.common.cache.Cache cache) { + long now = System.nanoTime(); + if (Thread.currentThread() != horizonQueueWorker || now - horizonLastIdleCleanup >= 50_000_000L) { + cache.cleanUp(); + horizonLastIdleCleanup = System.nanoTime(); + } + } + // Ordinal zero is specifically the debounce retry. Executor rejection retries remain unchanged. @Redirect(method = "tryDispatchReadyChunkUpdate", at = @At(value = "INVOKE", target = "Lcom/seibel/distanthorizons/core/api/internal/chunkUpdating/ChunkPosQueue;addItem(Lcom/seibel/distanthorizons/core/pos/DhChunkPos;Lcom/seibel/distanthorizons/core/api/internal/chunkUpdating/ChunkUpdateData;)V", diff --git a/mods/horizon-lab/src/main/resources/fabric.mod.json b/mods/horizon-lab/src/main/resources/fabric.mod.json index 5adc82208..5ad121239 100644 --- a/mods/horizon-lab/src/main/resources/fabric.mod.json +++ b/mods/horizon-lab/src/main/resources/fabric.mod.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, "id": "horizonlab", - "version": "0.8.0", + "version": "0.9.0", "name": "Horizon Lab", "description": "Client frame pacing and server tick measurements for reproducible optimization experiments.", "authors": [ diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/budget/IdleQueueBenchmark.java b/mods/horizon-lab/src/test/java/dev/horizonlab/budget/IdleQueueBenchmark.java new file mode 100644 index 000000000..19b2d1038 --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/budget/IdleQueueBenchmark.java @@ -0,0 +1,63 @@ +package dev.horizonlab.budget; + +import com.seibel.distanthorizons.core.api.internal.chunkUpdating.ChunkPosQueue; +import com.seibel.distanthorizons.core.api.internal.chunkUpdating.ChunkUpdateData; +import com.seibel.distanthorizons.core.pos.DhChunkPos; +import java.util.Locale; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.atomic.AtomicReference; +import java.util.concurrent.locks.LockSupport; + +/** Isolates wakeup after synthetic incoming work; does not measure terrain rendering or debounce. */ +public final class IdleQueueBenchmark { + private static void run(boolean wakeable, boolean report, int trial) throws Exception { + var queue = new ChunkPosQueue(); + var update = new ChunkUpdateData(null, null); + var ready = new CountDownLatch(1); + var published = new AtomicLong(); + var idleStarted = new AtomicLong(); + var latency = new AtomicLong(); + var failure = new AtomicReference(); + Thread worker = new Thread(() -> { + try { + idleStarted.set(System.nanoTime()); + ready.countDown(); + while (queue.isEmpty()) { + if (wakeable) WakeableIdleWait.pause(queue, 50_000_000L); + else Thread.sleep(50); + } + var item = queue.popClosest(); + latency.set(System.nanoTime() - published.get()); + if (item != update || queue.getQueuedCount() != 0) + throw new AssertionError("Queued work identity/count changed"); + } catch (Throwable error) { failure.set(error); } + }, "Horizon idle queue benchmark"); + worker.setDaemon(true); + worker.start(); + try { + if (!ready.await(5, TimeUnit.SECONDS)) throw new AssertionError("Worker did not start"); + LockSupport.parkNanos(5_000_000L); + long start = System.nanoTime(); + published.set(start); + queue.addItem(new DhChunkPos(0, 0), update); + if (wakeable) LockSupport.unpark(worker); + worker.join(5_000); + if (worker.isAlive()) throw new AssertionError("Incoming work did not reach worker"); + if (failure.get() != null) throw new AssertionError("Worker failed", failure.get()); + if (latency.get() < 0) throw new AssertionError("Invalid timestamp ordering"); + if (report) System.out.printf(Locale.ROOT, + "mode=%s trial=%d incoming_after_idle_ms=%.3f publication_to_pop_ms=%.3f%n", + wakeable ? "wakeable" : "upstream", trial, (start - idleStarted.get()) / 1e6, latency.get() / 1e6); + } finally { + worker.interrupt(); + worker.join(1_000); + } + } + + public static void main(String[] args) throws Exception { + for (int warmup = 0; warmup < 4; warmup++) { run(false, false, warmup); run(true, false, warmup); } + for (int trial = 0; trial < 20; trial++) { run(false, true, trial); run(true, true, trial); } + } +} diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/budget/WakeableIdleWaitTest.java b/mods/horizon-lab/src/test/java/dev/horizonlab/budget/WakeableIdleWaitTest.java new file mode 100644 index 000000000..9778e07a8 --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/budget/WakeableIdleWaitTest.java @@ -0,0 +1,70 @@ +package dev.horizonlab.budget; + +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import java.util.concurrent.locks.LockSupport; + +public final class WakeableIdleWaitTest { + private static void check(boolean condition, String message) { + if (!condition) throw new AssertionError(message); + } + + private static void workerCase(boolean interrupt, boolean beforePark) throws Exception { + var ready = new CountDownLatch(1); + var proceed = new AtomicBoolean(!beforePark); + var failure = new AtomicReference(); + var completed = new AtomicBoolean(); + Thread worker = new Thread(() -> { + ready.countDown(); + // No blocking operation may consume the early unpark permit before the tested wait. + while (!proceed.get() && !Thread.currentThread().isInterrupted()) Thread.onSpinWait(); + try { + WakeableIdleWait.pause(completed, TimeUnit.SECONDS.toNanos(30)); + check(!interrupt, "Interrupt must throw"); + completed.set(true); + } catch (InterruptedException expected) { + if (!interrupt) failure.set(expected); + else if (Thread.currentThread().isInterrupted()) failure.set(new AssertionError("Throw must clear interrupt status")); + else completed.set(true); + } catch (Throwable error) { failure.set(error); } + }, "Horizon idle-wait test"); + worker.setDaemon(true); + worker.start(); + try { + check(ready.await(5, TimeUnit.SECONDS), "Worker did not start"); + if (!beforePark) { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); + while (worker.getState() != Thread.State.TIMED_WAITING && worker.isAlive() && System.nanoTime() < deadline) + Thread.onSpinWait(); + check(worker.getState() == Thread.State.TIMED_WAITING, "Worker did not park"); + } + if (interrupt) worker.interrupt(); else LockSupport.unpark(worker); + proceed.set(true); + worker.join(5_000); + check(!worker.isAlive(), "Wakeup was lost or shutdown stalled"); + if (failure.get() != null) throw new AssertionError("Worker failed", failure.get()); + check(completed.get(), "Wait did not complete"); + } finally { + proceed.set(true); + worker.interrupt(); + worker.join(1_000); + } + } + + public static void main(String[] args) throws Exception { + Thread.currentThread().interrupt(); + try { + WakeableIdleWait.pause(null, 1_000_000); + throw new AssertionError("Pending interrupt must throw"); + } catch (InterruptedException expected) { + check(!Thread.currentThread().isInterrupted(), "Pending interrupt must be cleared"); + } + workerCase(false, true); // Producer arrived between empty check and park. + workerCase(false, false); // Producer arrived while worker was idle. + workerCase(true, true); + workerCase(true, false); + System.out.println("Wakeable idle-wait arrival races and interruption tests passed."); + } +} diff --git a/packs/START-HERE.txt b/packs/START-HERE.txt index 49abce194..508d0dabe 100644 --- a/packs/START-HERE.txt +++ b/packs/START-HERE.txt @@ -46,6 +46,8 @@ PROFILES retries while a DH update is still inside its existing 250 ms debounce period. Incoming work wakes the queue worker. OS timers can overshoot the requested 1 ms maximum wait; evaluate terrain update latency as well as CPU/FPS. + Version 0.9 also lets incoming work wake an empty queue's former 50 ms sleep. + Cache maintenance keeps its 50 ms cadence; the original debounce stays intact. - adaptive-queue: combines queue-wait with adaptive terrain and precise pacing. For an isolated comparison use queue-wait versus m2-balanced. For the combined controls use adaptive-queue versus adaptive-pacing. Disable the queue hook in diff --git a/packs/mods.lock.json b/packs/mods.lock.json index edc1e9cf1..4805a0c82 100644 --- a/packs/mods.lock.json +++ b/packs/mods.lock.json @@ -3,7 +3,7 @@ "minecraft": "26.3", "java_major": 25, "fabric_loader": "0.19.5", - "pack_version": "0.8.0", + "pack_version": "0.9.0", "options_data_version": 5023, "projects": { "sodium": { diff --git a/tools/Compare-Benchmarks.html b/tools/Compare-Benchmarks.html index 56c619775..29649383d 100644 --- a/tools/Compare-Benchmarks.html +++ b/tools/Compare-Benchmarks.html @@ -100,6 +100,7 @@ function renderDetails(side){ const r=entry.report,fields=[['Profile',r.profile||r.label||'Unlabeled'],['Recording',format(r.elapsed_seconds)+' s · '+format(r.stats.count)+' samples'],['Platform',[r.os,r.architecture].filter(Boolean).join(' ')||'Not captured']]; if(r.kind==='frames')fields.push(['Graphics',[r.gpu,r.graphics_backend].filter(Boolean).join(' · ')||'Not captured'],['Window',number(r.framebuffer_width)?r.framebuffer_width+' × '+r.framebuffer_height:'Not captured'],['Experiments','Adaptive: '+(r.adaptive_budget_enabled?'on':'off')+' · precise pacing: '+(r.precise_worker_pacing?'on':'off')+' · queue wait: '+(r.debounce_queue_wait?'on':'off')]); fields.push(['JVM', 'Compact headers: '+(r.compact_object_headers===true?'on':r.compact_object_headers===false?'off':'not captured')+' · GC: '+(Array.isArray(r.garbage_collectors)?r.garbage_collectors.join(', '):'not captured')]); + fields.push(['Wakeable queue idle', r.wakeable_idle_wait===true?'on':r.wakeable_idle_wait===false?'off':'not captured']); for(const [label,value]of fields)target.append(text('dt',label),text('dd',value)); } async function loadFiles(side,files){ diff --git a/tools/build_mod.py b/tools/build_mod.py index 2bb2a6f1f..894e7297d 100644 --- a/tools/build_mod.py +++ b/tools/build_mod.py @@ -43,6 +43,10 @@ def test_metrics(): SOURCE / "test/java/dev/horizonlab/budget/DebounceWaitTest.java"] subprocess.run(["javac", "--release", "25", "-d", str(destination), *map(str, debounce_sources)], check=True) subprocess.run(["java", "-cp", str(destination), "dev.horizonlab.budget.DebounceWaitTest"], check=True) + idle_sources = [SOURCE / "main/java/dev/horizonlab/budget/WakeableIdleWait.java", + SOURCE / "test/java/dev/horizonlab/budget/WakeableIdleWaitTest.java"] + subprocess.run(["javac", "--release", "25", "-d", str(destination), *map(str, idle_sources)], check=True) + subprocess.run(["java", "-cp", str(destination), "dev.horizonlab.budget.WakeableIdleWaitTest"], check=True) def build(): @@ -167,6 +171,23 @@ def benchmark_headers(): print(output.read_text(), end="") +def benchmark_idle(): + arguments = [json.loads(line) for line in (BUILD / "javac.args").read_text().splitlines()] + classpath = os.pathsep.join([str(BUILD / "classes"), arguments[arguments.index("-classpath") + 1]]) + tests = BUILD / "idle-benchmark" + tests.mkdir(parents=True, exist_ok=True) + subprocess.run(["javac", "--release", "25", "-proc:none", "-cp", classpath, + "-d", str(tests), str(SOURCE / "test/java/dev/horizonlab/budget/IdleQueueBenchmark.java")], check=True) + output = ROOT / "dist/idle-queue-benchmark.txt" + with output.open("w", encoding="utf-8") as report: + report.write(f"Java {subprocess.check_output(['java', '--version'], text=True).splitlines()[0]}\n") + report.write(f"Platform {platform.system()} {platform.release()} {platform.machine()}; logical CPUs {os.cpu_count()}\n") + report.flush() + subprocess.run(["java", "-cp", os.pathsep.join([str(tests), classpath]), + "dev.horizonlab.budget.IdleQueueBenchmark"], stdout=report, check=True) + print(output.read_text(), end="") + + if __name__ == "__main__": parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--test-only", action="store_true")